src/img.h

   1 /* img.h
   2  * Routines for reading and writing 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-2024
  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 # define img_FFLAG_SEPARATOR(CH) (((((int)CH) & 0xff) << 9) | 0x100)
  85
  86 /* When writing img_XSECT, img_XFLAG_END in pimg->flags means this is the last
  87  * img_XSECT in this tube:
  88  */
  89 # define img_XFLAG_END      0x01
  90
  91 # define img_STYLE_UNKNOWN   -1
  92 # define img_STYLE_NORMAL     0
  93 # define img_STYLE_DIVING     1
  94 # define img_STYLE_CARTESIAN  2
  95 # define img_STYLE_CYLPOLAR   3
  96 # define img_STYLE_NOSURVEY   4
  97
  98 /* 3D coordinates (in metres) */
  99 typedef struct {
 100    double x, y, z;
 101 } img_point;
 102
 103 typedef struct {
 104    /* Members you can access when reading (don't touch when writing): */
 105    char *label;
 106    int flags;
 107    char *title;
 108    /* This contains a string describing the coordinate system which the data is
 109     * in, suitable for passing to PROJ.  For a coordinate system with an EPSG
 110     * code this will typically be "EPSG:" followed by the code number.
 111     *
 112     * If no coordinate system was specified then this member will be NULL.
 113     */
 114    char *cs;
 115    /* Older .3d format versions stored a human readable datestamp string.
 116     * Format versions >= 8 versions store a string consisting of "@" followed
 117     * by the number of seconds since midnight UTC on 1/1/1970.  Some foreign
 118     * formats contain a human readable string, others no date information
 119     * (which results in "?" being returned).
 120     */
 121    char *datestamp;
 122    /* The datestamp as a time_t (or (time_t)-1 if not available).
 123     *
 124     * For 3d format versions >= 8, this is a reliable value and in UTC.  Older
 125     * 3d format versions store a human readable time, which img will attempt
 126     * to decode, but it may fail, particularly with handling timezones.  Even
 127     * if it does work, beware that times in local time where DST applies are
 128     * inherently ambiguous around when the clocks go back.
 129     *
 130     * CMAP XYZ files contain a timestamp.  It's probably in localtime (but
 131     * without any timezone information) and the example files are all pre-2000
 132     * and have two digit years.  We do our best to turn these into a useful
 133     * time_t value.
 134     */
 135    time_t datestamp_numeric;
 136    char separator; /* character used to separate survey levels ('.' usually) */
 137
 138    /* Members that can be set when writing: */
 139 #if IMG_API_VERSION == 0
 140    time_t date1, date2;
 141 #else /* IMG_API_VERSION == 1 */
 142    int days1, days2;
 143 #endif
 144    double l, r, u, d;
 145
 146    /* Error information - valid when img_ERROR_INFO is returned: */
 147    int n_legs;
 148    double length;
 149    double E, H, V;
 150
 151    /* The filename actually opened (e.g. may have ".3d" added).
 152     *
 153     * This is only set if img opened the filename - if an existing stream
 154     * is used (via img_read_stream() or similar) then this member will be
 155     * NULL.
 156     */
 157    char * filename_opened;
 158
 159    /* Non-zero if reading an extended elevation: */
 160    int is_extended_elevation;
 161
 162    /* Members that can be set when writing: */
 163    /* The style of the data - one of the img_STYLE_* constants above */
 164    int style;
 165
 166    /* All other members are for internal use only: */
 167    FILE *fh;          /* file handle of image file */
 168    int (*close_func)(FILE*);
 169    char *label_buf;
 170    size_t buf_len;
 171    size_t label_len;
 172    int fRead;        /* 1 for reading, 0 for writing */
 173    long start;
 174    /* version of file format:
 175     *  -4 => CMAP .xyz file, shot format
 176     *  -3 => CMAP .xyz file, station format
 177     *  -2 => Compass .plt file
 178     *  -1 => .pos file
 179     *   0 => 0.01 ascii
 180     *   1 => 0.01 binary,
 181     *   2 => byte actions and flags
 182     *   3 => prefixes for legs; compressed prefixes
 183     *   4 => survey date
 184     *   5 => LRUD info
 185     *   6 => error info
 186     *   7 => more compact dates with wider range
 187     *   8 => lots of changes
 188     */
 189    int version;
 190    char *survey;
 191    size_t survey_len;
 192    /* Used to track state in various ways depending on the format, and also for
 193     * filtering by survey. */
 194    int pending;
 195    img_point mv;
 196 #if IMG_API_VERSION == 0
 197    time_t olddate1, olddate2;
 198 #else /* IMG_API_VERSION == 1 */
 199    int olddays1, olddays2;
 200 #endif
 201    int oldstyle;
 202    /* Pointer to extra data reading some formats requires. */
 203    void *data;
 204 } img;
 205
 206 /* Which version of the file format to output (defaults to newest) */
 207 extern unsigned int img_output_version;
 208
 209 /* Minimum supported value for img_output_version: */
 210 #define IMG_VERSION_MIN 1
 211
 212 /* Maximum supported value for img_output_version: */
 213 #define IMG_VERSION_MAX 8
 214
 215 /* Open a processed survey data file for reading
 216  *
 217  * fnm is the filename
 218  *
 219  * Returns pointer to an img struct or NULL
 220  */
 221 #define img_open(F) img_open_survey((F), NULL)
 222
 223 /* Open a processed survey data file for reading
 224  *
 225  * fnm is the filename
 226  *
 227  * survey points to a survey name to restrict reading to (or NULL for all
 228  * survey data in the file)
 229  *
 230  * Returns pointer to an img struct or NULL
 231  */
 232 img *img_open_survey(const char *fnm, const char *survey);
 233
 234 /* Read processed survey data from an existing stream.
 235  *
 236  * stream is a FILE* open on the stream (can be NULL which will give error
 237  * IMG_FILENOTFOUND so you don't need to handle that case specially).  The
 238  * stream should be opened for reading in binary mode and positioned at the
 239  * start of the survey data file.
 240  *
 241  * close_func is a function to call to close the stream (most commonly
 242  * fclose, or pclose if the stream was opened using popen()) or NULL if
 243  * the caller wants to take care of closing the stream.
 244  *
 245  * filename is used to determine the format based on the file extension,
 246  * and also the leafname with the extension removed is used for the survey
 247  * title for formats which don't support a title or when no title is
 248  * specified.  If you're not interested in default titles, you can just
 249  * pass the extension including a leading "." - e.g. ".3d".  May not be
 250  * NULL.
 251  *
 252  * Returns pointer to an img struct or NULL on error.  Any close function
 253  * specified is called on error (unless stream is NULL).
 254  */
 255 #define img_read_stream(S, C, F) img_read_stream_survey((S), (C), (F), NULL)
 256
 257 /* Read processed survey data from an existing stream.
 258  *
 259  * stream is a FILE* open on the stream (can be NULL which will give error
 260  * IMG_FILENOTFOUND so you don't need to handle that case specially).  The
 261  * stream should be opened for reading in binary mode and positioned at the
 262  * start of the survey data file.
 263  *
 264  * close_func is a function to call to close the stream (most commonly
 265  * fclose, or pclose if the stream was opened using popen()) or NULL if
 266  * the caller wants to take care of closing the stream.
 267  *
 268  * filename is used to determine the format based on the file extension,
 269  * and also the leafname with the extension removed is used for the survey
 270  * title for formats which don't support a title or when no title is
 271  * specified.  If you're not interested in default titles, you can just
 272  * pass the extension including a leading "." - e.g. ".3d".  filename must
 273  * not be NULL.
 274  *
 275  * survey points to a survey name to restrict reading to (or NULL for all
 276  * survey data in the file)
 277  *
 278  * Returns pointer to an img struct or NULL on error.  Any close function
 279  * specified is called on error.
 280  */
 281 img *img_read_stream_survey(FILE *stream, int (*close_func)(FILE*),
 282                             const char *filename,
 283                             const char *survey);
 284
 285 /* Open a .3d file for output with no specified coordinate system
 286  *
 287  * This is a very thin wrapper around img_open_write_cs() which passes NULL for
 288  * cs, provided for compatibility with the API provided before support for
 289  * coordinate systems was added.
 290  *
 291  * See img_open_write_cs() for documentation.
 292  */
 293 #define img_open_write(F, T, S) img_open_write_cs(F, T, NULL, S)
 294
 295 /* Open a .3d file for output in a specified coordinate system
 296  *
 297  * fnm is the filename
 298  *
 299  * title is the title
 300  *
 301  * cs is a string describing the coordinate system, suitable for passing to
 302  * PROJ (or NULL to not specify a coordinate system).  For a coordinate system
 303  * with an assigned EPSG code number, "EPSG:" followed by the code number is
 304  * the recommended way to specify this.
 305  *
 306  * flags contains a bitwise-or of any file-wide flags - currently these are
 307  * available:
 308  *
 309  * img_FFLAG_EXTENDED : this is an extended elevation
 310  * img_FFLAG_SEPARATOR(CHARACTER) : specify the separator character
 311  *              (default: '.')
 312  *
 313  * Returns pointer to an img struct or NULL for error (check img_error()
 314  * for details)
 315  */
 316 img *img_open_write_cs(const char *fnm, const char *title, const char * cs,
 317                        int flags);
 318
 319 /* Write a .3d file to a stream
 320  *
 321  * stream is a FILE* open on the stream (can be NULL which will give error
 322  * IMG_FILENOTFOUND so you don't need to handle that case specially).  The
 323  * stream should be opened for writing in binary mode.
 324  *
 325  * close_func is a function to call to close the stream (most commonly
 326  * fclose, or pclose if the stream was opened using popen()) or NULL if
 327  * the caller wants to take care of closing the stream.
 328  *
 329  * title is the title
 330  *
 331  * cs is a string describing the coordinate system, suitable for passing to
 332  * PROJ (or NULL to not specify a coordinate system).  For a coordinate system
 333  * with an EPSG, "EPSG:" followed by the code number is the recommended way
 334  * to specify this.
 335  *
 336  * flags contains a bitwise-or of any file-wide flags - currently these are
 337  * available:
 338  *
 339  * img_FFLAG_EXTENDED : this is an extended elevation
 340  * img_FFLAG_SEPARATOR(CHARACTER) : specify the separator character
 341  *              (default: '.')
 342  *
 343  * Returns pointer to an img struct or NULL for error (check img_error()
 344  * for details).  Any close function specified is called on error (unless
 345  * stream is NULL).
 346  */
 347 img *img_write_stream(FILE *stream, int (*close_func)(FILE*),
 348                       const char *title, const char * cs, int flags);
 349
 350 /* Read an item from a processed survey data file
 351  *
 352  * pimg is a pointer to an img struct returned by img_open()
 353  *
 354  * coordinates are returned in p
 355  *
 356  * flags and label name are returned in fields in pimg
 357  *
 358  * Returns img_XXXX as #define-d above
 359  */
 360 int img_read_item(img *pimg, img_point *p);
 361
 362 /* Write a item to a .3d file
 363  *
 364  * pimg is a pointer to an img struct returned by img_open_write()
 365  *
 366  * code is one of the img_XXXX #define-d above
 367  *
 368  * flags is the leg, station, or xsect flags
 369  * (meaningful for img_LINE, img_LABEL, and img_XSECT respectively)
 370  *
 371  * s is the label (only meaningful for img_LABEL)
 372  *
 373  * x, y, z are the coordinates
 374  */
 375 void img_write_item(img *pimg, int code, int flags, const char *s,
 376                     double x, double y, double z);
 377
 378 /* Write error information for the current traverse
 379  *
 380  * n_legs is the number of legs in the traverse
 381  *
 382  * length is the traverse length (in m)
 383  *
 384  * E is the ratio of the observed misclosure to the theoretical one
 385  *
 386  * H is the ratio of the observed horizontal misclosure to the theoretical one
 387  *
 388  * V is the ratio of the observed vertical misclosure to the theoretical one
 389  */
 390 void img_write_errors(img *pimg, int n_legs, double length,
 391                       double E, double H, double V);
 392
 393 /* rewind a processed survey data file opened for reading
 394  *
 395  * This is useful if you want to read the data in several passes.
 396  *
 397  * pimg is a pointer to an img struct returned by img_open()
 398  *
 399  * Returns: non-zero for success, zero for error (check img_error() for
 400  *   details)
 401  */
 402 int img_rewind(img *pimg);
 403
 404 /* Close a processed survey data file
 405  *
 406  * pimg is a pointer to an img struct returned by img_open() or
 407  *   img_open_write()
 408  *
 409  * Returns: non-zero for success, zero for error (check img_error() for
 410  *   details)
 411  */
 412 int img_close(img *pimg);
 413
 414 /* Codes returned by img_error */
 415 typedef enum {
 416    IMG_NONE = 0, IMG_FILENOTFOUND, IMG_OUTOFMEMORY,
 417    IMG_CANTOPENOUT, IMG_BADFORMAT, IMG_DIRECTORY,
 418    IMG_READERROR, IMG_WRITEERROR, IMG_TOONEW
 419 } img_errcode;
 420
 421 /* Read the error code
 422  *
 423  * If img_open(), img_open_survey() or img_open_write() returns NULL, or
 424  * img_rewind() or img_close() returns 0, or img_read_item() returns img_BAD
 425  * then you can call this function to discover why.
 426  */
 427 img_errcode img_error(void);
 428
 429 /* Datum codes returned by img_parse_compass_datum_string().
 430  *
 431  * We currently don't handle the following, which appear in the datum list
 432  * in Compass, but there don't seem to be any EPSG codes for UTM with any
 433  * of these:
 434  *
 435  *   Australian 1966
 436  *   Australian 1984
 437  *   Camp Area Astro (Antarctica only)
 438  *   European 1979
 439  *   Hong Kong 1963
 440  *   Oman
 441  *   Ordnance Survey 1936
 442  *   Pulkovo 1942
 443  *   South American 1956
 444  *   South American 1969
 445  */
 446 typedef enum {
 447     img_DATUM_UNKNOWN = 0,
 448     img_DATUM_ADINDAN,
 449     img_DATUM_ARC1950,
 450     img_DATUM_ARC1960,
 451     img_DATUM_CAPE,
 452     img_DATUM_EUROPEAN1950,
 453     img_DATUM_NZGD49,
 454     img_DATUM_HUTZUSHAN1950,
 455     img_DATUM_INDIAN1960,
 456     img_DATUM_NAD27,
 457     img_DATUM_NAD83,
 458     img_DATUM_TOKYO,
 459     img_DATUM_WGS72,
 460     img_DATUM_WGS84
 461 } img_datum;
 462
 463 /* Parse a Compass datum string and return an img_datum code. */
 464 img_datum img_parse_compass_datum_string(const char *s, size_t len);
 465
 466 /* Return a CRS string to pass to PROJ from an img_datum and UTM zone.
 467  *
 468  * utm_zone can be between -60 and -1 (Southern Hemisphere), or 1 and 60
 469  * (Northern Hemisphere).
 470  *
 471  * Where possible a string of the form "EPSG:1234" is returned.
 472  *
 473  * Example Compass files we've seen use "North American 1927" outside of where
 474  * it's defined for use, presumably because some users fail to change the datum
 475  * from Compass' default.  To enable reading such files we return a PROJ4
 476  * string of the form "+proj=utm ..." for "North American 1927" and "North
 477  * American 1983" for UTM zones which don't have an EPSG code.
 478  *
 479  * If no mapping is known NULL is returned.
 480  *
 481  * The returned value is allocated with malloc() and the caller is responsible
 482  * for calling free().
 483  */
 484 char *img_compass_utm_proj_str(img_datum datum, int utm_zone);
 485
 486 #ifdef __cplusplus
 487 }
 488 #endif
 489
 490 #endif