Incorporated Research Institutions for Seismology (IRIS) Data Management Center (DMC) Product Team 2014-01-22 This bundle is provided by the IRIS DMC Product Team WITHOUT ANY WARRANTY AND/OR SUPPORT Description: This bundle contains Debi Kilb's MATLAB SeisSound scripts that read an event file and create a SeisSound movie (http://www.iris.edu/dms/products/seissound/data/repository/) based on the parameters provided in the event file and the MATLAB scripts (see the Parameters section for a list). The necessary waveform files are downloaded on-the-fly using IRIS DMC's web services. For more information on SeisSound, visit: http://www.iris.edu/dms/products/seissound. Installation: - make sure that MATLAB is installed on your computer and note your MATLAB installation directory path, hereafter called {MATLAB_DIR} - go to the desired installation directory, hereafter called {INSTALL_DIR} - untar the bundle - the resulting IRIS_DMC_SeisSound, hereafter called {SS_DIR}, folder contains the SeisSound package - the included matTaup package in the bundle requires you to add: {INSTALL_DIR}/IRIS_DMC_SesiSound/matTaup/lib/matTaup.jar to {MATLAB_DIR}/toolbox/local/classpath.txt You could also download the latest matTaup package from: http://www.ess.washington.edu/SEIS/FMI/matTaup.htm - the SeisSound bundle also includes a test event file under the {SS_DIR}/TSD directory. - for customization, edit the "SeisSound_main.m" and the "SeisSound_driver.m" scripts and change their parameters - to produce mp4 format movies, the script uses the "ffmpeg" public package (not provided): see http://www.ffmpeg.org for more information - the necessary waveform data are downloaded using the IRIS DMC web services. Update the included IRIS-WS-x.x.x.jar and its associated irisFetch.m file when a newer version becomes available at http://www.iris.edu/dms/nodes/dmc/manuals/irisfetchm/ Input: Script expects {SS_DIR}/TSD directory to contain event files with necessary parameters: sample event file name: {SS_DIR}/TSD/SEIS_SOUND_1916079 Note: any event file to be processed must be placed under this directory and their name should appear in "{SS_DIR}/bin/filename.dat file" the event file data should contain the event information as follows (optional fields may be left blank): 1916079|2004|12|26|00|58|52|3.4125|95.9012|26.1|ISC|46|705|OFF W COAST OF NORTHERN SUMATERA|ISC|ISC|MW,9.0,HRVD|MW,9.0,HRV|MW,8.2,NEIC|MW,8.2,NEIC|mb,7.0,NEIC|MB,7.0,NEIC the event fields are separated by "|" and are: EVENT_ID|YYYY|MM|DD|HH|MM|SS|LAT|LON|DEPTH|CONTRIBUTOR|REGION_ID|REGION_CODE|REGION_NAME|MAG_TYPE,MAG,MAG_AUTH|MAG_TYPE,MAG,MAG_AUTH|.... EVENT_ID event ID YYYY event year MM event month (2 digits) DD event day (2 digits) HH event hour (2 digits) MM event minute (2 digits) SS event second (2 digits) LAT event latitude (-90/90 degrees) LON event longitude (-180/180 degrees) DEPTH event depth (km) CONTRIBUTORx event authour (not used) REGION_ID event Flinn-Engdahl region ID (not used) REGION_CODE event Flinn-Engdahl region code (not used) REGION_NAME event Flinn-Engdahl region name MAG_TYPE,MAG,MAG_AUTH event magnitude type, value, author MAG_TYPE,MAG,MAG_AUTH event magnitude type, value, author (not used) .... (not used) Running the Script: to start generating SeisSound movie based on the test event: - cd {INSTALL_DIR}/IRIS_DMC_SeisSound/bin - start MATLAB - type the following in the command window: path(path,'../matTaup') javaaddpath('../matTaup/lib/matTaup.jar') javaaddpath('IRIS-WS-2.0.4.jar') - run SeisSound_driver in the command window - Notes: o For each frame MATLAB captures the image on the display screen. If the MATLAB display screen is covered at any time, the covering object will also be captured! o Since MATLAB is using image capture to make movie frames, the actual graphic device resolution will control the final movie quality, color, text size and some graphic elements positioning you may need to tune the script based on your graphic device - once the processing is complete, the movie is created in mpg4 format using ffmpeg package - the following directories under {SS_DIR}/SeisSound_data_products hold files produced for the event Audio - main SeisSound and VCO audio files Events - a copy of the event file Images - a snapshot image of the SeisSound product Movies - SeisSound mpg4 movie Output: The script produces the following output files: {SS_DIR}/SeisSound_data_products/status_report.dat {SS_DIR}/SeisSound_data_products/Audio: 1916079_II_AAK_BHZ_2004_12_26_005852_vco.wav 1916079_II_AAK_BHZ_2004_12_26_005852.wav {SS_DIR}/SeisSound_data_products/Events: 1916079_II_AAK_BHZ_2004_12_26_005852_vco_720.dat {SS_DIR}/SeisSound_data_products/Images: 1916079_II_AAK_BHZ_2004_12_26_005852.jpg {SS_DIR}/SeisSound_data_products/Movies: 1916079_II_AAK_BHZ_2004_12_26_005852_vco_720.mp4 Parameters: Flags that can be toggled on/off in the SeisSound_main.m program. ============================================================================================================= Flag Name Purpose ----------------------------- -------------------------------------------------------------------------------------- iflag_sound Option to save an individual copy of the sound ‘wav’ file. Set to 1 to keep a copy of the wav sound file, set to zero to not save a copy of the wav file. iflag_movie Option to save a movie (set to 1) or not save a movie (set to 0). Sometimes it is handy to set this flag to zero when updating/debugging the program when static images suffice for quality control (i.e., iflag_movie = 0; iflag_image = 1). iflag_image Option to save a sample thumbnail image. Set to 1 to keep a sample thumbnail, set to 0 to not keep a thumbnail image. iflag_phases Option to include seismic phase arrival information (similar to the GMV data product). Set to 1 to include phase arrival information, set to zero to not include phase arrival information. iflag_vco Option to include the voltage controlled oscillator (vco) feature in the sound output. Set to 1 to add the vco feature, 0 otherwise. Caveat: successfully generating the vco sound requires also setting iflag_movie = 1. iflag_stereo Allows for stereo sound instead of mono sound. Set to 1 for stereo sound, set to 0 for mono sound. iflag_largescale Option to generate a large size movie (800x900) in addition creating a movie the size requested by the user through the “movie_height” parameter. Set to 1 to also generate a large-scale movie (800x900), set to zero not to generate an additional large-scale movie. Matlab programs used to create the SeisSound data product and a short description of each program’s purpose. ============================================================================================================= Program Name Purpose ----------------------------- -------------------------------------------------------------------------------------- SeisSound_driver.m Feeds requested data, station (more than one station can be specified), chan information into SeisSound_main SeisSound_main.m Retrieves the data and creates a metadata structure of associated information. SeisSound_IRIS.m Produces individual images, the sound file and creates the final movie (or other requested data products such as a sample thumb-nail image). VCO_seismogram.m Creates the voltage controlled oscillator (vco) sound file (if requested). caseconvert.m To convert text from all capitals to sentence case capitalization epoch.m Converts year, day, hour, min, sec to epochal time. Copyright (C) 2011 Product Team, IRIS Data Management Center. eqfiltfilt.m Function to perform a butterworth filter. geoc4.m Converts from a geographic colatitude to geocentric. Copyright (C) 2011 Product Team, IRIS Data Management Center. irisFetch.m Function that allows seamless access to data stored within the IRIS-DMC. Copyright (C) 2012 Product Team, IRIS Data Management Center. jday.m Converts yr,month, day to day-of-year. Copyright (C) 2011 Product Team, IRIS Data Management Center. linex.m Add a horizontal line time indicator seismogram and spectrogam images. mono2stereo.m Convert a mono wav file to a stereo wav file smooth_envelope.m Provides a smoothed envelope of the input seismogram using a Hilbert transform. This routine is used when generating VCO sound files. stadis2.m To compute the distance and azimuth between two geographic locations. Copyright (C) 2011 Product Team, IRIS Data Management Center. stereo2mono.m Convert a stereo wav file to a mono wave file (not used in this release). sub_phases.m To add markers that indicate the arrival of different seismic phases (similar to the IRIS GMV data product) taupTime.m Calculates travel times using the TauP toolkit. taup.m Invokes the TauP GUI program taupPath.m Calculates ray paths using the TauP toolkit taupPierce.m Calculate points where specified rays pierce discontinuities (not used in this release).