src/img.h

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