source: git/src/img.h @ 4f70ebc

RELEASE/1.2debug-cidebug-ci-sanitisersstereowalls-data
Last change on this file since 4f70ebc was 4f70ebc, checked in by Olly Betts <olly@…>, 10 years ago

src/: Add new "datestamp_numeric" field to struct img giving the
datestamp as a time_t in UTC (or (time_t)-1 if there's no datestamp
or we failed to convert it). For .3d >= v8, this field is reliable.
We attempt to convert date strings in .3d <= v7 and CMAP XYZ
files, but may get the timezone wrong.

  • Property mode set to 100644
File size: 8.6 KB
Line 
1/* img.h
2 * Header file for routines to read and write Survex ".3d" image files
3 * Copyright (C) Olly Betts 1993,1994,1997,2001,2002,2003,2004,2005,2006,2010,2011,2012,2013,2014
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
18 */
19
20#ifndef IMG_H
21# define IMG_H
22
23/* Define IMG_API_VERSION if you want more recent versions of the img API.
24 *
25 * 0 (default)  The old API.  date1 and date2 give the survey date as time_t.
26 *              Set to 0 for "unknown".
27 * 1            days1 and days2 give survey dates as days since 1st Jan 1900.
28 *              Set to -1 for "unknown".
29 */
30#ifndef IMG_API_VERSION
31# define IMG_API_VERSION 0
32#elif IMG_API_VERSION > 1
33# error IMG_API_VERSION > 1 too new
34#endif
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40#include <stdio.h>
41#include <time.h> /* for time_t */
42
43# define img_BAD   -2
44# define img_STOP  -1
45# define img_MOVE   0
46# define img_LINE   1
47/* NB: img_CROSS is never output and ignored on input.
48 * Put crosses where labels are. */
49/* # define img_CROSS  2 */
50# define img_LABEL  3
51# define img_XSECT  4
52# define img_XSECT_END 5
53# define img_ERROR_INFO 6
54
55/* Leg flags */
56# define img_FLAG_SURFACE   0x01
57# define img_FLAG_DUPLICATE 0x02
58# define img_FLAG_SPLAY     0x04
59
60/* Station flags */
61# define img_SFLAG_SURFACE     0x01
62# define img_SFLAG_UNDERGROUND 0x02
63# define img_SFLAG_ENTRANCE    0x04
64# define img_SFLAG_EXPORTED    0x08
65# define img_SFLAG_FIXED       0x10
66# define img_SFLAG_ANON        0x20
67# define img_SFLAG_WALL        0x40
68
69/* File-wide flags */
70# define img_FFLAG_EXTENDED 0x80
71
72/* When writing img_XSECT, img_XFLAG_END in pimg->flags means this is the last
73 * img_XSECT in this tube:
74 */
75# define img_XFLAG_END      0x01
76
77# define img_STYLE_UNKNOWN   -1
78# define img_STYLE_NORMAL     0
79# define img_STYLE_DIVING     1
80# define img_STYLE_CARTESIAN  2
81# define img_STYLE_CYLPOLAR   3
82# define img_STYLE_NOSURVEY   4
83
84/* 3D coordinates (in metres) */
85typedef struct {
86   double x, y, z;
87} img_point;
88
89typedef struct {
90   /* members you can access when reading (don't touch when writing) */
91   char *label;
92   int flags;
93   char *title;
94   /* Older .3d format versions stored a human readable datestamp string.
95    * Format versions >= 8 versions store a string consisting of "@" followed
96    * by the number of seconds since midnight UTC on 1/1/1970.  Some foreign
97    * formats contain a human readable string, others no date information
98    * (which results in "?" being returned).
99    */
100   char *datestamp;
101   /* The datestamp as a time_t (or (time_t)-1 if not available).
102    *
103    * For 3d format versions >= 8, this is a reliable value and in UTC.  Older
104    * 3d format versions store a human readable time, which img will attempt
105    * to decode, but it may fail, particularly with handling timezones.  Even
106    * if it does work, beware that times in local time where DST applies are
107    * inherently ambiguous around when the clocks go back.
108    *
109    * CMAP XYZ files contain a timestamp.  It's probably in localtime (but
110    * without any timezone information) and the example files are all pre-2000
111    * and have two digit years.  We do our best to turn these into a useful
112    * time_t value.
113    */
114   time_t datestamp_numeric;
115   char separator; /* character used to separate survey levels ('.' usually) */
116#if IMG_API_VERSION == 0
117   time_t date1, date2;
118#else /* IMG_API_VERSION == 1 */
119   int days1, days2;
120#endif
121   double l, r, u, d;
122   /* Error information - valid when IMG_ERROR is returned: */
123   int n_legs;
124   double length;
125   double E, H, V;
126   /* The filename actually opened (e.g. may have ".3d" added). */
127   char * filename_opened;
128   int is_extended_elevation;
129   /* The style of the data - one of the img_STYLE_* constants above */
130   int style;
131
132   /* all other members are for internal use only */
133   FILE *fh;          /* file handle of image file */
134   char *label_buf;
135   size_t buf_len;
136   size_t label_len;
137   int fRead;        /* 1 for reading, 0 for writing */
138   long start;
139   /* version of file format:
140    *  -4 => CMAP .xyz file, shot format
141    *  -3 => CMAP .xyz file, station format
142    *  -2 => Compass .plt file
143    *  -1 => .pos file
144    *   0 => 0.01 ascii
145    *   1 => 0.01 binary,
146    *   2 => byte actions and flags
147    *   3 => prefixes for legs; compressed prefixes
148    *   4 => survey date
149    *   5 => LRUD info
150    *   6 => error info
151    *   7 => more compact dates with wider range
152    *   8 => lots of changes
153    */
154   int version;
155   char *survey;
156   size_t survey_len;
157   int pending; /* for old style text format files and survey filtering */
158   img_point mv;
159#if IMG_API_VERSION == 0
160   time_t olddate1, olddate2;
161#else /* IMG_API_VERSION == 1 */
162   int olddays1, olddays2;
163#endif
164   int oldstyle;
165} img;
166
167/* Which version of the file format to output (defaults to newest) */
168extern unsigned int img_output_version;
169
170/* Minimum supported value for img_output_version: */
171#define IMG_VERSION_MIN 1
172
173/* Maximum supported value for img_output_version: */
174#define IMG_VERSION_MAX 8
175
176/* Open a .3d file for reading
177 * fnm is the filename
178 * Returns pointer to an img struct or NULL
179 */
180#define img_open(F) img_open_survey((F), NULL)
181
182/* Open a .3d file for reading
183 * fnm is the filename
184 * Returns pointer to an img struct or NULL
185 * survey points to a survey name to restrict reading to (or NULL for all
186 * survey data in the file)
187 */
188img *img_open_survey(const char *fnm, const char *survey);
189
190/* Open a .3d file for output
191 * fnm is the filename
192 * title is the title
193 * flags contains a bitwise-or of any file-wide flags - currently only one
194 * is available: img_FFLAG_EXTENDED.  (The third parameter used to be
195 * 'fBinary', but has been ignored for many years, so the parameter has
196 * been repurposed for flags - for this reason, img.c deliberately ignores bit
197 * 1 being set, but callers should be written/updated not to set it).
198 *
199 * Returns pointer to an img struct or NULL for error (check img_error()
200 * for details)
201 */
202img *img_open_write(const char *fnm, char *title, int flags);
203
204/* Read an item from a .3d file
205 * pimg is a pointer to an img struct returned by img_open()
206 * coordinates are returned in p
207 * flags and label name are returned in fields in pimg
208 * Returns img_XXXX as #define-d above
209 */
210int img_read_item(img *pimg, img_point *p);
211
212/* Write a item to a .3d file
213 * pimg is a pointer to an img struct returned by img_open_write()
214 * code is one of the img_XXXX #define-d above
215 * flags is the leg, station, or xsect flags
216 * (meaningful for img_LINE, img_LABEL, and img_XSECT respectively)
217 * s is the label (only meaningful for img_LABEL)
218 * x, y, z are the coordinates
219 */
220void img_write_item(img *pimg, int code, int flags, const char *s,
221                    double x, double y, double z);
222
223/* Write error information for the current traverse
224 * n_legs is the number of legs in the traverse
225 * length is the traverse length (in m)
226 * E is the ratio of the observed misclosure to the theoretical one
227 * H is the ratio of the observed horizontal misclosure to the theoretical one
228 * V is the ratio of the observed vertical misclosure to the theoretical one
229 */
230void img_write_errors(img *pimg, int n_legs, double length,
231                      double E, double H, double V);
232
233/* rewind a .3d file opened for reading so the data can be read in
234 * several passes
235 * pimg is a pointer to an img struct returned by img_open()
236 * Returns: non-zero for success, zero for error (check img_error() for
237 *   details)
238 */
239int img_rewind(img *pimg);
240
241/* Close a .3d file
242 * pimg is a pointer to an img struct returned by img_open() or
243 *   img_open_write()
244 * Returns: non-zero for success, zero for error (check img_error() for
245 *   details)
246 */
247int img_close(img *pimg);
248
249/* Codes returned by img_error */
250typedef enum {
251   IMG_NONE = 0, IMG_FILENOTFOUND, IMG_OUTOFMEMORY,
252   IMG_CANTOPENOUT, IMG_BADFORMAT, IMG_DIRECTORY,
253   IMG_READERROR, IMG_WRITEERROR, IMG_TOONEW
254} img_errcode;
255
256/* Read the error code
257 * If img_open(), img_open_survey() or img_open_write() returns NULL, or
258 * img_rewind() or img_close() returns 0, or img_read_item() returns img_BAD
259 * then you can call this function to discover why.
260 */
261img_errcode img_error(void);
262
263#ifdef __cplusplus
264}
265#endif
266
267#endif
Note: See TracBrowser for help on using the repository browser.