Editing Guide to madagascar programs (section)

==sfsegyread==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Convert a SEG-Y or SU dataset to RSF.
|-
! colspan="4" | sfsegyread mask=msk.rsf > out.rsf tfile=hdr.rsf verb=n su= suxdr=n endian=y format=segyformat (bhead) ns=segyns (bhead) tape= read= hfile= bfile=
|-
|  colspan="4" | <br>Data headers and trace headers are separated from the data.<br><br>"suread" is equivalent to "segyread su=y"<br><br>SEGY key names:<br><br>tracl: trace sequence number within line 0<br><br>tracr: trace sequence number within reel 4<br><br>fldr:     field record number 8 <br><br>tracf:    trace number within field record 12 <br><br>ep:       energy source point number 16 <br><br>cdp:      CDP ensemble number 20 <br><br>cdpt:     trace number within CDP ensemble 24 <br><br>trid:     trace identification code:<br>1 = seismic data<br>2 = dead<br>3 = dummy<br>4 = time break<br>5 = uphole<br>6 = sweep<br>7 = timing<br>8 = water break<br>9---, N = optional use (N = 32,767) 28 <br><br>nvs:      number of vertically summed traces 30 <br><br>nhs:      number of horizontally summed traces 32 <br><br>duse:     data use:<br>1 = production<br>2 = test 34<br><br>offset:   distance from source point to receiver<br>group (negative if opposite to direction<br>in which the line was shot) 36 <br><br>gelev:    receiver group elevation from sea level<br>(above sea level is positive) 40 <br><br>selev:    source elevation from sea level<br>(above sea level is positive) 44 <br><br>sdepth:   source depth (positive) 48 <br><br>gdel:     datum elevation at receiver group 52 <br><br>sdel:     datum elevation at source 56 <br><br>swdep:    water depth at source 60 <br><br>gwdep:    water depth at receiver group 64 <br><br>scalel:   scale factor for previous 7 entries<br>with value plus or minus 10 to the<br>power 0, 1, 2, 3, or 4 (if positive,<br>multiply, if negative divide) 68 <br><br>scalco:   scale factor for next 4 entries<br>with value plus or minus 10 to the<br>power 0, 1, 2, 3, or 4 (if positive,<br>multiply, if negative divide) 70 <br><br>sx:       X source coordinate 72 <br><br>sy:       Y source coordinate 76 <br><br>gx:       X group coordinate 80 <br><br>gy:       Y group coordinate 84 <br><br>counit:   coordinate units code:<br>for previous four entries<br>1 = length (meters or feet)<br>2 = seconds of arc (in this case, the<br>X values are unsigned longitude and the Y values<br>are latitude, a positive value designates<br>the number of seconds east of Greenwich<br>or north of the equator 88 <br><br>wevel:     weathering velocity 90 <br><br>swevel:    subweathering velocity 92 <br><br>sut:       uphole time at source 94 <br><br>gut:       uphole time at receiver group 96 <br><br>sstat:     source static correction 98 <br><br>gstat:     group static correction 100 <br><br>tstat:     total static applied 102 <br><br>laga:      lag time A, time in ms between end of 240-<br>byte trace identification header and time<br>break, positive if time break occurs after<br>end of header, time break is defined as<br>the initiation pulse which maybe recorded<br>on an auxiliary trace or as otherwise<br>specified by the recording system 104 <br><br>lagb:      lag time B, time in ms between the time<br>break and the initiation time of the energy source,<br>may be positive or negative 106 <br><br>delrt:     delay recording time, time in ms between<br>initiation time of energy source and time<br>when recording of data samples begins<br>(for deep water work if recording does not<br>start at zero time) 108 <br><br>muts:      mute time--start 110 <br><br>mute:      mute time--end 112 <br><br>ns:        number of samples in this trace 114 <br><br>dt:        sample interval, in micro-seconds 116 <br><br>gain:      gain type of field instruments code:<br>1 = fixed<br>2 = binary<br>3 = floating point<br>4 ---- N = optional use 118 <br><br>igc:       instrument gain constant 120 <br><br>igi:       instrument early or initial gain 122 <br><br>corr:      correlated:<br>1 = no<br>2 = yes 124<br><br>sfs:       sweep frequency at start 126 <br><br>sfe:       sweep frequency at end 128 <br><br>slen:      sweep length in ms 130 <br><br>styp:      sweep type code:<br>1 = linear<br>2 = cos-squared<br>3 = other 132<br><br>stas:      sweep trace length at start in ms 134 <br><br>stae:      sweep trace length at end in ms 136 <br><br>tatyp:     taper type: 1=linear, 2=cos^2, 3=other 138 <br><br>afilf:     alias filter frequency if used 140 <br><br>afils:     alias filter slope 142 <br><br>nofilf:    notch filter frequency if used 144 <br><br>nofils:    notch filter slope 146 <br><br>lcf:       low cut frequency if used 148 <br><br>hcf:       high cut frequncy if used 150 <br><br>lcs:       low cut slope 152 <br><br>hcs:       high cut slope 154 <br><br>year:      year data recorded 156 <br><br>day:       day of year 158 <br><br>hour:      hour of day (24 hour clock) 160 <br><br>minute:    minute of hour 162 <br><br>sec:       second of minute 164 <br><br>timbas:    time basis code:<br>1 = local<br>2 = GMT<br>3 = other 166<br><br>trwf:      trace weighting factor, defined as 1/2^N<br>volts for the least sigificant bit 168 <br><br>grnors:    geophone group number of roll switch<br>position one 170<br><br>grnofr:    geophone group number of trace one within<br>original field record 172<br><br>grnlof:    geophone group number of last trace within<br>original field record 174<br><br>gaps:      gap size (total number of groups dropped) 176 <br><br>otrav:     overtravel taper code: <br>1 = down (or behind)<br>2 = up (or ahead) 178<br><br>cdpx:   X coordinate of CDP 180<br><br>cdpy:   Y coordinate of CDP 184<br><br>iline:  in-line number 188 <br><br>xline:  cross-line number 192<br><br>shnum:  shotpoint number 196<br><br>shsca:  shotpoint scalar 200<br><br>tval:   trace value meas. 202<br><br>tconst4: transduction const 204<br><br>tconst2: transduction const 208<br><br>tunits:  transduction units 210<br><br>device:  device identifier 212<br><br>tscalar: time scalar 214<br><br>stype:   source type 216<br><br>sendir:  source energy dir. 218<br> <br>unknown: unknown 222<br><br>smeas4:  source measurement 224<br><br>smeas2:  source measurement 228<br><br>smeasu:  source measurement unit 230 <br><br>unass1:  unassigned 232<br><br>unass2:  unassigned 236
|-
| ''string '' || '''bfile=''' ||   || 	output binary data header file
|-
| ''bool   '' || '''endian=y''' ||  [y/n] || 	Whether to automatically estimate endianness or not
|-
| ''int    '' || '''format=segyformat (bhead)''' ||  [1,2,3,5] || 	Data format. The default is taken from binary header.
:1 is IBM floating point
:2 is 4-byte integer
:3 is 2-byte integer
:5 is IEEE floating point
|-
| ''string '' || '''hfile=''' ||   || 	output text data header file
|-
| ''string '' || '''mask=''' ||   || 	optional header mask for reading only selected traces (auxiliary input file name)
|-
| ''int    '' || '''ns=segyns (bhead)''' ||   || 	Number of samples. The default is taken from binary header
|-
| ''string '' || '''read=''' ||   || 	what to read: h - header, d - data, b - both (default)
|-
| ''bool   '' || '''su=''' ||  [y/n] || 	y if input is SU, n if input is SEGY
|-
| ''bool   '' || '''suxdr=n''' ||  [y/n] || 	y, SU has XDR support
|-
| ''string '' || '''tape=''' ||   || 	input data
|-
| ''string '' || '''tfile=''' ||   || 	output trace header file (auxiliary output file name)
|-
| ''bool   '' || '''verb=n''' ||  [y/n] || 	Verbosity flag
|}

The SEG Y format is an [http://en.wikipedia.org/wiki/Open_standard open standard] for the exchange of geophysical data. It is controlled by the non-profit [http://www.seg.org/SEGportalWEBproject/portals/SEG_Online.portal?_nfpb=true&_pageLabel=pg_gen_content&Doc_Url=prod/SEG-Publications/Pub-Yearbook/committees.htm SEG Technical Standards Committee]. There are two versions of this standard: [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev0.pdf rev0] (1975)<ref>Barry, K.M., Cavers, D.A., and Kneale, C.W. 1975. Recommended standards for digital tape formats. ''Geophysics'', '''40''', no. 02, 344–352.</ref> and [http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev1.pdf rev1] (2002)<ref>Norris, M.W., Faichney, A.K., ''Eds''. 2001. SEG Y rev1 Data Exchange format. Society of Exploration Geophysicists, Tulsa, OK, 45 pp.</ref>. The implementation in <tt>sfsegyread</tt> is a mixture of rev0 (i.e. no checks for Extended Textual Headers) and rev1 ([http://en.wikipedia.org/wiki/IEEE_floating-point_standard IEEE floating point format] allowed for trace data samples).

An SEG-Y file, as understood by <tt>sfsegyread</tt>, contains a "Reel Identification Header" (3200 bytes in EBCDIC followed by 400 bytes in a binary encoding), followed by a number of "Trace Blocks." Each "Trace Block" contains a 240-byte "Trace Header" (binary) followed by "Trace Data" -- a sequence of <tt>ns</tt> samples. Binary values in both reel headers and trace headers are two's complement integers, either two bytes or four bytes long. There are no floating-point values defined in the headers. Trace Data samples can have various encodings, either floating point or integer, described further down, but they are all big-endian. To convert from SEG-Y to RSF, <tt>sfsegyread</tt> will strip the tape reel EBCDIC header and convert it to ASCII, will extract the reel binary header without changing it, and will put the trace headers into one RSF file, and the traces themselves on another.

===SEG-Y Trace Headers===
In the SEG-Y standard, only the first 180 bytes of the 240-byte trace header are defined; bytes 181-240 are reserved for non-standard header information, and these locations are increasingly used in modern SEG-Y files and their variants. The standard provides for a total of 71 4-byte and 2-byte predefined header words. These 71 standard words have defined lengths and byte offsets, and only these words and byte locations are read using <tt>segyread</tt> and output to the RSF header file with the <tt>tfile=</tt> option. The user may remap these predefined keywords to different byte offsets.

===SU File Format===
An [http://www.cwp.mines.edu/sututor/node22.html SU file] is nothing more than an SEG-Y file without the reel headers and with the Trace Data samples in the native encoding of the CPU the file was created on (Attention -- limited portability!). So, to convert from SU to RSF, <tt>sfsegyread</tt> will just separate headers and traces into two RSF files. 

===SEG-Y specific parameters===
*<tt>hfile=</tt> specifies the name of the file in which the EBCDIC reel header will be put after conversion to ASCII. If you are certain there is no useful information in it, <tt>hfile=/dev/null</tt> works just fine. If you do not specify anything for this parameter, you will get an ASCII file named <tt>header</tt> in the current directory. If you want to quickly preview this header before running <tt>sfsegyread</tt>, use<pre>dd if=input.segy count=40 bs=80 cbs=80 conv=unblock,ascii</pre>
*<tt>bfile=</tt> specifies the name of the file in which the binary reel header (the 400-byte thing following the 3600-byte EBCDIC) will be put without any conversion. The default name is "binary". Unless you have software that knows how to read exactly this special type of file, it will be completely useless, so do <tt>bfile=/dev/null</tt>
*<tt>format=</tt> specifies the format in which the trace data samples are in the SEG-Y input file. This is read from the binary reel header of the SEG-Y file. Valid values are 1(IBM floating point), 2 (4-byte integer), 3 (2-byte integer), and 5 (IEEE floating point). If the input file is SU, the format will be assumed to be the native <tt>float</tt> format.

*<tt>keyname=</tt> specifies the byte offset to remap a header using the trace header key names shown above. For example, if the CDP locations have been placed in bytes 181-184 instead of the standard 21-24, <tt>cdp=180</tt> will remap the trace header to that location. 

===SU-specific parameters===
*<tt>suxdr=</tt> specifies whether the input file was created with an SU package with XDR support enabled. If you have access to the source code of your SU install (try <tt>$CWPROOT/src</tt>), type: <tt>grep 'XDRFLAG =' $CWPROOT/src/Makefile.config</tt> and look at the last uncommented entry. If no value is given for <tt>XDRFLAG</tt>, the package was not compiled with XDR support.
===Common parameters===
*<tt>su=</tt> specifies if the input file is SU or SEG-Y. The default is <tt>su=n</tt> (SEG-Y file).
*<tt>read=</tt> specifies what parts of the "Trace Blocks" will be read. It can be <tt>read=d</tt> (only trace data is read), <tt>read=h</tt> (only trace headers are read) or <tt>read=b</tt> (both are read).
*<tt>tfile=</tt> gives the name of the RSF file to which trace headers are written. Obviously, it should be only specified with <tt>read=h</tt> or <tt>read=b</tt>.
*<tt>mask=</tt> is an optional parameter specifying the name of a mask that says which traces will be read. The mask is a 1-D RSF file with integers. The number of mask samples is the same as the number of traces in the unmasked SEG-Y. There should be zeros in the mask in places corresponding to unwanted traces.
*<tt>ns=</tt> specifies the number of samples in a trace. For SEG-Y files, the default is taken from the binary reel header, and for SU files, from the header of the first trace. This parameter is, however, critical enough that a command line override was given for it.
*<tt>verbose=</tt> is the verbosity flag. Can be <tt>y</tt> or <tt>n</tt>.
*<tt>endian=</tt> is a y/n flag (default y), specifying whether to estimate automatically or not if samples in the Trace Data blocks are big-endian or little-endian. Try it if you are in trouble and do not know what else to do; otherwise, let the automatic estimation do its job.