User Tools

Site Tools


keckcaves:crustamanual

Crusta Manual

About this document

This page is currently under construction. It will provide bare-bones instructions for pre-alpha testers.

Software Programmer: Tony Bernardin

Crusta data on nile has been moved to here

Installation & Updates

Installing Crusta on Mac OS X

Before installing Crusta you need to download and install the following programs (links for Mac OS X):

1. GDAL - website

2. CMAKE - click to download

3. GIT - website

4. XQuartz (Mac OS X Only) - website

This installation assumes you have installed Vrui-3.0 to ~/Vrui-3.0 or in more detail /Users/yourusername/Vrui-1.0 – Check this by typing cd ~/Vrui-3.0 - If it is there, all steps in this manual will apply, if not then you will have to edit one command in a future step.

Instructions on how to install Vrui can be found here

Step 1 Choose a directory where you want to install the Crusta folder - I suggest doing this in ~/src

cd ~/src 

Step 2 Type:

git clone git://github.com/KeckCAVES/crusta.git 

Step 3 Move into the new crusta folder

cd ~/src/crusta

Step 4 Type (Enter between each line)

cd build
mkdir release
cd release

Step 5 Create a make file. If you have not installed Vrui-3.0 to ~/Vrui-3.0 you will need to change the -DVRUI_PATH=~/Vrui-3.0 command to the directory where Vrui is installed. Please note the trailing two dots as they are part of the command line.

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=~/Crusta -DVRUI_PATH=~/Vrui-3.0 ..

For computers in iMAC classroom

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=~/Crusta -DVRUI_PATH=/Vrui-3.0 ..

Step 6 Make

 make -j(# of processors you would like to use)
Do not use -j if you are unsure of what it means

Step 7 Make Install

make install

Step 8 Go to folder with programs

cd ~/crusta/bin

Step 9 Test installation

./crusta
crusta should pop up

Step 10 Setup Crusta .cfg files (For version 10.03.03 go here) Crusta is configurable through a set of separate files. Some have been provided through the git repository and are in the subfolder ~/src/Crusta/share. Some are copied during installation to the ~/Crusta/share/crusta:

  • mapSymbols.cfg: definitions for geologic mapping symbols that can be attributed to lines drawn in Crusta (is copied during install)
  • mapSymbolAtlas.tga: visual representation of the geologic mapping symbols (is copied during install)
  • crustaSettings.cfg: settings for the crusta environment (see “Running Crusta” below)
  • pre.cfg: configuration file that initializes a set of tools to be used in Crusta (see “Running Crusta” below)

Updating to the Latest Version

Once you have the git clone of the sources, fetching the latest updates is very quick and easy:

Step 1 Use the terminal to navigate to the Crusta folder. In our example:

cd ~/src/Crusta

Step 2 Use git to fetch the latest source updates:

git pull

Step 3 Navigate to the release build folder and rebuild the executable:

cd build/release
make install

You now have the latest Crusta release.

Running Crusta

Launching Crusta

Follow these steps to start Crusta.

Open a Terminal window.

cd into the directory that contains the program crusta:

cd /path/to/crusta/executable

and then launch:

./crusta -dem /path/to/dem -color /path/to/color

If you'd like to use the default configuration of the Crusta tools for desktop use you can merge this configuration at start-up by adding '-mergeConfig path/to/pre.cfg' to the command line. In the example below we have copied pre.cfg to the installed share location ~/Crusta/share/crusta:

./crusta -dem /location/of/dem -color /location/of/color -mergeConfig share/crusta/pre.cfg

If you are always going to be using the configuration you may also copy the pre.cfg file to the folder containing the crusta executable (~/Crusta) and rename it to Vrui.cfg. This way it will automatically be loaded.

Similarly the default crusta settings can be merged in on the command line by appending:

-mergeConfig /path/to/settings.cfg

To minimize the chances of accidentally forgetting to import the proper settings, please copy the crustaSettings.cfg file provided in the source distribution (~/src/Crusta/share/crustaSettings.cfg) to the folder containing the executable (~/Crusta/bin). When the settings file is present in the working directory crusta will automatically load it.

Example: If I had crusta in ~/Crusta/bin and the data files were in ~/Data/DEM/ and ~/Data/Color, I would use the following commands in terminal

cd ~/Crusta/bin 
./crusta -dem ~/Data/DEM/mainDEM -color ~/Data/Color/blueEye100113

Note although the Color and DEM folders contain numerous files with different numbers, I only need to call the first part of the file before the _#'s.

Setting up the Controls

Note: You may not need to do this. When crusta launches, press the 1 button. If a menu pops up that allows you to toggle the texture image, you should not need to do the reset.

Once crusta has started the first thing to do is click the left mouse button in the red box and then the right mouse button in the red box. This resets both controls for those buttons.

Now, right click the mouse button and scroll to Navigation –> Surface-Alligned Navigation –> Mouse (Multiple Buttons)

BEFORE letting go click the left mouse button and then scroll the wheel on the mouse, then let go.

This assigns the left mouse button to pan, the scroll wheel to zoom, and the right mouse button to “grab” the data and rotate the frame around. At first, you will likely have to use the right mouse button to get the world into its correct orientation.

After playing with this for awhile you should be able to figure out the controls. Feel free to explore the data.

Because we reset the right click on the mouse, the Crusta menu does not have a button assigned to it. To assign this button, press a number down on the keyboard (e.g. 1) and then scroll to User-interface –> Menu Handler –> Screen-alligned Menu and then let go of the number (e.g. 1) - Do NOT click the mouse.

If done correctly, you can bring the menu up by pressing the # you assigned to the menu. Within this menu you can change the vertical scale. Due to the way the mouse was set-up in the beginning, you need to right click to move the vertical scale box around and change the scale.

Toggle texture

If you have the menu assigned to button “1”, then press 1 and deselect textured terrain.

If you do not have the menu assigned by default, use whatever key you've assigned it to, or see “Setting up controls” above.

Saving a viewpoint

VRUI easily lets you save and restore viewpoints within any program (LidarViewer/Crusta). With the .cfg we are using, you will need to press button “1” and navigate to Vrui System –> View –> Save View and VRUI will export a file (If it's your first it will be called SavedViewpoint0001.view) into the directory where you ran crusta from (most likely ~/Crusta/bin). You can rename this file, but be sure to leave the .view ending. To load this view back, press button “1” and go to Vrui System –> View –> Load View and find the view you would like to load when the dialog box opens. Because of the way the controls are set up, controls in the dialog box are controlled by the right-mouse button.

Mapping Functions (2 Button)

Prepare yourself: (see here for release 10.03.03 instructions)

  • Make sure you have the mapSymbols.cfg in the share subfolder from which you run Crusta (e.g., ~/Crusta/bin).
  • If not, check crusta installation Step 10 above
  • Launch Crusta
  • Select two unassigned buttons. In the following we'll use #2 & #3. (An alternative is Control+L mouse and Control+Rmouse)

Tie cursor to Crusta surface

  • press #2, select “Transformer > Crusta Surface”
  • Release #2.

Set up mapping tool:

  • press #2, select “Crusta Tool > Mapping Tool > Polyline Drawing Tool”, and then press & hold #3 without releasing #2
  • Release #3 and then release #2.

Using the mapping tool: You should now have these functions (WARNING: NO UNDO FUNCTIONALITY!):

  • To create a polyline: press #2 to drop nodes at end of cursor ray.
  • To select a node or line segment: move cursor ray over node/line segment. It turns green when selected.
  • To unselect a line: move away from the line and press #3 to toggle off selection mode. Blue nodes should vanish & not appear when you hover over line. Note that #3 toggles the selection mode on & off (i.e., cursor stays in “select” mode until #3 is pressed to turn it off and vice versa).
  • To add a node: select line segment and press #2
  • To edit a node: select node, press & hold #2, then drag mouse
  • To delete a node: make sure you're in selection mode (i.e, nodes are appearing). Move cursor ray over node to kill until node turns green. Press & hold #2 to grab the node, and then press #3 to kill it.
  • To delete an entire line: move cursor ray over line, press & hold #3 and then #2. Whole line should vanish.

Saving mapping to various file formats

  • press & hold #1 key and turn on the mapping control panel.
  • Right click on box with arrow (says “GRASS” when first loaded) and select format to save file in.
  • File is saved in directory from which you launched Crusta

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

  • press & hold #1 key and select “Map Symbols” and then “Favorites” to turn on the Map Symbols list.
  • select line. Current attribute should display in Mapping Control window in “Current Shape Symbol”field. If blank, it means no attributing is assigned.
  • To assign/change attributing: double right-click on desired name from symbols list

Applying color

Switching color modes

From the Crusta menu “Texturing modes” chose:

  • Untextured: greyscale hillshade of the digital elevation model
  • Color Map: overlay a custom color map over the textured hillshade terrain (or greyscale hillshade if no texture was loaded)
  • Image: textured hillshade terrain only (or greyscale hillshade if no texture was loaded)
Editing the color map

Chose “Palette Editor” from the crusta menu to open the editor. The editor shows three workspaces from top to bottom: 1. the color map, where individual control points with color attributes can be set and modified; 2. information and color picking panel; 3. control point and palette controls.

  • 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 Control Point” 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) 2. manipulate the sliders to change the contribution of opacity, red, green and blue (from left to right).
  • 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 to the terrain

To select the elevation range to which the color map should be applied use the “Elevation Range Tool” as follows.

Assign the tool to an unassigned button. We will use #4 in the following.

  • Tie cursor to Crusta surface by pressing #4, selecting “Transformer > Crusta Surface” and then releasing #4. (We map the cursor to the terrain surface as that will allow us to pick the range directly on the visible terrain)
  • Assign the tool to the projected cursor by pressing #4, selecting “Crusta Tool > Elevation Range Tool” and then releasing #4.
  • Upon success the “Elevation Range Settings” window will pop up.

Manipulate the range using the controls on the settings window:

  • Using the “-” and “+” buttons will respectively decrease or increase the elevation value mapped to the minimum or maximum of the range.
  • Pulling the sliders towards the “-” or “+” will respectively continuously decrease or continuously increase the elevation value until the slider is released. The speed at which the values are changed can be controlled by how close the slider is dragged to the “-” or “+” buttons.

Setting the minimum and the maximum directly on the terrain:

  • toggle the “Set Min/Max” at the top of the window
  • point to the spot on the terrain that should correspond to the minimum and press #4. As long as #4 is held the position can be adjusted. Release #4.
  • point to the spot on the terrain that should correspond to the maximum and press #4 again. Adjust the position while holding #4. Release #4.
  • Once both min and max markers have been placed they can be adjusted by pointing to one of them pressing and holding #4, dragging the marker to the new location and finally releasing #4.

Sliding the range directly on the terrain:

  • toggle the “Shift Min” at the top of the window
  • point to the location on the terrain where the new minimum of the range should start and press #4. Hold #4 while adjusting the location to shift the range. Release #4.

Save and load ranges by using the corresponding buttons at the bottom of the window. Elevation ranges are saved as numbered files “Crusta_ElevationRangeXXXX.rng” where XXXX is a sequence number.

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 that 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 “Shift Min” mode of the “Elevation Range Tool” will dynamically move the contour line to the terrain location pointed to by the cursor.

Measurement tool

Use this tool to measure distances on the terrain. The approach is similar to the mapping tool above, so please read that first if you are not familiar with this

  1. Decide on two buttons (b1, b2) to use for measurement tool (do not use the same ones as on the PolylineTool if you have one assigned)
  2. Press and hold b1, in the menu go to transformer → Mouse/Screen projector, press and hold b2, release b2, release b1
  3. Repeat step 2, but select transformer → Crusta Surface instead. (Now you have a surface transformed device with no tool assigned to it)
  4. Repeat step 2, but select Utility → Measurement Tool. (Now you have a measurement tool connected to the surface location
  5. A menu should open, that allows you to select the type of measurement and units.

Pre-Processing Data

The Crusta PreProcessor (construo) processes both DEMs (topographic data) and imagery (Satellite, Aerial, etc - basically anything with 3 bands). The processor accept numerous types of data (.tif, .adf, etc) - A detailed list of acceptable formats is coming.

cd ~/Crusta/bin

For a printout of how construo works, you can simply type:

./construo
Usage:
construo -dem | -color <database name> [-scale <scalar>] [-nodata <value>] [-pointsampling] [-areasampling] <input files>
  • -dem | -color — Choose only one depending on what data you are processing
  • <database name> - location of database with name (see notes below - can call previously constructed project). You need a database name for construo to work, otherwise it will not recognize the dem as data.
  • The -scale <scalar> argument can be used to convert a DEM file in feet to meters or vice versa (e.g. -scale 0.3048)
  • The -nodata <value> overrides the nodata loaded by GDAL and assign that value to nodata (only use this if GDAL does not read in NoDATA value). Nodata values for color -nodata “0 0 0” if you want to remove all black pixels. The quotes ARE important!!
  • For now ignore -pointsampling and -areasampling
  • <input files> Directory and file calls for the files needed to be processed (see note below)

IMPORTANT - Creating a Crusta project is like painting. At first you need to paint a base layer and then layer other paint on top that improves the painting. Thus, when processing a Crusta project with different resolution data - the input file order is important. First call the lowest resolution data and then the medium then the highest resolution (e.g. Blue Marble –> Aster –> LiDAR).

Other Notes:

  • If you have a project that you would like to add additional data to, you can call that database in <database name>. This will then write all data on top of that project. I suggest making a copy of the database before doing this.
  • For Imagery Processing you can ignore most of the commands (-scale, -nodata) - e.g. ./construo -color <database name> <input files>
  • Crusta can load in NoDATA Values from ESRI GRID files automatically. If you are loading topographic (DEM) data this can be done by calling the directory that contains numerous files. Crusta will find the GRID file and load that (e.g. /gis-data/GIS/dems/Damage/sm_alirt/)
  • It seems that GDAL does not like RGB (imagery) GRID format. Apparently, this format export 4 folders - The 3 color bands that contain the w*.adf files that crusta loads and a fourth folder that ArcGIS recognizes as the combination of all those files. Unfortunately loading in each individual folder will overwrite the previous, so Do NOT use ESRI GRID format for COLOR IMAGERY.
  • It seems that GDAL has an issue with reading the JPEG2000 image formats. Affects some of the HiRISE imagery. Please convert the JPEG2000 to another supported image format, e.g. GeoTIFF.
  • GDAL makes a distinction between the latitude of origin and the latitude of true scale. These were not used correctly in some of the HiRISE dataset that we used. Fortunately construo outputs a .proj file that contains the projection it uses for processing the data when it first reads the input (it does not overwrite the file if it already exists). This way projections can be manually set (if there is no georeferencing) or tweaked (if there is). Thus, a first (cancelled) attempt to build the HiRISE data provides the .proj files where the value stored for latitude_of_origin can be set to a new standard_parallel_1 parameter to produced the correct projection

How to load/process shapefiles into Crusta

Step 1. You will need:

  1. Shapefile
  2. 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

  • Press “1” and go to Mapping Control
  • Click Load and navigate to the location of the shapefile and load Crusta_Polylines.shp

DEM files known to work with Construo/Crusta

All gdal supported formats. 
keckcaves/crustamanual.txt · Last modified: 2014/07/02 15:26 by yikilmaz