/******************************************************************************* Name: sacio.h Purpose: structure for header of a SAC (Seismic Analysis Code) data file, and prototype for basic SAC I/O Notes: Key to comment flags describing each field: Column 1: R required by SAC (blank) optional Column 2: A = settable from a priori knowledge D = available in data F = available in or derivable from SEED fixed data header T = available in SEED header tables (blank) = not directly available from SEED data, header tables, or elsewhere Problems: none known References: * O'Neill, D. (1987). IRIS Interim Data Distribution Format (SAC ASCII), Version 1.0 (12 November 1987). Incorporated Research Institutions for Seismology, 1616 North Fort Myer Drive, Suite 1440, Arlington, Virginia 22209. 11 pp. * Tull, J. (1987). SAC User's Manual, Version 10.2, October 7, 1987. Lawrence Livermore National Laboratory, L-205, Livermore, California 94550. ??? pp. Language: C, hopefully ANSI standard Author: Dennis O'Neill Revisions: 07/15/88 Dennis O'Neill Initial preliminary release 0.9 11/21/88 Dennis O'Neill Production release 1.0 01/27/91 Lorraine Hwang Header number is now version 6 07/06/93 Xiaoming Ding structure name sac -> sac_head typedef structure to be SACHEAD 12/06/96 Lupei Zhu prototype sacio functions 05/04/13 Dongdong Tian modify headers according to SAC v101.5 *******************************************************************************/ #ifndef _SACIO_H #define _SACIO_H /******************************************************************************* SAC header structure The SAC package is originally implemented in FORTRAN language, and the SAC file format follows the conventions of FORTRAN language. Each character string has a length of 8 bytes (16 bytes for kevnm). While reimplementing SAC in C, an extra byte is needed since C use '\0' to mark the termination of a string to avoid wiping out the contents of the last character. The header structure are needed, one for structure in memory and one for reading/writing header structure from/to disk. While reading a file, first read in the numeric part to the header structure, then read the string part to a temporary buffer, then map strings from buffer to header structure. While writing a file, first write the numeric part from header structure to disk, then map the strings from header structure to temporary buffer, then write the buffer to disk. *******************************************************************************/ typedef struct sac_head { float delta; /* RF increment between evenly spaced samples */ float depmin; /* minimum value of dependent variable */ float depmax; /* maximum value of dependent variable */ float scale; /* amplitude scale factor (not used) */ float odelta; /* Observed increment */ float b; /* RD beginning value of the independent variable */ float e; /* RD ending value of the independent variable */ float o; /* event origin time(seconds wrt reference time)*/ float a; /* 1st arrival time (seconds wrt reference time)*/ float internal1; /* internal use */ float t0; /* user-defined time pick */ float t1; /* user-defined time pick */ float t2; /* user-defined time pick */ float t3; /* user-defined time pick */ float t4; /* user-defined time pick */ float t5; /* user-defined time pick */ float t6; /* user-defined time pick */ float t7; /* user-defined time pick */ float t8; /* user-defined time pick */ float t9; /* user-defined time pick */ float f; /* end time of event, sec > 0 */ float resp0; /* instrument respnse parameter (not used) */ float resp1; /* instrument respnse parameter (not used) */ float resp2; /* instrument respnse parameter (not used) */ float resp3; /* instrument respnse parameter (not used) */ float resp4; /* instrument respnse parameter (not used) */ float resp5; /* instrument respnse parameter (not used) */ float resp6; /* instrument respnse parameter (not used) */ float resp7; /* instrument respnse parameter (not used) */ float resp8; /* instrument respnse parameter (not used) */ float resp9; /* instrument respnse parameter (not used) */ float stla; /* T station latititude (degree, north positive) */ float stlo; /* T station longitude (degree, east positive) */ float stel; /* T station elevation (meters, not used) */ float stdp; /* T station depth (meters, not used) */ float evla; /* event latitude (degree, north positive) */ float evlo; /* event longitude (degree, east positive) */ float evel; /* event elevation (meters, not used) */ float evdp; /* event depth (kilometer, previously meters) */ float mag; /* event magnitude */ float user0; /* User defined variable storage area */ float user1; /* User defined variable storage area */ float user2; /* User defined variable storage area */ float user3; /* User defined variable storage area */ float user4; /* User defined variable storage area */ float user5; /* User defined variable storage area */ float user6; /* User defined variable storage area */ float user7; /* User defined variable storage area */ float user8; /* User defined variable storage area */ float user9; /* User defined variable storage area */ float dist; /* station-event distance (km) */ float az; /* event-station azimuth */ float baz; /* station-event azimuth */ float gcarc; /* station-event great arc length (degrees) */ float internal2; /* internal use */ float internal3; /* internal use */ float depmen; /* mean value of dependent variable */ float cmpaz; /* T component azimuth (degree CW from north) */ float cmpinc; /* T component inclination (degree from vertical)*/ float xminimum; /* minimum value of X (spectral files only) */ float xmaximum; /* maximum value of X (spectral files only) */ float yminimum; /* minimum value of Y (spectral files only) */ float ymaximun; /* maximum value of Y (spectral files only) */ float unused1; /* reserved for future use */ float unused2; /* reserved for future use */ float unused3; /* reserved for future use */ float unused4; /* reserved for future use */ float unused5; /* reserved for future use */ float unused6; /* reserved for future use */ float unused7; /* reserved for future use */ int nzyear; /* F GMT year corresponding to zero time of file */ int nzjday; /* F GMT julia day */ int nzhour; /* F GMT hour */ int nzmin; /* F GMT minite */ int nzsec; /* F GMT second */ int nzmsec; /* F GMT millisecond */ int nvhdr; /* R header version number (6) */ int norid; /* origin ID (CSS 3.0) */ int nevid; /* event ID (CSS 3.0) */ int npts; /* RF number of points per data component */ int internal4; /* internal use */ int nwfid; /* waveform ID (CSS 3.0) */ int nxsize; /* spectral length (spectral files only) */ int nysize; /* spectral width (spectral files only) */ int unused8; /* reserved for future use */ int iftype; /* RA type of file */ int idep; /* type of dependent variable */ int iztype; /* reference time equivalence */ int unused9; /* reserved for future use */ int iinst; /* type of recording instrument (not used) */ int istreg; /* station geographic region (not used) */ int ievreg; /* event geographic region (not used) */ int ievtyp; /* type of event */ int iqual; /* quality of data (not used) */ int isynth; /* synthetic data flag (not used) */ int imagtyp; /* magnitude type */ int imagsrc; /* source of magnitude information */ int unused10; /* reserved for future use */ int unused11; /* reserved for future use */ int unused12; /* reserved for future use */ int unused13; /* reserved for future use */ int unused14; /* reserved for future use */ int unused15; /* reserved for future use */ int unused16; /* reserved for future use */ int unused17; /* reserved for future use */ int leven; /* RA true if data is evenly spaced */ int lpspol; /* station polarity flag (left hand rule) */ int lovrok; /* overwrite permission */ int lcalda; /* true if to calculate distance, azimuth */ int unused18; /* reserved for future use */ char kstnm[9]; /* F station name */ char kevnm[18]; /* event name */ char khole[9]; /* nuclear: hole id; Other: location id; */ char ko[9]; /* event origin time id */ char ka[9]; /* 1st arrival time id */ char kt0[9]; /* time pick 0 id */ char kt1[9]; /* time pick 1 id */ char kt2[9]; /* time pick 2 id */ char kt3[9]; /* time pick 3 id */ char kt4[9]; /* time pick 4 id */ char kt5[9]; /* time pick 5 id */ char kt6[9]; /* time pick 6 id */ char kt7[9]; /* time pick 7 id */ char kt8[9]; /* time pick 8 id */ char kt9[9]; /* time pick 9 id */ char kf[9]; /* end of event id */ char kuser0[9]; /* User defined variable storage area */ char kuser1[9]; /* User defined variable storage area */ char kuser2[9]; /* User defined variable storage area */ char kcmpnm[9]; /* F channel name, three characters */ char knetwk[9]; /* name of seismic network */ char kdatrd[9]; /* date data was read onto computer */ char kinst[9]; /* generic name of recording instrument */ } SACHEAD; /******************************************************************************* SAC Enumerated type Definitions of constants for SAC enumerated data values. undocumented == couldn't find a definition for it (denio, 07/15/88) *******************************************************************************/ #define ITIME 1 /* file: time series data */ #define IRLIM 2 /* file: real&imag spectrum */ #define IAMPH 3 /* file: ampl&phas spectrum */ #define IXY 4 /* file: gen'l x vs y data */ #define IUNKN 5 /* x data: unknown type */ /* zero time: unknown */ /* event type: unknown */ #define IDISP 6 /* x data: displacement (nm) */ #define IVEL 7 /* x data: velocity (nm/sec) */ #define IACC 8 /* x data: accel (cm/sec/sec)*/ #define IB 9 /* zero time: start of file */ #define IDAY 10 /* zero time: 0000 of GMT day*/ #define IO 11 /* zero time: event origin */ #define IA 12 /* zero time: 1st arrival */ #define IT0 13 /* zero time: user timepick 0*/ #define IT1 14 /* zero time: user timepick 1*/ #define IT2 15 /* zero time: user timepick 2*/ #define IT3 16 /* zero time: user timepick 3*/ #define IT4 17 /* zero time: user timepick 4*/ #define IT5 18 /* zero time: user timepick 5*/ #define IT6 19 /* zero time: user timepick 6*/ #define IT7 20 /* zero time: user timepick 7*/ #define IT8 21 /* zero time: user timepick 8*/ #define IT9 22 /* zero time: user timepick 9*/ #define IRADNV 23 /* undocumented */ #define ITANNV 24 /* undocumented */ #define IRADEV 25 /* undocumented */ #define ITANEV 26 /* undocumented */ #define INORTH 27 /* undocumented */ #define IEAST 28 /* undocumented */ #define IHORZA 29 /* undocumented */ #define IDOWN 30 /* undocumented */ #define IUP 31 /* undocumented */ #define ILLLBB 32 /* undocumented */ #define IWWSN1 33 /* undocumented */ #define IWWSN2 34 /* undocumented */ #define IHGLP 35 /* undocumented */ #define ISRO 36 /* undocumented */ #define INUCL 37 /* event type: nuclear shot */ #define IPREN 38 /* event type: nuke pre-shot */ #define IPOSTN 39 /* event type: nuke post-shot*/ #define IQUAKE 40 /* event type: earthquake */ #define IPREQ 41 /* event type: foreshock */ #define IPOSTQ 42 /* event type: aftershock */ #define ICHEM 43 /* event type: chemical expl */ #define IOTHER 44 /* event type: other source */ /* data quality: other problm*/ #define IGOOD 45 /* data quality: good */ #define IGLCH 46 /* data quality: has glitches*/ #define IDROP 47 /* data quality: has dropouts*/ #define ILOWSN 48 /* data quality: low s/n */ #define IRLDTA 49 /* data is real data */ #define IVOLTS 50 /* file: velocity (volts) */ #define IMB 52 /* undocumented */ #define IMS 53 /* undocumented */ #define IML 54 /* undocumented */ #define IMW 55 /* undocumented */ #define IMD 56 /* undocumented */ #define IMX 57 /* undocumented */ #define INEIC 58 /* undocumented */ #define IPDEQ 59 /* undocumented */ #define IPDEW 60 /* undocumented */ #define IPDE 61 /* undocumented */ #define IISC 62 /* undocumented */ #define IREB 63 /* undocumented */ #define IUSGS 64 /* undocumented */ #define IBRK 65 /* undocumented */ #define ICALTECH 66 /* undocumented */ #define ILLNL 67 /* undocumented */ #define IEVLOC 68 /* undocumented */ #define IJSOP 69 /* undocumented */ #define IUSER 70 /* undocumented */ #define IUNKNOWN 71 /* undocumented */ #define IQB 72 /* undocumented */ #define IQB1 73 /* undocumented */ #define IQB2 74 /* undocumented */ #define IQBX 75 /* undocumented */ #define IQMT 76 /* undocumented */ #define IEQ 77 /* undocumented */ #define IEQ1 78 /* undocumented */ #define IEQ2 79 /* undocumented */ #define IME 80 /* undocumented */ #define IEX 81 /* undocumented */ #define INU 82 /* undocumented */ #define INC 83 /* undocumented */ #define IO_ 84 /* undocumented */ #define IL 85 /* undocumented */ #define IR 86 /* undocumented */ #define IT 87 /* undocumented */ #define IU 88 /* undocumented */ #define IEQ3 89 /* undocumented */ #define IEQ0 90 /* undocumented */ #define IEX0 91 /* undocumented */ #define IQC 92 /* undocumented */ #define IQB0 93 /* undocumented */ #define IGEY 94 /* undocumented */ #define ILIT 95 /* undocumented */ #define IMET 96 /* undocumented */ #define IODOR 97 /* undocumented */ #define IOS 103 /* undocumented */ /* True/false definitions */ #undef false #define false 0 #undef true #define true 1 #define SAC_FLOAT_UNDEF (-12345.0) #define SAC_INT_UNDEF (-12345) #define SAC_CHAR8_UNDEF "-12345 " #define SAC_CHAR16_UNDEF "-12345 " /* Format strings for writing headers for SAC ASCII files */ #define FCS "%15.7f%15.7f%15.7f%15.7f%15.7f\n" /* for floats */ #define ICS "%10d%10d%10d%10d%10d\n" /* for integers */ #define CCS1 "%-8.8s%-8.8s%-8.8s\n" /* for strings */ #define CCS2 "%-8.8s%-16.16s\n" /* for strings */ /* Number of floats in the SAC Header */ #define SAC_HEADER_FLOATS 70 /* Number of ints in the SAC Header */ #define SAC_HEADER_INTS 40 /* 15 + 20 + 5 */ /* Number of numeric values in the SAC Header (4 bytes) */ #define SAC_HEADER_NUMBERS ( SAC_HEADER_FLOATS + SAC_HEADER_INTS ) /* Number of strings in the SAC Header (8 or 9 bytes) */ #define SAC_HEADER_STRINGS 24 /* 24 = 23 + 1 */ /* size of integers or floats on disk or in memory * make sure sizeof(float) == 4 && sizeof(int)==4 */ #define SAC_DATA_SIZEOF 4 /* Size of a character string stored on disk for a SAC header */ #define SAC_HEADER_STRING_LENGTH_FILE 8 /* Size of a character string stored in memory for a SAC header */ #define SAC_HEADER_STRING_LENGTH 9 /* Size of floats in the SAC Header */ #define SAC_HEADER_FLOATS_SIZE ( SAC_HEADER_FLOATS * SAC_DATA_SIZEOF ) /* Size of ints in the SAC Header */ #define SAC_HEADER_INTS_SIZE ( SAC_HEADER_INTS * SAC_DATA_SIZEOF ) /* Size of numeric headers on disk */ #define SAC_HEADER_NUMBERS_SIZE ( SAC_HEADER_FLOATS_SIZE + SAC_HEADER_INTS_SIZE ) /* Size of string headers on disk */ #define SAC_HEADER_STRINGS_SIZE ( SAC_HEADER_STRINGS * SAC_HEADER_STRING_LENGTH_FILE ) /* SAC Header Version Number */ #define SAC_HEADER_MAJOR_VERSION 6 /* offset of nvhdr relative to struct SACHEAD */ #define SAC_VERSION_LOCATION 76 /* offset of T0 relative to pointer to struct SACHEAD */ #define TMARK 10 /* offset of USER0 relative to pointer to struct SACHEAD */ #define USERN 40 /* function prototype of basic SAC I/O */ int read_sac_head(const char *name, SACHEAD *hd); float *read_sac(const char *name, SACHEAD *hd); int read_sac_xy(const char *name, SACHEAD *hd, float *xdata, float *ydata); float *read_sac_pdw(const char *name, SACHEAD *hd, int tmark, float t1, float t2); int write_sac(const char *name, SACHEAD hd, const float *ar); int write_sac_xy(const char *name, SACHEAD hd, const float *xdata, const float *ydata); SACHEAD new_sac_head(float dt, int ns, float b0); int sac_head_index(const char *name); int issac(const char *name); #endif /* sacio.h */