About

Welcome to SCEC-VDO!

Researchers and interns at the Southern California Earthquake Center (SCEC) have built a seismic data visualization software tool called the SCEC Virtual Display of Objects (SCEC-VDO). Written in Java with the Swing GUI toolkit to create interactive menus and the Visualization Toolkit (VTK) to render 3D content, SCEC-VDO allows for the visualization of 3D earthquake and fault objects on maps and the creation of images and movies for analysis, presentation, and publication.

Explore the sidebar to learn more about SCEC-VDO!

Installation

System Requirements

SCEC-VDO supports the following operating systems:

  • Windows 7, Windows 10 (64-bit)
  • Mac OS X
  • Linux (64-bit)
Memory

Minimum: 8GB RAM
Recommended: 16GB RAM


Installing SCEC-VDO

Install from package

Version 18.9 and installation instructions are coming soon!

Install from GitHub

Note: Screenshots are taken from a Windows computer, but installation process will be identical on Mac OS X and Linux.

To acquire and run the latest version of the SCEC-VDO source code from GitHub, the Eclipse integrated development environment (IDE) is recommended. Install the latest version of the Eclipse IDE here.

Follow the instructions given by the Eclipse installer. Once installed, open Eclipse. You may be prompted to set a workspace. Click "OK" to accept the default Eclipse workspace.

Your screen should appear similar to this:

In the toolbar at the top, click File > Import... An import wizard should appear:

Click the arrow next to the folder icon to the right of Git. Select Projects from Git and click Next.

Select Clone URI and click Next.

In the URI field, enter the web URL for the SCEC-VDO repository: https://github.com/SCECcode/scec-vdo/
The Host and Repository path fields should auto-fill. Click Next.

Here you will be presented with the SCEC-VDO repository branches. Deselect all except for master. Click Next.

Next Eclipse will prompt you with a Local Destination window. If you would like to change where Eclipse will install the SCEC-VDO repository, change the path in the Directory field. Otherwise leave the default path. Click Next.

The repository should now be cloning to your computer. It will take a few minutes. When installation is complete, you should be able to click the Next button.

Click Finish. SCEC-VDO is now installed to your computer!


Running SCEC-VDO

Run from package

Version 18.9 and instructions are coming soon!

Run from Eclipse

In the top left of your Eclipse window, there is a toolbar with a green circle with a play button (outlined in red below).

Click the black arrow directly to the right of the play button. A dropdown menu should appear. These are run configurations for SCEC-VDO.

Select the appropriate run configuration for your operating system. If you have at least 16GB of RAM in the computer you are currently using, select the configuration with LargeMem.
For example, if you were using a Windows computer with 32GB of RAM, you would select SCEC-VDO Windows64 LargeMem. However, if you were using a Mac computer with 8GB of RAM, you would select SCEC-VDO MacOSX.

If it starts successfully, you will see the SCEC-VDO logo splashscreen (as above), signifying that the software is loading. Explore the rest of the documentation to learn more about what SCEC-VDO can do!

Basic Navigation

Menu Options

File offers a number of options: saving the project state, opening a saved project, exporting the 3D viewer as an .obj, .vtk, or .PNG file, publishing the project on the SCEC-VDO web viewer, or safely quitting the SCEC-VDO application.

Display gives access to SCEC-VDO plugins.

Window allows for the resizing of the 3D viewer window. A preset window size can be selected, or a custom window size can be specified.

Render gives access to the Timeline feature.

Help provides a link to this very user manual and the option to toggle on/off the appearance of a startup wizard popup.

Shortcut Toolbar

The shortcut toolbar offers shortcuts to a number of functions. From left to right:

  • Recenter 3D viewer window to default (on California)
  • Zoom in (in 3D viewer window)
  • Zoom out (in 3D viewer window)
  • Save project state
  • Open saved project
  • Focal Point, which represents the center from the user's perspective when activated
3D Viewer

The 3D viewer enables the viewing of data both above and below the Earth's surface at any angle.

Changes through the maps made through plugins are automatically updated on the map.

Interact with the map as follows:

  • To zoom: use scroll wheel or hold and drag right mouse button
  • To translate map: hold and drag middle mouse button (scroll wheel) or hold Shift-left mouse button
  • To rotate (3D): hold and drag left mouse button
  • To rotate (2D): hold and drag Ctrl-left click
Plugin Panel

Plugins allow for the display and manipulation of visual data on the 3D viewer. Each active plugin is represented by a tab in the plugin panel.

Plugins (except the default plugins) can be closed with the X in their respective tab.

Default plugins

Political Boundaries

Political boundaries are the borders between regions.

Navigation

Select the checkbox next to a region to display its political boundaries. To select a region within another region, click the > to the right of it. To return to the parent region, click the < in the top left of the table.

Under United States > California groups of California-specific features are available for display on the map viewer.

For instance, as shown above, selecting California Interstates displays the interstate highways in California. Clicking > allows for the selection of individual features within each of these groups.

Color wheel

Select the color wheel to change the color of the highlighted features/political boundaries. Here California Interstates is highlighted, and the color red was selected. Click Apply to apply your changes.

Search

Use the search bar to filter out a desired region from those listed in the current window.

Graticule

A graticule is a network of lines representing meridians and parallels on a map. In the graticule plugin, the latitude/longitude grid color and dimensions and background color can be modified.

Click the Apply button to see your changes on the map.

Grid Settings

Change the properties of the grid here. Latitude/longitude increments of the grid (default: 1 degree) can be adjusted to preset or custom increments. In addition, grid color (default: gray) and background map color (default: black) can be changed. The appearance of the latitude/longitude labels may also be toggled with the checkbox.

Remember to click the Apply button at the bottom of the window to apply your changes to the map!

Grid Dimensions

Change the dimensions of the grid here. A minimum and maximum longitude and latitude must be set.

Remember to click the Apply button at the bottom of the window to apply your changes to the map!

Drawing Tools

Drawing tools allows for the plotting of labeled points of interest (rendered as cones) on the map.

Each entry in the table at the top represents a point (rendered as a cone) and a label, or "drawing". The buttons outlined in red above offer several drawing modification options:
    Bottom left (select a drawing in the table first):
Toggle drawing visibility | Change color | Edit label text
    Bottom right:
Add a new drawing | Remove a selected drawing

Change cone and label properties by selecting a point in the table and modifying the appropriate values in the text boxes below. In addition, double click a drawing in the table to highlight it in yellow on the map.

Timeline

Timeline

With Timeline, you are able to intuitively animate data over time with key frames, easily navigate camera positions, and represent your data visually through unique animation patterns. The plugin is the graphical interface that controls the overall process to create animated videos and then export that sequence as a MPEG-4 File.

Basic Functionalities of Significant Buttons
Navigation

It can be found in the Render section.

The timeline is an external window, which contains all your open plugins on the left side, as well as the actual window timeline on the right side. There are a total of three important sections to Timeline:
    Key Frames:
For every plugin you have open, it will be displayed on the Timeline along with some useful key frame buttons. These key frames enable the user to transition between positions or toggle data on the map at certain time durations. You can simply insert a Normal key frame by double clicking at a particular time on the top row. If you want to choose any other key frame types for other plugins, click on the button in this section when the time cursor is at the specific time you want that frame to be at.


    Timeline:
This screen is where you will find the time frame, as well as all the key frames you have added in. if you would like to delete a key frame, simply double-click on the one that you want to delete.


    Render Settings:
If you want to change the settings of what kind of rendering you would like, you can change that here.
    Total Time (s):
Changes the total amount of time you would like your rendering to be.
    Frames Per Second:
Simply changes the amount of frames used per each second interval.
    Camera Spline Type:
Adjust the camera spline to alter the transition behavior between position key frames. Default is Cardinal.
    Renderer/Render Quality:
You can choose what format your video renders in. The higher the quality, the larger memory size it will be!
    Custom Render Size:
Checking this box gives you the option to change the resolution of the rendering.

Creating Animations

There are endless possibilities to creating an animation. For this example, we will go step by step to simulate earthquakes on the Earthquake Catalog Plugin.

  1. Make sure that the Earthquake Catalog Plugin is active on the main program, and that you are at the beginning of the Timeline.
  2. Ensure that the catalog that you want from the Earthquake Catalog Plugin to animate is clicked on.
  3. On Timeline, click the green button on the Earthquake Catalog Plugin row. This is known as the Range Key Frame. A window will pop up for the duration. We will put 10, indicating that it will run for a total of ten seconds.
  4. Simply click on the Yellow button on the Camera row. This is known as a Normal Key Frame that records the placement of the camera on the main program's map.
  5. Go back to the main window, and move the map holding your left mouse button as you zoom in to a specific location on the map and stop.
  6. Go back to the Timeline and add another Normal Key Frame, which will add another key frame on top of your previous. Simply click and hold on that yellow key frame and drag it to the ten second mark.
  7. Go to the drawings plugin and add a Text Drawing.
  8. One last time, we will come back to the Timeline, and click on the gray button in the Drawing Tools row. This turns off that plugin's data from that sequence of frames.
  9. Since we want to display this after our rendering is done, we will click on the blue button in the Drawing Tools row, which turns on that plugin's data from that sequence of frames. We will drag that blue key frame until we hit the ten second mark.
  10. You can press the Play button on the top left to view how your animation runs from key frame to key frame, or you can click on the Record button to save it to your local files.

OpenSHA Plugins

Earthquake Simulator Plugin

Earthquake simulations are very important for research, forecasting future events, and to examine certain fault data. Specifically, earthquake simulators replicate seismic activity during an earthquake in order to analyze key characteristics such as aftershocks, foreshocks, amplification, etc.. This plugin specifically allows you to display preloaded or imported fault files, visually filter each by certain characteristics and/or subsections, as well as being able to animate simulations with their corresponding Simulator Event files (which are imported by you, the user).

Navigation

It can be found and opened using the "OpenSHA" section under Display

There are a lot of options to work with, so we will break down all constraints and parameters for the best experience. Please keep in mind that much of this plugin assumes that you, the user, has some prepackaged simulated event files and geometry files from UCERF3, RSQSim, or other compatible sources. The system will let you know if your files are not compatible.


    Min Event Mag To Load:
When loading in a Simulated Event File, there may be unnecessary events that you don’t want the software wasting time downloading. The number you add (between 0.0 to 10.0) forces the system to load up only events that have a minimum magnitude of that value. The default is 7.0.
    Max Catalog Years To Load:
This value is helpful if you have too many years of simulated data, and would like the system to load up a filtered amount. If not touched, the value will be 0.0 but will simply download all the year events by default.


    Geometry File Presets:
SCEC-VDO comes prepackaged with some Geometry files, ready for you to use. These are the files that mainly deal with bringing in fault information from California in order for you to visually see the data however you see fit. Click on one of them to load them in. UCERF3.D3.1.1km.tri.2.flt is an example file from UCERF3, whereas zfault_Deepen.in comes from RSQSim.
    Geometry File:
If you have your own Geometry files, you may load them in using this button. Keep in mind that the software would prefer files of type .flt, .dat, or .in.

If any of your Geometry files loads successfully, all its data will be displayed in tree format underneath Simulator Event Files.


    Filtering Tools:
In order to visualize earthquake data on certain fault sections, SCEC-VDO has provided filtering tools specifically for UCEREF3 and RSQSim Geometry files. These tools parse through the data to roughly reload the Geometry files with only the San Andreas, San Jacinto, Elsinore, and Hayward fault sections across California. This is not a required option, and you may remove any filter by choosing (none selected).


    Simulator Event File:
If you would like to visualize a certain simulation for your fault data, you can load that file here. These simulation files may come from those that end in a .XList extension, and if successful, will be used for one of the present Animations in the Animation Tab.

Underneath these options is where you find a whole other set of tabs to play around with:
    Color:
This tab, once you have a loaded Geometry File, will let you color code your fault data based on certain parameters. These can range from coloring by their strikes, rakes, depth, etc., the list is endless! You may change the scale, as well as whether you include the legend in the rendering or not.


    Display:
This tab, once you have a loaded Geometry File, will allow you to alter the display of the fault data, such as changing their Geometry Type, Surface Type, and Opacity.


    Animation:
This tab, once you have both a compatible Geometry File and Simulator Event File, should allow you to choose between the animations present. Animations run on events (such as earthquakes, slips, etc), where these events are rendered based on what animation you're on.

Using an Animation

Every single Animation will all have the same general layout of parameters that can be manipulated. Specifically, each one corresponds to how the animation will render:
    Prev/Play/Pause/Next:
These buttons allow you to change the position of your current animation.
    ID:
If you know the ID of the event, you may enter it here to go straight to that event.
    Year:
If you want to go to a specific year in the sequence, you may enter it here. There may not be an event on that time and will instead jump to the next event once you start playing.
    Duration(seconds):
This option allows you to change the speed of the animation. The larger the duration, the more events show up, and the better you're able to see said events animate. These are useful for simulations that have events thousands of years apart.
    Animation Type:
Time Based animations occur at the time of the event, where as Evenly Spaced Animations spread the events evenly allowing you to visually differentiate between each one.
    Loop Animation:
If chosen, once you reach the end of the animation, it will simply start at the beginning again.

Using an Animation - Simulator Output Animation: slip (m) per event

This animation allows you to view the slip in meters for every event that occurs throughout the animation.
    Min Mag/Max Mag:
Only animate earthquakes with a specific Minimum or Maximum magnitude.
    Only Events Involving:
Animate only a certain area of a fault section.
    Filter By Fault/Filter By Control+Clicking Elements:
Select only a specific fault to animate.
    Start Event ID:
Begin animation starting with an earthquake's unique ID. -1 is the default which starts the animation with the starting ID.
    Fade Out Time (years):
Defaulted at 0, control how long the event will still be displayed despite the event being over.

Using an Animation - Drought Animation

This animation allows you to view the length of drought across every fault, known as an Earthquake Drought. Read more here. The colors will distinguish how long a certain fault in the sequence has not had a ground rupturing event with a certain magnitude (defaulted at 7.0).
    Min Mag:
Define an earthquake that resets drought length by this parameter.
    Drought Period Indicator (years):
Defines the length we want the define as the drought length. We accompany an extra time period on the legend to show the severity of the drought length

Earthquake Drought Visualization

Below is a visual tutorial, courtesy of the 2019 SCEC-VDO team, demonstrating how to use the earthquake simulators plugin to visualize earthquake droughts. Simulator event files used were created by the 2019 Forecasting and Simulations Team during the UseIT 2019 Summer Program.

More Plugins

ShakeMap Plugin

ShakeMaps are maps developed by the USGS Earthquake Hazard Program in conjunction with the regional seismic networks. They display the motion and intensity of an earthquake onto a map focused on the epicenter. This plugin allows you to display a ShakeMap on SCEC-VDO in its corresponding geolocation, either from your own library of ShakeMaps or straight from the USGS Website.

Navigation

It can be found and opened using the "ShakeMap" section under Display.

There are three different options you may work from, Presets, Load Map, and Download USGS Map, each with their unique abilities and instructions.
    Presets:
a pre-downloaded list of sample ShakeMaps from some impactful events across the world over the years. This allows you to simply get a glimpse of how they look, as well as how well they visualize seismic events.


    Load Map:
If you have any loaded ShakeMap data (usually in the form of .txt), you may upload it to your SCEC-VDO by entering this tab and simply clicking on the "Load File" button at the bottom to bring it in.


    Download USGS Map:
If you wish to bring in a ShakeMap from the USGS website, you will need to do so in this tab. The top button links you to the official website and allows you to grab the respective data (Which will be explained next) and click on the "Download USGS Shake Map" to load it into your "Load Map" tab.

Clicking on ShakeMaps

Every tab has a table underneath that displays all ShakeMaps that have been clicked on, NOT just the ones that are being displayed at that moment. If you want to change the transparency of a certain ShakeMap, all you have to do is highlight that file and change the parameters that way.

Adding a ShakeMap from USGS

To upload a ShakeMap from USGS, we need the XML file from their official website. For this, we need to first be on the "Download USGS Map" tab. Click on the button labeled "Open USGS Website", and it should link you to the updated version of the ShakeMap Website. Our example follows the current version of the website as of September 2019.

There are a lot of options for searching up ShakeMaps, but generically for our example, we will click on the "Search ShakeMap Archives" option to search for one with specific parameters.

This option links you to a search form where you will add the parameters you want, such as finding one in a specific region, with a specific minimum magnitude, a timeframe, etc. Once you are done with your parameters, click on the "Search" button under "Output Options" at the very end of the page.

On this next page, all your earthquakes with your specific parameters will be displayed on the left column next to the regional map. To the left of them showcases their Intensity levels, and clicking on your desired earthquake will give you the option of displaying its data. Click on any of the buttons such as DYFI, ShakeMap, or Pager after this to move on to the data page.

Once you enter the data page, there is a large variety of information for this specific earthquake, depending on how serious and how much data is out there. Specifically for our cause, we want to grab the ShakeMap of this earthquake. To do this, click on the box labeled "ShakeMap" and scroll down to the "Downloads" Section. Note, that if ShakeMap does not show up, there currently isn't one available.

This step is critical because we want to ensure we are grabbing the right piece of information! After clicking on the "Downloads" section, find the one labeled "XML Grids" or "XML files", and click on the "XML xx.x MB" link. We do NOT need the ZIP option.

The information from within the page it sends you to is not important to this task necessarily, but the link itself is. Copy JUST the link, not everything else in the website.

Now let us head back to SCEC-VDO! Go back to the "Download USGS Map" tab and paste your copied link in the text box labeled "Enter Shakemap XML Link Here". Once you have done this, click on the button next to it labeled "Download USGS Shake Map", and wait for the magic to happen. Choose a name for the ShakeMap when prompted (if you press Cancel or exit, it will simply name the file based on the associated USGS ID ).

If it was successful, you should now find it in the "Load Map" Section. Be wary of it might having some weird naming scheme. You can now display it by checking off the box to the left!

Earthquake Catalog

Earthquake Catalogs contain earthquake source parameters (hypocenters, magnitudes, amplitudes, etc), that are produced by contributing seismic networks. This plugin displays multiple earthquake catalogs generated by USGS based on user chosen parameters of time and earthquake data.

Navigation

It can be found and opened using the "Earthquake" section under Display.

The bottom right corner contains two important tabs, Extents and Display. Whenever you highlight and click to display a catalog:


    Extents:
Displays information such as Min/Max Depth, Magnitude, Latitude, and Longitude coming from the earthquake catalog being highlighted. You can also see the range of the time of the data, as well as how many total EQs are present.


    Display:
Manipulates the visual display of the earthquake catalog being highlighted. You can choose what kind of parameters to change such as the geometry of each point, the scaling of the geometry, its color gradient, etc.

You may display more than one earthquake catalog at a time, but just keep in mind that the more earthquakes, the harder they are to see! You also need to make sure the catalog you want to manipulate is currently being highlighted.

Adding a Catalog

To import your own catalog, click on the grey globe with the plus sign on top of the Extents and Display tabs.

At this point, we as the user need to ensure we have all our data ready to import, such as what we want our Minimum and Maximum values for Latitude, Longitude, Magnitude and Depth to be, the Start and End dates for the data, and their respective Start Time and End Time in UTC time. We have a Max constraint that allows the program to limit how many earthquakes will be displayed, but most of the time the constraint acts like a safety net.

Once you have chosen your parameters, click on Import and your new Catalog should be updated with a name of _Imported_Catalog_ with a sequenced number. At this point you are ready to display your earthquakes that were imported by highlighting the catalog, and check off the box on the left side.

Surface Plugin

The Surface Plugin enables the user to display certain regions of the world through their uppermost layers, allowing greater accuracy in location for any form of fault data you may want to visualize.

Navigation

It can be found using the "Surface" section under Display.

When you open up the plugin, there is a main screen with three distinctive sections:
    Default Surfaces:
This is where you will find a collection of preloaded surfaces, ready at your convenience. Simply click on one of the checkboxes to have the map automatically load up to its specific geographical location on the world map.


    Surface Table:
Whenever you click on a Surface, or you load one in, they will show up in this table. The table will tell you whether or not that Surface is being displayed (under Visible), the name of each Image (under Image(s)), and the name of the Surface if it exists (under Surface(s)).

If you want to toggle the visibility of each image, or to simply remove one, you may do so underneath the Transparency tab. Once you highlight a Surface, you may click the button with an eye to toggle visibility, or click on the minus button on the right side to fully delete it from the map and the table.


    Transparency:
in the Surface Table, once you have a highlighted Surface, you may toggle the transparency of that surface using this slider.

Add a Surface

If you wish to add your own Surface, you may do so by clicking on the button with the plus sign underneath the Transparency slider next to Add/Remove. This will lead you to the Add new: Surface/Image/Preset Surface & Image window:

Both tabs (Load a Surface (topography) and Load an Image), allow you to add a certain file into SCEC-VDO with whatever coordinates you deem are necessary. With the CURRENT fully implemented features, it allows you to bring in a .txt file for a Surface, and if you have a corresponding image (.png, .jpeg, etc. ), you may switch tabs to add one from your current Computer.

You may press Display to add your new surface onto the Surface Table, and you are good to go!

Contact

University of Southern California (map)
3651 Trousdale Parkway, Suite 169
Los Angeles, California, 90089-0742

Phone: 213-740-5843
Fax: 213-740-0011
e-mail: SCECinfo@usc.edu