ORA2SNIPPET_GIF: Details
What It Does
How To Configure It
Credits

## What It Does

ora2snippet_gif generates an html page containing a single large GIF image. The image contains summary information about the event along with record section images of waveforms for the closest available stations for the Event. The page is broken up into three parts: 1)The record section GIF; 2)A link to download the waveforms in SAC; 3)A button allowing the user to delete the event.

### Part 1: The GIF

The GIF is itselft broken into three parts: The Event Header, The Waveform Record Sections, and a Footer displaying the time scale and alignment for the record sections.

The Event Header
The event header contains the following information

- The DB Event ID
- The date/time of the preferred Origin for the Event(UTC)
- The preferred Magnitude for the Event.**
- The Lattitude(in degrees), Longitude(in degrees), and Depth(km) of the preferred Origin
- A WARNING, reminding the user that the GIFs are generated from decimated data.

** Note: The magnitude type is displayed in parenthesis as a number. It is probably not useful in its current format unless you have memorized the magnitude_type codes used by Earthworm.
The Record Sections
The core of the GIF image is the record sections from each station. For each applicable station, a record section is displayed along with header information.

THE RECORD SECTION HEADER
For each station, there is a header displayed, giving information about the station and the record section image. The header currently ranges from 1 to 6 lines based upon the available room. The header includes:

- Line 1: The channel name including (Station, Component, Network).
- Line 2:
  A two character code in RED:
  - The first character is the wave type: (P,S, etc.);
  - The second character is the first motion of the wave ((U)p, (D)own).
  The epicentral distance of the station. (in km)
- Line 3: The Scale of the display. This is essentially the magnification factor used to view the waveform. The waveform is drawn inside a little box; the scale factor describes(inversely) how large that box is in terms of digital counts.
  Scale = MAX_WAVEFORM_COUNTS_FOR_GIVEN_DATATYPE / MAXIMUM_COUNTS_IN_SNIPPET
  For example, suppose the data coming from the station was of type "i4", meaning 4-byte data with Intel aligned byte order. The maximum range for this datatype is (+/-2.1 billion). Now let's say the channel data was generated by a 20-bit A/D. The maximum possible value from that station would be 2**19 = 500k. Each vertical pixel would represent more than 10 million digital counts, and the only thing that would ever be displayed for that record section would be a straight horizontal line, because the counts would never change enough to break out of the one pixel. So there must(unless you want to see all flat lines) be some sort of magnification done when viewing the data. (If you don't believe me, then set "ScaleFactor" = 1 in the config file.) The default behavior is auto-scale, where the program looks at the variance in the data and automagically selects the scale factor that will make the wiggle as large as possible without clipping it at the box boundaries. Auto-scaling is the recommended setting, as it will overcome problems of varying gain and datatypes on channels.
  So, under auto-scaling, if we had 4-byte data from a channel, and the max (de-meaned) value in the snippet was 12347 counts, then the Scale would be set to 2.1 billion / 12347 = 173927. So in the third line of the header, the scale would be written as 173927, and the record section box size would be setup so that it could display +/- 12347 counts.
  If auto-scaling sounds too much like witchcraft or horse-pucky to you, you can set a fixed scale in the config file. (or if you are trying to set the channel gain on multiple stations so that they generate comparable amplitudes, then you can set the Scale to a fixed value for all stations. See "ScaleFactor" in the sample config file.
  Auto-scaling IS the default mode.
- Line 4/5: AmpMax: This is the maximum amplitude in the snippet, where amplitude refers too the largest difference between a Local Max and a Local Min. Given in digital counts.
- Line 6: DEMEANED. All traces are de-meaned before being displayed. If the mean was SIGNIFICANT(last seen, this meant that the mean was more than half the distance between the Max and Min values), then a "DEMEANED" label is written into the header in BLUE.
  Example 1: The max data value in the snippet was 12205, and the min value was -8000, and the mean was 2000. (12205 - (-8000))/2 > 2000, so the de-meaning was insignificant, and no label is written.
  Example 2: The max data value in the snippet was 12205, and the min value was 12000, and the mean was 12100. (12205 - (12000))/2 < 12100, so the de-meaning was SIGNIFICANT, and a DEMEANED label is written.

THE WIGGLES
The wiggles(waveforms) are drawn in BLUE.
Tick marks are drawn in BLACK(the same color as the box border) at the top and bottom of the box.
The time of the "picked" arrival is drawn as a vertical RED line.(if applicable). Wiggles are ALWAYS sorted by EPICENTRAL distance.

The Event Footer
The time scale is printed in RED at the bottom of the GIF. Times are in seconds.

### Part 2: The SAC Link

Below the GIF is a section of the page with a hyperlink. You can click on the link to get a tar'd copy of the SAC directory for the event. The tar file is usually avaialble through anonymous FTP.

### Part 3: The Delete Button

If enabled(the default), a "DELETE EVENT" button, along with a strong warning, will appear in the third section of the page. By pressing this button, you will PERMANENTLY delete the Event from the database.

This button is provided so that users can quickly delete bogus events without having to load Quick Review. It can also be used to inadvertantly delete LARGE, IMPORTANT events. It can also be used to provide entertainment to any hackers or random folks that stumble upon your website. 8)! It can be removed from the page by setting "ShowDeleteButton" to 0 in the config file.

## How To Configure It

Required Parameters
Optional Parameters

- Logging Parameters
- Drawing Parameters
- Other Parameters

ora2snippet_gif was designed to display wiggles(waveforms, record sections) for an Event. It was envisioned that an operator would have multiple copies of ora2snippet_gif running, each using different parameters. The idea was that the configuration for viewing an M2.0 event is most likely not the same configuration you would use for viewing M > 5.0 events.
Each copy of ora2snippet_gif must have a unique name, with a matching config file.
*NOTE* On Solaris, unless you have specifically set your webserver up to follow symbolic-links, you will have to make copies of the ora2snippet_gif executable, or hard-link all of the differntly named programs together.

### Required Parameters

These parameters are required in order for the program to run. You will have to customize them to your setup, however they are global parameters used by all of the Earthworm web/dbms programs, and so you COULD create one file with all of the params, and then just link to it from each config file, with lines like the following
# DB connection params
@../params/db_connect_opts.d

The Database Username, Password, and ServiceID (DBuser, DBpassword, DBservice)
These represent the connection information that the program will use to connect to the Earthworm DBMS. See the documentation on using the Earthworm Database for more information on these parameters.

Webserver Hostname (WebHost)
The name of the machine that you are running these programs on. It will appear in the footer of the page, with a note about comments/problems.

### Optional Parameters

#### LOGGING PARAMETERS

Logfile Directory (Logfiledir)
The directory where the program will write logfiles. The webserver user must have write permission in this directory.
*NOTE: If LogFile is set to 0, this param has no effect.
The default directory is that given by the EW_LOG environment variable.
#Logfiledir /home/earthworm/web/log/

Disk Logfile (LogFile)
Indicate whether a logfile should be written to disk.
0 = FALSE, 1 = TRUE. If set to TRUE, then a logfile will be written to the directory specified by Logfiledir.
#LogFile 1

Module ID (MyModuleId)
Unused. Allows you to specify a ModuleID, which was formerly used in constructing the logfile name.
This param has no effect.
#MyModuleId 1

#### DRAWING PARAMETERS

Width of the GIF Image in Pixels (DisplayWidth)
The width of the GIF image that contains the header information and record section wiggles. The width is given in Pixels. The width of the waveform wiggles will be equal to (DisplayWidth - HeaderWidth).
Range: positive integer values (within reason)
#DisplayWidth 480

Width of the Trace Header in Pixels (HeaderWidth)
The width of the Trace Header portion of the GIF image. The GIF image contains two sections for each waveform trace: the Header and the Waveform Wiggle. The Header section contains the channel name and parametric information, and the Wiggle portion contains a graphical representation of the Waveform. The width of the Wiggle portion is equal to (DisplayWidth - HeaderWidth).
Range: positive integer values (within reason)
#HeaderWidth 60

Height of each Trace Wiggle(TraceHeight)
This is the height of the box, in which each Wiggle is drawn. The height is given in Pixels. The overall height(length) of the GIF image will be "Height of the Event Header" + ("Number of Waveforms Displayed" * TraceHeight) + "Height of Event Footer".
Range: positive integer values (within reason)
#TraceHeight 64

Display Time Duration(DisplayTime)
The length of the display in Seconds after the alignment point. All of the wiggles are aligned in a certain manner, as controlled by the WiggleAlign config parameter. The total duration of the Wiggle box is DisplayTime + (DisplayTime * PreAlgnPcntg), meaning the DisplayTime (after the alignment point) + the display time before the alignment point.
Range: positive integer values (within reason)
#DisplayTime 30

Scaling(magnification) factor(ScaleFactor)
The amount of magnification applied to ALL traces. With a scale factor of 1, the traces are displayed, such that the vertical amplitude of the trace relative to the vertical space allocated for the trace is equal to the relation between the trace values and the maximum possible values of trace with that datatype. Also see the description of Scale inside the description of the Waveform header, at the top of this document.

Example: For a given piece of trace, the max value is 3000, and the min value is -3000. The trace is of datatype 'i2', meaning 2-byte data, so the vertical distance in pixels between the min and the max will be (1500 - (-1500)) * TraceHeight/(64k -1). (64k is the data-range for 2-byte data.) If TraceHeight is 100, then the distance would be 4.577 or ~5 pixels. Since you probably want to utilize more than 4 out of 100 pixels, we invented ScaleFactor, which allows you to magnify the trace relative to the range for its datatype. So if ScaleFactor is 20, max becomes 30000, and min becomes -30000, and thus 90 of 100 pixels are used. ScaleFactor sets the magnification of ALL traces. Because some traces require diffent magnification than others, (low gain, and broadband stations don't mix well with high gain stations) we invented, or atleast implemented autoscaling. By setting ScaleFactor to 0, the program will attempt to determine the "BEST" scale for each station, meaning it will attempt to set the magnification factor such that, as much of the Wiggle box as possible is used to display the trace, without clipping any portion of the waveform.
WARNING: autoscaling can make channels with no activity look noisy, since it will stretch the trace to fit the box, even if there is no activity.
Range: 0 for auto scaling, or any positive integer value less than (2^32) for a fixed scale.
#ScaleFactor 0

Maximum Number of Waveforms to Display (MaxPlots)
The maximum number of waveforms that will be plotted in the GIF for a given event. This parameter allows you to limit the GIF size by just plotting the closest X stations, instead of plotting all stations for an event.
NOTE:Through experimentation, it has been noticed that the GIF images tend to break down when their length gets much over 2000 pixels. It is recommended that (MaxPlots * TraceHeight) <= 2000.
The more wiggles that are drawn, the longer the program will take to run, no matter the height of the Wiggles.
#MaxPlots 20

Number of Tick Marks(NumOfTicks)
The number of tick marks that will be displayed along the top/bottom of each Wiggle box. Tick marks are divide into Large, Medium, and Small, depending on their significance.
Range: positive integer values(within reason). The display will look more symmetrical if the number is divisible by 4.
#NumOfTicks 16

Alignment of Wiggles (WiggleAlign)
The method used to align the waveforms together. Supported methods are:

1. ALIGN_WIGGLE_ON_OT
   Align the waveforms so that they all begin at the Origin Time.
2. ALIGN_WIGGLE_ON_ARRIVAL
Align the waveforms on the arrival time, so that each one begins at it's picked time. If there is no picked Arrival for the channel(in ShowAllWiggles mode), then the waveform is aligned based upon the beginning of the waveform for that channel.
3. ALIGN_WIGGLE_ON_8_KM_PER_SEC
Align the waveforms based upon a velocity reduction method. Align the waveforms so that they each begin at (Origin Time + Epicentral Distance / 8km/sec). This value will be different for each station. With this alignment, the user can tell whether pick times line up base on a constant surface velocity of 8km/sec.
4. ALIGN_WIGGLE_ON_6_KM_PER_SEC
The same as #3 (ALIGN_WIGGLE_ON_8_KM_PER_SEC), except a 6km/sec model is used.

Range: integral values 1 - 4. The default is 1(Origin Time).
#WiggleAlign 1

Display Wiggles without Picked Arrivals(ShowAllWiggles)
A flag indicating whether unpicked waveforms should be displayed. If ShowAllWiggles is not set, then only channels with picked arrivals will be displayed. If ShowAllWiggles is set, then all waveforms, regardless of picked arrival state, will be displayed. This does not directly affect the total number of waveforms displayed, that is controled by MaxPlots.
The default is FALSE. If the param appears in the config file, then it is set to TRUE. No value (such as 1) is required.
#ShowAllWiggles

Waveform Decimation/Drawing Method (WiggleType)
Describes which method will be used to decimate and draw the waveform wiggle in the GIF. These methods are only invoked if data must be decimated, meaning that the number of horizontal pixels available for drawing is less than the number of samples to be drawn. For example: if we are drawing 60 seconds of 100 sample/sec trace, in a wiggle box that is 600 pixels wide, then we will have to draw (60seconds * 100samples-per-sec/600 pixels) = 10 samples/pixel.
The following methods are supported:

1. WIGGLE_TYPE_SINGLE_DATAPOINT
   A middle time value for each pixel is calculated, and the data sample closest to that time value is plotted. Only a single data point from each pixel's time range is plotted. So, if the pixel covered the time range (0.10 - 0.199), then the time 0.15 would be selected and the data value at that time would be selected and drawn.
   This method often misses peaks, and as a result causes wave periods to look long.
2. WIGGLE_TYPE_MAX_DIST
   The waveform (within the pixel's time range) is scanned for max and min values. The value, either min or max, that is furthest from the entire waveform's mean is plotted. So in the same example as above, the waveform would be scanned from 0.10 to 0.199, and max and min values within that time range would be retrieved. If min=-8, max=12, and mean=1.27, then the max data value would be plotted, because it was further away from the mean(10.73) than the min value(9.27). This is an implementation of a method believed to have been developed by Tull@LLNL.
3. WIGGLE_TYPE_DOUBLE_PEAK
   The waveform (within the pixel's time range) is scanned for max and min values. A vertical line is drawn between the min and max values. With this method, all local peaks(min/max) are plotted.
   This method leaves a lot of blue on the screen, if the data is heavily decimated. It tends to look like the wiggles were drawn with a thick felt marker, that is multiple pixels in diameter.
4. WIGGLE_TYPE_HOMEGROWN
   This method is similar to the DOUBLE_PEAK, except that it tries to draw less wiggle fill.
   The waveform (within the pixel's time range) is scanned for max and min values. The opposite of the last value(min/max) is plotted. So if for one pixel, the max is plotted, then for the next pixel, the min would be plotted. And for the pixel after that, the max, and then the min. It keeps oscilating. A caveat is provided to ensure that all of the absolute peaks are drawn. If a max was selected for the last pixel, and the max from this pixel is GREATER THAN that of the last pixel, then a vertical line is drawn from this pixel's Min to it's Max, the way it would be done in the DOUBLE_PEAK method. The same rule applies to Min values, except that the clause is LESS THAN instead of GREATER THAN.
   This method may make the trace look a little nervous, like the person drawing the trace had too much caffine.

The default method is 4(Homegrown).
Range: integral values 1 - 4.
#WiggleType 1

Pre-Alignment Percentage of Trace (PreAlgnPcntg)
This value controls what percentage of the trace appears before the alignment mark. The DisplayTime parameter controls the duration of the trace AFTER the alignment mark. PreAlgnPcntg controls what percentage of that Post-Alignment display time, is additionaly allocated to the Pre-Alignment portion of the display.
For example, if the traces are aligned on Arrival time (WiggleAlign=2), DisplayTime=60, and PreAlgnPcntg=10, then the wiggle boxes, would be drawn such that the wiggles were aligned on arrival time, with 6 seconds prior to the arrival, and 60 seconds after it.
Range: Integral values between 0 and 100, representing a % value.
#PreAlgnPcntg 10

#### OTHER PARAMETERS

Show "Delete Event" Button (ShowDeleteButton)
Controls whether or not a button is displayed at the bottom of the screen, allowing the user to Delete the Event.
See Part 3 of the "What It Does" section above.
NOTE*: By default, the button is enabled.
Range: 1(TRUE), 0(FALSE)
#ShowDeleteButton 1

Debug Flag (Debug)
Controls whether or not debugging information is written to the logfile. If it is set to TRUE, lots of debugging information will be written to the logfile.
Range: 1(TRUE), 0(FALSE)
# Debug 1

## Credits and Misc. Notes

Author: This program was originally developed by LV or DK at Earthworm Central, with supporting blame going to AB and others.
Drawing:
The record sections are drawn and compressed into GIF format using the GD Lib tools developed by Tom Boutell, available at http://www.boutell.com/gd/.
Retreving Information:
ora2snippet_gif uses the EWDB C API to retrieve data for an earthquake from an Earthworm Database.
Webserver:
ora2snippet_gif is meant to be used with a webserver, and as such outputs everything in html. It utilizes GET/POST CGI-BIN variables to maintain state information.