Using Crusta

Using Crusta

Crusta is currently in development. This page provides bare-bones instructions for early users. The instructions apply to using Crusta in desktop environment and assume that the software is started with the provided mouse.cfg configuration file (see below).

Crusta visualizes global terrain by rendering crusta globefiles. These files contain terrain data (DEM, imagery, etc.) that have been optimized for use with the visualization. Please see “Use Construo” for details on how to create globefiles. Example datasets can be downloaded from the Crusta Globefiles page.

Launching Crusta

Startup Configuration

Because Crusta is an application built using the Vrui framework it may run on a number of visualization environments from a laptop to an immersive CAVE. To facilitate desktop usage of the application it provides a startup configuration that bind Crusta’s virtual tools to inputs on the keyboard with a mouse, and a command to automatically load this configuration (crusta-desktop).

The tool assignments are as follows:

crusta-desktop currently unavailable
Menu 1-key 1-key
Widget interaction left mouse button main trackpad button
Pan left mouse button main trackpad button
Rotate right mouse button z-key
Zoom scroll wheel Page-Up/Down swipe
Map Primary ctrl + left mouse button 2-key
Map Secondary ctrl + right mouse button 3-key

Map Primary is used to create and edit line mapping control points and Map Secondary to select and delete line mappings. See the Mapping section below for details.


1. Open a Terminal window.

2. cd into the folder from which you want to run crusta. All output generated by the program will be stored in that folder:

cd /path/to/crusta/output/folder

and then launch:

crusta-desktop [crusta globefiles]

You can launch Crusta with no default dataset and use the Crusta menu entry Load Data to select the globefiles to visualize from within the running application.


  • no initial dataset using desktop configuration:
  • let ~/Data/DEM.globeFile be a digital elevation globefile and ~/Data/Color.globeFile an imagery globefile to be visualized on a desktop:
crusta-desktop ~/Data/DEM.globeFile ~/Data/Color.globeFile

note: although the Color and DEM globefiles are folders that contain numerous files, only the base folder path should be used to specify the globefile.

The main menu of Crusta is brought up by pressing and holding the 1-key (as in the number one) on the keyboard. Entries of the menu are selected by moving the mouse pointer to the desired entry and then releasing the 1-key. Following features can be accessed through the menu:

  • Load Data — Use the graphical interface within the running application to assign globefiles for visualization.
  • Vertical Scale — Adjust the vertical exaggeration of the elevation dynamically.
  • Light Settings — Enable/Disable and adjust fixed light source parameters.
  • Mapping Control — View information on selected vector art; Import and Export vector art.
  • Map Symbols — Open groups of symbology that can be attributed to vector art.
  • Layer Settings — View currently loaded data (color and scalar) layers. All layers can be hidden/shown, scalar layers can have their color map clamped or repeated.
  • Palette Editor — Edit the color map associated with the active layer (must be a scalar layer).

Saving a viewpoint

Vrui easily lets you save and restore viewpoints within any program (3DVisualizer/LidarViewer/Crusta). Bring up the main menu (use the 1-key) and navigate to Vrui System –> View –> Save View and Vrui will export a file into the directory where you ran Crusta from. If it is your first saved viewpoint it will be called SavedViewpoint0001.view. You can rename this file, but be sure to leave the .view extension. To load this view back, from the main menu navigate to Vrui System –> View –> Load View and find the view you would like to load when the dialog box opens.

The Crusta desktop navigation binds the viewing manipulations to pivot around a point fixed on the surface of the globe. The left mouse button is used to pan: when held the motion of the mouse shifts the pivot point on the surface. The right mouse button is used to orient the view: when held the motion of the mouse rotates the view-point around the pivot point. Use the scroll-wheel to zoom in and out.


In the desktop configuration (mouse.cfg), editing line art can be done as follows (WARNING: NO UNDO FUNCTIONALITY!):

  • Active polyline: any manipulation to polylines require the polyline to first be active. Ctrl+Right-Mouse-Button (CR) toggles the activation mode on & off: while CR is held activation is enabled at the cursor location. If CR is released while the cursor is hovering over a polyline that polyline is activated. To deactivate an active polyline (e.g. before creating a new polyline) move the cursor away from existing polylines and press and release CR. The blue control nodes of the previously active polyline should disappear and not appear when you hover over polylines.

The following applies to active polylines:

  • To create a polyline: make sure no existing polylines are active, press Ctrl+Left-Mouse-Button (CL) to drop the first node at the cursor. The polyline is now active.
  • To select a node or line segment: move cursor over the node/line segment. It turns green when selected.
  • To insert a node: move the cursor over the line segment and press CL.
  • To edit a node: select node, press & hold CL, then drag the mouse.
  • To delete a node: move cursor over node to kill until the node turns green. Press & hold CL to grab the node, and then press CR to kill it.
  • To delete an entire line: move cursor over the line, press & hold CR and then click CL. Whole line should vanish.

Saving mapping to various file formats:

  • Bring up the menu and select Mapping Control to open the control panel.
  • Click on the box with the arrow and select the format to save the file in.
  • The file is saved in the directory from which you launched Crusta.

Assigning attributes (this allows you to decorate lines in Arc with map symbols)

  • Bring up the main menu and select Map Symbols –> the desired symbol group to open the corresponding list.
  • Activate a polyline (using CR). The current attribute should display in the Mapping Control window in the “Current Shape Symbol” field. If blank, it means no attributing is assigned.
  • To assign/change attributing: double left-click on the desired name from symbols list.

Applying color

A color map is generated for each scalar layer that is loaded for visualization. The colors generated for the scalar layers are composited using alpha-blending over the imagery layers.

crusta in the mars

Editing the color map

To edit the color map for a given scalar layer, open the Layer Settings from the main menu and select the desired scalar layer from the list. Then chose Palette Editor from the main menu to open the editor. The editor shows four workspaces from top to bottom: 1. the color map, where individual control points with color attributes can be set and modified; 2. the range editor that shows and controls how the color is mapped to the scalar domain; 3. information and color picking panel; 4. control point and palette controls.

Under the color map the minimum of the map interval is shown as the left-most value and the maximum as the right-most value. The middle value indicates the value at the center of the map interval. By default the color map is applied by repeating it over intervals which ranges are defined by the minimum and maximum value. This behavior can be changed to clamp the map only to the specified interval boundaries. To do so, open the Layer Settings from the main menu, select the desired scalar layer and click the Clamp button on that panel.

To manipulate the color of the map:

  • Add a control point by clicking on the location on the map where the new control color value should be inserted. The height of the control point controls it’s opacity value (top fully opaque, bottom fully transparent).
  • Move a control point by first clicking on it to select it. Then click and drag the point.
  • Remove a control point by first clicking on it to select it. Then click on the “Remove CP” button at the bottom of the window.
  • Assign a color to a control point by first clicking on it to select it. Then: 1. pick a color from the color hexagon (the slider on the bottom controls the saturation) or 2. manipulate the sliders to change the contribution of opacity, red, green and blue (from left to right).

To manipulate the interval of the color map, use the sliders. Unlike a regular slider, where the position directly corresponds to a value, these sliders increment or decrement the manipulated value. The position of the slider off the center defines how fast to decrement (when dragging to the left) or increment (when dragging to the right). Release the slider nob to spring it back to the center position:

  • The top-left slider adjusts the minimum of the interval.
  • The top-right slider adjusts the maximum of the interval.
  • The bottom slider is used to shift the current interval without changing it’s range.

To save and load edited color maps:

  • The four buttons on the left-hand side of the window allow for quick temporary storing and retrieval of edited maps. (ATTENTION: their content is NOT preserved from one Crusta session to the next). To store the current map click on the bottom-left corner of a button of your choosing. To set the current map to a stored one, click on the top-right corner of the button.
  • Save the current color map or Load an existing one by using the “Save Palette” and “Load Palette” buttons. Color maps are saved as numbered files “SavedPaletteXXXX.pal” where XXXX is a sequence number.

Applying the color map using the terrain

In addition to the sliders in the Palette Editor, the range of the color map can be manipulated more interactively, by selecting locations on the terrain surface and assigning the scalar value at that location to the interval ends. This requires the use of the Crusta Surface Probe.

Before using the tool we must bind it to a button. Here we will use Alt+Left-Mouse-Button (AL). Press and hold AL to bring up the Vrui tool menu. Navigate to Crusta –> Surface Probe and release AL. This will pop up a small control window with the options “Dual” and “Single”. The “Dual” mode allows us to set the minimum and then the maximum of the interval whereas the “Single” mode shifts the interval.

Setting the minimum and the maximum directly on the terrain:

  • toggle the “Dual” mode.
  • point to the spot on the terrain that should correspond to the minimum and press AL. As long as AL is held the position can be adjusted. Release AL when done.
  • point to the spot on the terrain that should correspond to the maximum and press AL again. Adjust the position while holding AL. Release AL when done.
  • Once both min and max markers have been placed they can be adjusted by pointing to one of them (the markers will change color to reflect their selection) pressing and holding AL, dragging the marker to the new location and finally releasing AL.

Sliding the range directly on the terrain:

  • toggle the “Single” mode.
  • point to the location on the terrain where the new minimum of the range should start and press AL. Hold AL while adjusting the location to shift the range. Release AL when done.

Generating dynamic contour lines

Since the opacity of the applied color can be controlled, contour lines can be generated by carefully editing a color map of the DEM scalar layer such that it is mostly transparent but contains opaque pixels. For example setting the left and right control points to fully opaque black, then creating two new adjacent transparent control points will produce one line at the boundary of the range (the color map is repeated in periods corresponding to the elevation range). Now using the “Single” mode of the Surface Probe will dynamically move the contour line to the terrain location pointed to by the cursor.

Using the Vrui measurement tool

Use this tool to measure distances on the terrain. Before using the tool we have to bind it to a button, but we also have to make sure the mouse cursor is mapped to the surface of the terrain. For this purpose we will use 3-Button (3).

  • Map the cursor to the terrain surface by pressing and holding 3, navigating the menu to Transformer –> Crusta Surface and release 3.
  • Now bind the measurement tool by pressing and holding 3 again and then navigating the tools menu to Utility –> Measurement Tool and releasing 3.

A menu should open that allows you to select the type of measurement and units. Select options you wish.

Use 3 to select locations on the surface of the terrain to measure. NOTE: after making your first measurement, zoom in and adjust the view (e.g., tilt to ~low-angle relative to the terrain surface) to make sure the nodes are actually plotting on (i.e., embedded within) the terrain surface. If not, the first step did not work.

To kill the measurement tool: move the cursor to the farthest point possible in the lower-left corner of the display and then press and release 3. When you move the cursor to the center of the screen and press 3, the Tool Menu should reappear. If not, kill was not successful.

How to load/process shapefiles into Crusta

Step 1. You will need:

  • Shapefile
  • DEM that covers the entire extent of the shapefile

Step 2. Open ArcScene

  • Load 3D Analyst toolbar
  • Go to 3D Analyst –> Convert –> Features to 3D
  • Unordered List ItemInput Feature – select the shapefile
  • Raster or TIN surface – select the DEM that covers the area
  • Output Feature – save the shapefile that will have z-values

Step 3. Rename the output shapefile to Crusta_Polylines.shp Step 4. Start Crusta

  • Chose Mapping Control from the main Crusta menu
  • Click “Load” and navigate to the location of the shapefile and load Crusta_Polylines.shp

To Print an Image

On Linux:

  • Press “Win+PrintScreen” buttons. Vrui will print a confirmation when it saves a screenshot

On Mac:

  • Command+Shift+3: takes a screenshot of the full screen (or screens if multiple monitors), and saves it as a file to the desktop
  • Command+Shift+4: brings up a selection box so you can specify an area to take a screenshot of, then save it as a file to the desktop
  • Command+Shift+4, then spacebar, then click a window: takes a screenshot of a window only and saves it as a file to the desktop