ceallab - 2012-07-03

[MabelBrowserDocumentation]

Setting IDL Up to Run MabelBrowser

Screenshot thumbnail
The MABEL lidar data browser.
Screenshot thumbnail
The CompareChannels data browser.

The first step in running the MabelBrowser program is to make sure the needed IDL programs are in your IDL path (i.e., on the list of directories specified by the IDL system variable !PATH). There is no special version of IDL required to run the MabelBrowser, and it has been tested and found to run successfully on IDL versions 6.4 through 8.2. The MabelBrowser program is built on top of the Coyote Library, which means this library must be downloaded and installed correctly before anything else can occur.

Obtaining and Installing the Coyote Library

It is extremely important that you do not have more than one Coyote Library on your IDL path. The Coyote Library is a popular library, and parts of it (sometimes all if it!) are distributed with other software you may be using (e.g., NASA Astronomy Library, Solar-Soft library, BCAL LidarTools, etc.). All of these programs will run correctly if you have the latest version of the Coyote Library installed. If you have a Coyote Library installed currently, you will need to update it to at least tagged version 2.3.1 of the library in order to run the MabelBrowser code.

The most current version of the Coyote Library can be found in either of two locations. The first, and best, location is the http://code.google.com/p/idl-coyote/ in the freely available Google Code distribution area. The SVN commands to check out the Coyote Library to a coyote directory looks like this:

svn co http://idl-coyote.googlecode.com/svn/trunk/coyote coyote

The second location is on the Guide to IDL Programming web site:

http://www.idlcoyote.com/programs/zip_files/coyoteprograms.zip

The zip file will unzip into a coyote directory in the current directory.

If you wanted to check out a tagged release of the library, you might use an SVN command like this, where the last three digits indicate the tagged version you want:

svn co http://idl-coyote.googlecode.com/svn/tags/coyote_library_2.3.1 coyote

Adding the Coyote Library to your IDL Path

To use the Coyote Library, you must add it to your IDL path (IDL !Path system variable). How you do this depends on whether you use the IDLDE (the IDL Workbench) to run IDL, or whether you run IDL from the command line.

If you use the IDL Workbench to run IDL, simply open up the Workbench and locate the IDL preferences dialog. This is usually under the Windows -> Preferences -> IDL menu item. Find the Paths dialog and simply click the Insert button and locate the coyote directory on your machine. Now move the coyote directory to the correct location in the IDL path (I strongly recommend you place it as the first directory on your IDL path) by clicking the Move Up or Move Down buttons until it is placed where you want it. Use the buttons to order the other directories on your IDL path now.

If you use the IDL command line, then you probably want to set your IDL path in an IDL start-up file. The start-up file is run automatically whenever IDL is started, so it is a good place to define your IDL path. The location and name of the IDL start-up file is specified in various ways. If you are using the IDL Workbench, you can define the start-up file using the IDL preferences dialog you used before. Look for it by clicking the Windows -> Preferences -> IDL menu button. If you are running IDL from a command line, the IDL start-up file is usually named by defining the IDL_STARTUP environment variable for your computer system. This is done differently, depending upon which shell or computer system you use to run IDL, but here are some examples.

Suppose you have have an "idl" directory in your home directory. This is probably where you have installed the "coyote" directory. The "idl" directory might be a good location for your IDL start-up file. If you are running a bash shell, you might put this command in your .bashrc or .profile file in your home directory:

export IDL_STARTUP=~/idl/idl_startup.pro

In a C shell (use the .cshrc file), you might do this:

setenv IDL_STARTUP ~/idl/idl_startup.pro

In a Korn shell (use the .profile file), you might do this:

IDL_STARTUP=~/idl/idl_startup.pro
export IDL_STARTUP

Once you have an IDL_STARTUP environment variable defined (you may have to run the file you just edited or even log-out and log back into your account to pick up the change), you are ready to add the Coyote Library to your IDL path. Inside your idl_startup.pro file, add this line if you are working with a UNIX operating system:

!PATH =  Expand_Path('+~/idl/coyote') + ':' + $
         Expand_Path('+~/idl/david') + ':' + $
         Expand_Path('~/idl/idl_util') + ':' + $
         !PATH

In this example I have added two additional directories to the IDL path,
david and idl_util. You can add as many directories as you like
using this command.
The order in which these directories are added to the !PATH system variable, as in this example, is the order in which they will be searched. You see the Coyote Library as the first directory on the path. The "+" sigh in front of the directory name indicates that all
the sub-directories in this directory should be added to the path, too.
Also, notice the semi-colon that follows each directory name. This is how directories are separated in the IDL path on UNIX machines.

If you are working on a Windows machine, the command might look like this:

!PATH = Expand_Path('+C:\idl\coyote')  + ';' + $
         Expand_Path('+C:\idl\david') + ';' + $
         Expand_Path('~C:\idl\idl_util') + ';' + $!PATH

Note the use of a semi-colon, instead of a colon, on a Windows machine to separate directories, and the use of backward slashes rather than the forward slashes used in UNIX.

Obtaining and Installing the Mabel Directory

Once the Coyote Library is installed, you are ready to install the Mabel IDL files that are required for the MabelBrowser program. The Mabel files are available here. They can be downloaded with an SVN client application (we recommend the free TortoiseSVN client for Windows users). Use this SVN command to check out the Mabel directory into a mabel directory in your IDL directory:

svn co http://svn.code.sf.net/p/mabelidl/code/trunk/mabel mabel

Next, add the mabel directory to your IDL path in exactly the same way you did for the coyote directory above. Use the IDL preferences dialog if you are using the IDLDE (IDL Workbench), or the IDL_STARTUP file method if you are using a command line version of IDL. On a UNIX machine, your path descriptor in your idl_startup.pro file might look like this:

!PATH =  Expand_Path('+~/idl/coyote') + ':' + $
         Expand_Path('~/idl/mabel') + ':' + $
         Expand_Path('+~/idl/david') + ':' + $
         Expand_Path('~/idl/idl_util') + ':' + $
         !PATH

Creating Projects in the IDL Workbench

If you work in the IDL Workbench, the best way to work with the two directories you have downloaded and installed is to make projects out of them. Then you have access to the code in the Project Explorer window.

To make a project of the coyote directory, chose the New Project button from the Workbench interface (File -> New -> IDL Project. Give the project the name "coyote", and select the "Create the new project from an existing directory" button. Use the Browse button to locate the coyote directory on your computer. Be sure the "Update IDL path when project is opened or closed" button is not selected! Click the Finish button to complete the project.

Do exactly the same thing to add the mabel directory as a project in your IDL Workbench. Now you are ready to start using the MabelBrowser program.

Creating High Quality Raster File Output

Coyote Library routines make it extremely easy to produce high-quality raster file output, but it does require the installation of free third-party software. In particular, IDL must have access to ImageMagick to create high-quality raster files from PostScript intermediate files. ImageMagick is free software that is easily installed on any machine running IDL, including Macs and Windows machines. It is normally installed automatically on UNIX machines. If you wish to produce PDF files, you must install the free GhostScript software, also available on any machine IDL runs on. UNIX users might use other programs to do this conversion from PostScript files. In general, the Coyote Library routines will be able to find the software it needs if it has been installed correctly. Please contact us if you have any difficulty at all creating high-quality file output.

Running the MabelBrowser Program

To run the MabelBrowser program, just type "MabelBrowser" at the IDL command prompt:

IDL> MabelBrowser

The first thing you will be asked to do is to open a MABEL data file. These files are written in HDF5 format, and have a *.h5 file extension. You can find an example file in this repository if you don't have a data file handy.

Running the CompareChannels Program

The CompareChannels program can be run as a stand-alone program, or it can be run from a button in the MabelBrowser program. Suppose you wanted to compare channels 1, 16, and 43 in the program. You would run the program like this:

IDL> CompareChannels, CHANNELS=[1,16,43]

Channel selection widgets allow you to change to any channel in the file and to change the symbol used to designate that channel in the line plot. Up to seven channels can be compared at once.

Using Zoom/Pan Graphics Windows

The massive amounts of data created by Lidar instruments turns the old adage "can't see the forest for the trees" on its head. With Lidar about all you can see is the forest, but what you often want to see are the trees. This requires some way to "zoom into" the data on an appropriate scale.

The Lidar browsing tools provided here are often displayed in a modified version of the Coyote Library routine cgZPlot, which allows the user to zoom into a line plot and/or pan to a different position along the data axes. The modified program, named ZLidar, samples the Lidar data differently at different zoom factors. It does this for two reasons: (1) speed of rendering the data, and (2) to create a better visualization of the data. For example, when completely zoomed out, every 12th point in the data is shown. As the user zooms in, and the X data range becomes smaller, progressively more and more points are shown in the plot. When the data range gets to be 1/10th of its full range, all the Lidar data points are shown in the plot window.

The cgZPlot program allows the user to adjust the the amount of zoom in various ways. The primary method is to draw a rubber-band box around the portion of the data you want to zoom into. Just click with the LEFT mouse button, hold the button down, and move the mouse. You will see a box drawn on the display. When you release the button, the plot will zoom into that portion of the data. You can do this as many times as you like to zoom closer and closer to the data. To zoom all the way back out, just click the LEFT mouse button in the window and release it without moving the mouse.

If you make a mistake zooming into or out of the data, you can use the UNDO and REDO buttons to step back and forth in time. The UNDO button will remember the last 25 adjustments you made to the data plot.

Once zoomed in to the data, you may find you want to adjust the zoom parameters. You can do this by clicking the LEFT mouse button in the margins outside the data plot. If you click in the Top or Bottom margins you will zoom into or out of the current zoom along the X axis by a small amount. If you click in the Left or Right margins you will zoom into or out of the current zoom along the Y axis by a small amount. You can click in the margins as many times as you like. The UNDO button will remember than last 25 zooming operations.

The cgZPlot program allows you to zoom into the data in both the X and Y directions with a rubber-band zoom. If, however, you would like to see all of the Y data for a particular X data range, you can click the Adjust Y Range button and all the Y data for that particular X data range will be shown.

Once you are zoomed into the data, you may want to see other portions of the data at that zoom level. To do so, hold the RIGHT mouse button down inside the plot boundaries and drag the plot to pan the plot to a different location along the X and Y axes. Each "panning" operation is saved and can be undone with the UNDO button.

 

Last edit: ceallab 2012-07-20