src/img.h

   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,2016,2018
   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
  37 extern "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 /* Loop closure information for the *preceding* traverse (img_MOVE + one or
  54  * more img_LINEs). */
  55 # define img_ERROR_INFO 6
  56
  57 /* Leg flags */
  58 # define img_FLAG_SURFACE   0x01
  59 # define img_FLAG_DUPLICATE 0x02
  60 # define img_FLAG_SPLAY     0x04
  61
  62 /* Station flags */
  63 # define img_SFLAG_SURFACE     0x01
  64 # define img_SFLAG_UNDERGROUND 0x02
  65 # define img_SFLAG_ENTRANCE    0x04
  66 # define img_SFLAG_EXPORTED    0x08
  67 # define img_SFLAG_FIXED       0x10
  68 # define img_SFLAG_ANON        0x20
  69 # define img_SFLAG_WALL        0x40
  70
  71 /* File-wide flags */
  72 # define img_FFLAG_EXTENDED 0x80
  73
  74 /* When writing img_XSECT, img_XFLAG_END in pimg->flags means this is the last
  75  * img_XSECT in this tube:
  76  */
  77 # define img_XFLAG_END      0x01
  78
  79 # define img_STYLE_UNKNOWN   -1
  80 # define img_STYLE_NORMAL     0
  81 # define img_STYLE_DIVING     1
  82 # define img_STYLE_CARTESIAN  2
  83 # define img_STYLE_CYLPOLAR   3
  84 # define img_STYLE_NOSURVEY   4
  85
  86 /* 3D coordinates (in metres) */
  87 typedef struct {
  88    double x, y, z;
  89 } img_point;
  90
  91 typedef struct {
  92    /* Members you can access when reading (don't touch when writing): */
  93    char *label;
  94    int flags;
  95    char *title;
  96    /* If the coordinate system was specified, this contains a PROJ4 string
  97     * describing it.  If not, this member will be NULL.
  98     */
  99    char *cs;
 100    /* Older .3d format versions stored a human readable datestamp string.
 101     * Format versions >= 8 versions store a string consisting of "@" followed
 102     * by the number of seconds since midnight UTC on 1/1/1970.  Some foreign
 103     * formats contain a human readable string, others no date information
 104     * (which results in "?" being returned).
 105     */
 106    char *datestamp;
 107    /* The datestamp as a time_t (or (time_t)-1 if not available).
 108     *
 109     * For 3d format versions >= 8, this is a reliable value and in UTC.  Older
 110     * 3d format versions store a human readable time, which img will attempt
 111     * to decode, but it may fail, particularly with handling timezones.  Even
 112     * if it does work, beware that times in local time where DST applies are
 113     * inherently ambiguous around when the clocks go back.
 114     *
 115     * CMAP XYZ files contain a timestamp.  It's probably in localtime (but
 116     * without any timezone information) and the example files are all pre-2000
 117     * and have two digit years.  We do our best to turn these into a useful
 118     * time_t value.
 119     */
 120    time_t datestamp_numeric;
 121    char separator; /* character used to separate survey levels ('.' usually) */
 122
 123    /* Members that can be set when writing: */
 124 #if IMG_API_VERSION == 0
 125    time_t date1, date2;
 126 #else /* IMG_API_VERSION == 1 */
 127    int days1, days2;
 128 #endif
 129    double l, r, u, d;
 130
 131    /* Error information - valid when img_ERROR_INFO is returned: */
 132    int n_legs;
 133    double length;
 134    double E, H, V;
 135
 136    /* The filename actually opened (e.g. may have ".3d" added).
 137     *
 138     * This is only set if img opened the filename - if an existing stream
 139     * is used (via img_read_stream() or similar) then this member will be
 140     * NULL.
 141     */
 142    char * filename_opened;
 143
 144    /* Non-zero if reading an extended elevation: */
 145    int is_extended_elevation;
 146
 147    /* Members that can be set when writing: */
 148    /* The style of the data - one of the img_STYLE_* constants above */
 149    int style;
 150
 151    /* All other members are for internal use only: */
 152    FILE *fh;          /* file handle of image file */
 153    int (*close_func)(FILE*);
 154    char *label_buf;
 155    size_t buf_len;
 156    size_t label_len;
 157    int fRead;        /* 1 for reading, 0 for writing */
 158    long start;
 159    /* version of file format:
 160     *  -4 => CMAP .xyz file, shot format
 161     *  -3 => CMAP .xyz file, station format
 162     *  -2 => Compass .plt file
 163     *  -1 => .pos file
 164     *   0 => 0.01 ascii
 165     *   1 => 0.01 binary,
 166     *   2 => byte actions and flags
 167     *   3 => prefixes for legs; compressed prefixes
 168     *   4 => survey date
 169     *   5 => LRUD info
 170     *   6 => error info
 171     *   7 => more compact dates with wider range
 172     *   8 => lots of changes
 173     */
 174    int version;
 175    char *survey;
 176    size_t survey_len;
 177    int pending; /* for old style text format files and survey filtering */
 178    img_point mv;
 179 #if IMG_API_VERSION == 0
 180    time_t olddate1, olddate2;
 181 #else /* IMG_API_VERSION == 1 */
 182    int olddays1, olddays2;
 183 #endif
 184    int oldstyle;
 185 } img;
 186
 187 /* Which version of the file format to output (defaults to newest) */
 188 extern unsigned int img_output_version;
 189
 190 /* Minimum supported value for img_output_version: */
 191 #define IMG_VERSION_MIN 1
 192
 193 /* Maximum supported value for img_output_version: */
 194 #define IMG_VERSION_MAX 8
 195
 196 /* Open a .3d file for reading
 197  *
 198  * fnm is the filename
 199  *
 200  * Returns pointer to an img struct or NULL
 201  */
 202 #define img_open(F) img_open_survey((F), NULL)
 203
 204 /* Open a .3d file for reading
 205  *
 206  * fnm is the filename
 207  *
 208  * survey points to a survey name to restrict reading to (or NULL for all
 209  * survey data in the file)
 210  *
 211  * Returns pointer to an img struct or NULL
 212  */
 213 img *img_open_survey(const char *fnm, const char *survey);
 214
 215 /* Read processed survey data from an existing stream.
 216  *
 217  * stream is a FILE* open on the stream (can be NULL which will give error
 218  * IMG_FILENOTFOUND so you don't need to handle that case specially).  The
 219  * stream should be opened for reading in binary mode and positioned at the
 220  * start of the survey data file.
 221  *
 222  * close_func is a function to call to close the stream (most commonly
 223  * fclose, or pclose if the stream was opened using popen()) or NULL if
 224  * the caller wants to take care of closing the stream.
 225  *
 226  * filename is used to determine the format based on the file extension,
 227  * and also the leafname with the extension removed is used for the survey
 228  * title for formats which don't support a title or when no title is
 229  * specified.  If you're not interested in default titles, you can just
 230  * pass the extension including a leading "." - e.g. ".3d".  May not be
 231  * NULL.
 232  *
 233  * Returns pointer to an img struct or NULL on error.  Any close function
 234  * specified is called on error (unless stream is NULL).
 235  */
 236 #define img_read_stream(S, C, F) img_read_stream_survey((S), (C), (F), NULL)
 237
 238 /* Read processed survey data from an existing stream.
 239  *
 240  * stream is a FILE* open on the stream (can be NULL which will give error
 241  * IMG_FILENOTFOUND so you don't need to handle that case specially).  The
 242  * stream should be opened for reading in binary mode and positioned at the
 243  * start of the survey data file.
 244  *
 245  * close_func is a function to call to close the stream (most commonly
 246  * fclose, or pclose if the stream was opened using popen()) or NULL if
 247  * the caller wants to take care of closing the stream.
 248  *
 249  * filename is used to determine the format based on the file extension,
 250  * and also the leafname with the extension removed is used for the survey
 251  * title for formats which don't support a title or when no title is
 252  * specified.  If you're not interested in default titles, you can just
 253  * pass the extension including a leading "." - e.g. ".3d".  filename must
 254  * not be NULL.
 255  *
 256  * survey points to a survey name to restrict reading to (or NULL for all
 257  * survey data in the file)
 258  *
 259  * Returns pointer to an img struct or NULL on error.  Any close function
 260  * specified is called on error.
 261  */
 262 img *img_read_stream_survey(FILE *stream, int (*close_func)(FILE*),
 263                             const char *filename,
 264                             const char *survey);
 265
 266 /* Open a .3d file for output with no specified coordinate system
 267  *
 268  * This is a very thin wrapper around img_open_write_cs() which passes NULL for
 269  * cs, provided for compatibility with the API provided before support for
 270  * coordinate systems was added.
 271  *
 272  * See img_open_write_cs() for documentation.
 273  */
 274 #define img_open_write(F, T, S) img_open_write_cs(F, T, NULL, S)
 275
 276 /* Open a .3d file for output in a specified coordinate system
 277  *
 278  * fnm is the filename
 279  *
 280  * title is the title
 281  *
 282  * cs is a PROJ4 string describing the coordinate system (or NULL to not
 283  * specify a coordinate system).
 284  *
 285  * flags contains a bitwise-or of any file-wide flags - currently only one
 286  * is available: img_FFLAG_EXTENDED.
 287  *
 288  * Returns pointer to an img struct or NULL for error (check img_error()
 289  * for details)
 290  */
 291 img *img_open_write_cs(const char *fnm, const char *title, const char * cs,
 292                        int flags);
 293
 294 /* Write a .3d file to a stream
 295  *
 296  * stream is a FILE* open on the stream (can be NULL which will give error
 297  * IMG_FILENOTFOUND so you don't need to handle that case specially).  The
 298  * stream should be opened for writing in binary mode.
 299  *
 300  * close_func is a function to call to close the stream (most commonly
 301  * fclose, or pclose if the stream was opened using popen()) or NULL if
 302  * the caller wants to take care of closing the stream.
 303  *
 304  * title is the title
 305  *
 306  * cs is a PROJ4 string describing the coordinate system (or NULL to not
 307  * specify a coordinate system).
 308  *
 309  * flags contains a bitwise-or of any file-wide flags - currently only one
 310  * is available: img_FFLAG_EXTENDED.
 311  *
 312  * Returns pointer to an img struct or NULL for error (check img_error()
 313  * for details).  Any close function specified is called on error (unless
 314  * stream is NULL).
 315  */
 316 img *img_write_stream(FILE *stream, int (*close_func)(FILE*),
 317                       const char *title, const char * cs, int flags);
 318
 319 /* Read an item from a .3d file
 320  *
 321  * pimg is a pointer to an img struct returned by img_open()
 322  *
 323  * coordinates are returned in p
 324  *
 325  * flags and label name are returned in fields in pimg
 326  *
 327  * Returns img_XXXX as #define-d above
 328  */
 329 int img_read_item(img *pimg, img_point *p);
 330
 331 /* Write a item to a .3d file
 332  *
 333  * pimg is a pointer to an img struct returned by img_open_write()
 334  *
 335  * code is one of the img_XXXX #define-d above
 336  *
 337  * flags is the leg, station, or xsect flags
 338  * (meaningful for img_LINE, img_LABEL, and img_XSECT respectively)
 339  *
 340  * s is the label (only meaningful for img_LABEL)
 341  *
 342  * x, y, z are the coordinates
 343  */
 344 void img_write_item(img *pimg, int code, int flags, const char *s,
 345                     double x, double y, double z);
 346
 347 /* Write error information for the current traverse
 348  *
 349  * n_legs is the number of legs in the traverse
 350  *
 351  * length is the traverse length (in m)
 352  *
 353  * E is the ratio of the observed misclosure to the theoretical one
 354  *
 355  * H is the ratio of the observed horizontal misclosure to the theoretical one
 356  *
 357  * V is the ratio of the observed vertical misclosure to the theoretical one
 358  */
 359 void img_write_errors(img *pimg, int n_legs, double length,
 360                       double E, double H, double V);
 361
 362 /* rewind a .3d file opened for reading so the data can be read in
 363  * several passes
 364  *
 365  * pimg is a pointer to an img struct returned by img_open()
 366  *
 367  * Returns: non-zero for success, zero for error (check img_error() for
 368  *   details)
 369  */
 370 int img_rewind(img *pimg);
 371
 372 /* Close a .3d file
 373  *
 374  * pimg is a pointer to an img struct returned by img_open() or
 375  *   img_open_write()
 376  *
 377  * Returns: non-zero for success, zero for error (check img_error() for
 378  *   details)
 379  */
 380 int img_close(img *pimg);
 381
 382 /* Codes returned by img_error */
 383 typedef enum {
 384    IMG_NONE = 0, IMG_FILENOTFOUND, IMG_OUTOFMEMORY,
 385    IMG_CANTOPENOUT, IMG_BADFORMAT, IMG_DIRECTORY,
 386    IMG_READERROR, IMG_WRITEERROR, IMG_TOONEW
 387 } img_errcode;
 388
 389 /* Read the error code
 390  *
 391  * If img_open(), img_open_survey() or img_open_write() returns NULL, or
 392  * img_rewind() or img_close() returns 0, or img_read_item() returns img_BAD
 393  * then you can call this function to discover why.
 394  */
 395 img_errcode img_error(void);
 396
 397 #ifdef __cplusplus
 398 }
 399 #endif
 400
 401 #endif