1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Using the img library — Survex 1.4.17 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=12dfc556" />
<script src="_static/documentation_options.js?v=91e0adf2"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.htm" />
<link rel="search" title="Search" href="search.htm" />
<link rel="next" title="Mailing List" href="maillist.htm" />
<link rel="prev" title="Bob Thrun’s CMAP" href="cmap.htm" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="using-the-img-library">
<h1>Using the img library<a class="headerlink" href="#using-the-img-library" title="Link to this heading">¶</a></h1>
<p>The code Survex uses to read and write <code class="docutils literal notranslate"><span class="pre">.3d</span></code> files is provided as the
img library which allows it to be reused by other programs which are written
in C, C++ or another language which is able to call C functions.</p>
<p>Using this code means you can take advantage of any revisions to the 3d
file format by simply rebuilding your software with the updated
<code class="docutils literal notranslate"><span class="pre">img.c</span></code> and <code class="docutils literal notranslate"><span class="pre">img.h</span></code>, whereas if you write your own code to parse 3d
files then you’ll have to update it for each revision to the 3d file format.</p>
<p>Using the img library also allows you to read old revisions of the Survex .3d
format and also other processed survey data formats: currently it supports
reading Survex <code class="docutils literal notranslate"><span class="pre">.pos</span></code> files, and processed survey data from <a class="reference external" href="compass.htm#reading-compass-plf-plt">Larry Fish’s
Compass</a> and from <a class="reference external" href="cmap.htm">Bob Thrun’s CMAP</a>).</p>
<p>It also allows reading a subset of the data in a file, restricted by survey
prefix.</p>
<p>If not able to use the img library, parsing text output from <code class="docutils literal notranslate"><span class="pre">dump3d</span></code>
provides many of the same benefits. If you take this approach, you
may find the <code class="docutils literal notranslate"><span class="pre">--legs</span></code> option more convenient as it gives you a <code class="docutils literal notranslate"><span class="pre">LEG</span></code>
line for each leg rather than <code class="docutils literal notranslate"><span class="pre">MOVE</span></code> for the first station in a traverse
then <code class="docutils literal notranslate"><span class="pre">DRAW</span></code> for each subsequent station.</p>
<section id="using-img-in-your-own-code">
<h2>Using img in your own code<a class="headerlink" href="#using-img-in-your-own-code" title="Link to this heading">¶</a></h2>
<p>The expected way to use img is that you copy <code class="docutils literal notranslate"><span class="pre">src/img.c</span></code> and <code class="docutils literal notranslate"><span class="pre">src/img.h</span></code>
into your source tree, and periodically update them (they usually evolve fairly
slowly).</p>
<p>It’s not currently packaged as a separate library for Debian or anywhere else
I’m aware of (there’s a very low number of applications which link to it and
the effort to do that seems more usefully directed; we also don’t
guarantee ABI stability, but it should be upwardly API compatible).</p>
<p>The current img code makes decisions about the availability of standard C
library headers, functions and types based on the C/C++ standard version the
compiler claims to support (via the <code class="docutils literal notranslate"><span class="pre">__STDC_VERSION__</span></code> and <code class="docutils literal notranslate"><span class="pre">__cplusplus</span></code>
macros). In general these tests should be sensible but a bit conservative
(e.g. <code class="docutils literal notranslate"><span class="pre">snprintf()</span></code> was widely supported before it was standardised by C99)
but currently the highest standards tested for are C99 and C++11 and modern
compilers likely default to at least these. If you want more control you can
probe in your build system and define various macros named with a <code class="docutils literal notranslate"><span class="pre">HAVE_</span></code>
prefix - e.g. <code class="docutils literal notranslate"><span class="pre">HAVE_SNPRINTF</span></code> to indicate that <code class="docutils literal notranslate"><span class="pre">snprintf</span></code> is available.</p>
</section>
<section id="api">
<h2>API<a class="headerlink" href="#api" title="Link to this heading">¶</a></h2>
<p>The API is documented by comments in <code class="docutils literal notranslate"><span class="pre">src/img.h</span></code>.</p>
<p>See <code class="docutils literal notranslate"><span class="pre">src/imgtest.c</span></code> for an example program using img as you would from
outside of Survex. Also <code class="docutils literal notranslate"><span class="pre">src/dump3d.c</span></code> shows how to access all the different
types of data returned (that’s using img as it is in the Survex code so has
different <code class="docutils literal notranslate"><span class="pre">#include</span></code> lines, opens the file in a more complex way, and has
Survex-specific translation from img error codes to Survex message numbers
- none of these are relevant for using img outside of Survex).</p>
<p>If anything is unclear, please ask on the mailing list and we can clarify.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.htm">Survex</a></h1>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="intro.htm">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="getstart.htm">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="cmdline.htm">Survex Programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="datafile.htm">Survex data files</a></li>
<li class="toctree-l1"><a class="reference internal" href="svxhowto.htm"><code class="docutils literal notranslate"><span class="pre">.svx</span></code> Cookbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="genhowto.htm">General: How do I?</a></li>
<li class="toctree-l1"><a class="reference internal" href="compass.htm">Larry Fish’s Compass</a></li>
<li class="toctree-l1"><a class="reference internal" href="walls.htm">David McKenzie’s Walls</a></li>
<li class="toctree-l1"><a class="reference internal" href="cmap.htm">Bob Thrun’s CMAP</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Using the img library</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#using-img-in-your-own-code">Using img in your own code</a></li>
<li class="toctree-l2"><a class="reference internal" href="#api">API</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="maillist.htm">Mailing List</a></li>
<li class="toctree-l1"><a class="reference internal" href="future.htm">Future Developments</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.htm">Documentation overview</a><ul>
<li>Previous: <a href="cmap.htm" title="previous chapter">Bob Thrun’s CMAP</a></li>
<li>Next: <a href="maillist.htm" title="next chapter">Mailing List</a></li>
</ul></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.htm" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©1998-2025.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
</div>
</body>
</html>
|
