spatialmax Documentation

spatialmax - Find the file with the largest spatial region
spatialmax is a program that takes a list of input ISIS cube files
and determines the largest spatial area.  It uses a variety of methods
to determine this size based upon the following criteria:

1)  Finds the image with the most number of lines
2)  Finds the image with the most number of samples
3)  Finds the image with the most number of pixels determined by
    multplying the number of lines and samples.

A number of results are provided by this application once this has
been determined.  The user can SELECT one or combination of the above
criteria to determine the maximum spatial size.  The user can choose
one of the following four option of the SELECT parameter to decide
what the largest parameter is:

MAX	- The largest is determined by the most occuring number of
          lines and samples in all images.  Note that this is not
	  necessarily the same image.  If finds the maximum size in
	  both the line and sample dimension that can contain all the
	  images.
BIGGEST	- This is the image that contains the most pixels in both the
          line and sample dimensions.
LINE	- This is the image that contains the most number of lines
SAMPLE	- This is the image that contains the most number of samples

The user can optionally choose several methods to deal with results.

The ATODDS parameter, if provided by the user, will list all the
files that do not have the exact number of lines and samples as
determined by the SELECTed option.

Also, it may be nice to make all the files have the same dimension.
The MAGSCRIPT parameter is the name of a file that will be generated
containing only the files that do not have the exact number of lines
and samples of the SELECTed maximum dimensions.  The contents of this
file are actual "magcube" commands that result in files that do not
have the number of lines and samples as determined by the SELECTed
method.  Note that these are the actual raw commands that will
execute the "magcube" application to bring all files to spatial
compliancy.  The output file name is created from the input file
by replacing the ".cub" extention with ".mag.cub".  If for some
reason the ".cub" extension does not exist in the input cube file
name, ".mag.cub" is appended to the output file name.  The EXTRA
parameter is for adding additional options to the "magcube" program
for every file.  For example, if you want to convert all the files
to floating point, use EXTRA="OTYPE=1".

FPATH is provided if the user would like to redirect the files
created by the "magcube" application to another directory.

Additionally, the number of lines, samples and name of the file that
has the has satisfied the SELECTed criteris is returned to the caller
in the LINE, SAMPLE and BIGGEST return parameters.  For command line
users, the results are stored in the "isis_param.out" file.  In some
cases there is not a single file that satisfies the SELECTed option.
In this case, "NONE" is returned in BIGGEST.  The number of files
that do not have the maximum number of lines and samples is also
returned in the NODDS parameter.

Here is an (obfuscated) example for running spatialmax from the
command and the results also ran from the command line:

spatialmax FROMLIST=spatial.lis ATODDS=oddones.lis \
  MAGSCRIPT=magit.scr FPATH=/work1/kbecker/MER/forJJ \
  EXTRA=\"'otype=2 orange=(0,1)'\"

PROGRAMMER: Kris Becker, USGS, Flagstaff, Az

Name of file containing
list of ISIS cubes

NONE

Choose which file is the
marker to find other files
that are do not have the same
spatial size:
NONE    - Just give report
BIGGEST - One with most pixels
LINE    - One with most lines
SAMPLE  - One with most samples

"MAX"

Name of file to generate
containing files that differ
spatially from the SELECTed
one

--		

Name of file containing
MAGCUBE script to apply
to files that are ATODDS

--		

Optional path to put MAGCUBE'ed
results if desired

--

Add extra commands to the result
of the magcube command line.
This is useful if you want to
convert all files to the same
scale and pixel type.

Example:
"otype=2 orange=(0,1)"

--

Returns the number of files
found that do not have the
maximum number of lines and
samples.

LOCALA

Returns the maximum number of
lines in all the files

Returns the maximum number of
samples in all the files

If applicable, returns the
name of first occuring single
file that has LINE and SAMPLE
dimensions.  If no file is
found to satisfy this, NONE
is returned.

LOCALS

ADDITIONAL NOTES:

Parm	Description
FROMLIST	FROMLIST is the name of a file that contains all the files that will be processed. Each file is opened and spatial properties are collected. This information is used to determine the requested data. Note that the BAND dimension is virtually ignored in each of the files.
SELECT	General HELP describes this parameter in detail and how it is used.
ATODDS	This (optional) parameter is the name of the file that is generated by this application. Its contents will be the names of all the files that are "at odds" with the "truth" image - the first occuring image that satisfies the SELECT criteria. All files that do not precisely match the spatial properties of the truth image will appear in this file.
MAGSCRIPT	This (optional) parameter is the name of a file that will be generated by this application. It is in the form of a Unix shell script that can be sourced (executed) from the command line that will run the ISIS "magcube" application on all files that are "at odds" with the chosen one "truth" file. Additional parameters to the "magcube" application can be provided in the EXTRA parameter. See also EXTRA.
FPATH	This parameter is soley provided to redirect the ISIS files generated by the "magcube" application to a specific directory other than their original location as provided in the FROMLIST.
EXTRA	This (optional) parameter is useful for providing additional constant parameters to the "magcube" application. The content of EXTRA will be appended to each instance of the "magcube" application in the MAGSCRIPT output file. One example of its use would be to convert all bit types of the output to floating point: EXTRA="OTYPE=3".
NODDS	This is a return parameter. It specifies the number of images in FROMLIST that are "at odds" with the SELECTed image. It is provided for a quick determination of files that are inconsistant with particular spatial properties.
LINES	This is a return parameter. It returns the number of LINES from the image that first matched the SELECT property.
SAMPLES	This is a return parameter. It returns the number of SAMPLES from the image that first matched the SELECT property.
BIGGEST	This is a return parameter. It returns the name of the file that first matched the SELECT property and is indicative of the spatial properties that was used to evaluate all other input files in FROMLIST.