Command line interface

The MrGeo command line supports multiple operations. There is one "driver" script for running all commands, and in a development environment, it is located in mrgeo-cmd/src/main/scripts/mrgeo. It relies on the MRGEO_HOME environment variable being set properly. Additionally, the $MRGEO_HOME/conf/mrgeo.conf file must be configured.

Configuring MrGeo

First define the MRGEO_HOME environment variable. The typical setup for a developer is to set it to the top-level "mrgeo" directory where the MrGeo git repo is cloned. The examples in the rest of this page assume that the MrGeo git repo is cloned to /home/myself/projects/mrgeo.

export MRGEO_HOME /home/myself/projects/mrgeo

Given that, the mrgeo configuration directory must be set up in the MRGEO_HOME path. In a development environment:

• Create a symbolic link in the MRGEO_HOME path pointing to mrgeo-services/mrgeo-services.core/src/main/resources/conf and copy the boilerplate configuration file.

cd /home/myself/projects/mrgeo
ln -s /home/myself/projects/mrgeo/mrgeo/mrgeo-services/mrgeo-services-core/src/main/resources/conf/ conf
cd conf
cp mrgeo.conf.dev mrgeo.conf

Running the mrgeo script

To see the MrGeo commands available to you, run the mrgeo script with no arguments:

cd /home/myself/projects/mrgeo
mrgeo-cmd/src/main/scripts/mrgeo

produces output like:

Usage: mrgeo COMMAND
       where command is one of:
  buildpyramid    Build/rebuild image pyramids for a MrsImage
  export          Export a MrsPyramid image to a geotiff
  generatekeys    Generate keys (developer cmd)
  info            Show information on a MrsImage (developer cmd)
  ingest          Ingest source imagery into MrsImagePyramid format
  ingestvector    Ingest a vector source into a MrsVector
  mapalgebra      Execute a mapalgebra command
  printsplit      Print the splits file (developer cmd)
  showconf        Show configuration (developer cmd)
  updatesplits    Update the splits file (developer cmd)
  upgradepyramid  Upgrade a MrsPyramid from v1 to v2 (developer cmd)
Generic options supported are:
  -v    verbose logging
  -d    debug (very verbose) logging
Most commands print help when invoked without parameters.

Once you determine which command you wish to run, include that as the first argument to the mrgeo script. Each of those commands are independent from each other and take a different set of arguments. As the usage output above mentions, most commands will provide specific usage information if you run that command with no arguments. For example:

cd /home/myself/projects/mrgeo
mrgeo-cmd/src/main/scripts/mrgeo mapalgebra

produces:

usage: MapAlgebra
 -b,--buildPyramids            Build pyramids on the job output.
 -d,--debug                    Debug (very verbose) logging
 -e,--expression <arg>         Expression to calculate
 -l,--local-runner             Use Hadoop's local runner (used for
                               debugging)
 -o,--output <arg>             Output path
 -pl,--protectionLevel <arg>   Protection level
 -s,--script <arg>             Path to the script to execute
 -v,--verbose                  Verbose logging

so that you can determine the arguments accepted by that command. More information is available for each of these commands on separate help pages on this wiki.

Exporting an Image

The MrGeo command line includes an option for exporting an image to a tif. The output image will contain the raw values of the image. If you're interested in seeing an RGB image, use the MrGeo WMS or TMS services documented at Web Services. Tools like QGIS which can make WMS requests can be used to view imagery from MrGeo.

The export command-line however allows you a number of options. If your image is large, your computer may not have enough memory to generate a single output image at the highest resolution level. You have a few options to deal with that:

1. Increase the amount of memory the process can use.

   In the command shell where you run the MrGeo export, define an environment variable like:

   export HADOOP_CLIENT_OPTS=-Xmx12g
   

   That is an argument that sets the maximum amount of memory that will be used by the Java process that performs the export. In this case, it is set to 12 GB, so change that argument to suit the amount of memory available on your system and the amount of memory needed to generate the image.

2. Do not use the -s option to mosaic to a single tif.

   Depending on the size of your image, the output could be quite large, so it may not be possible to mosaic the output at the highest resolution. If you leave out the -s argument, export will create the output as a directory with a single tif file for each of the tiles of the image.

3. Provide a -z option

   This tells export which zoom level of the image to use. Using lower resolution zoom levels makes the output image smaller in size. In order for this to work, a pyramid must have been built for the image, which is usually the case.

4. Provide a narrower bounds

   Use the -b option along with a bounds argument "minX,minY,maxX,maxY" in latitude/longitude to reduce the bounding box of the image to export.