USGS

Isis 2 Documentation


lev2raster Documentation

lev2raster - Rasterize data using latitude, longitude coordinates
lev2raster is a general purpose application that will rasterize data
contained in a file to a Level 2 ISIS image cube.  The raster data file
can be either binary or ASCII in nature.  The raster file is assumed to
contain data in a record-like format.  Each record must contain
latitude, longitude and raster data at a specific location within each
record.  A record is defined in a configuration file given in the CONFIG
parameter.  Each latitude and longitude coordinate is translated
(converted) to a line and sample location.  The actual line and sample
where the raster data is placed is a result of rounding of the
conversion from latitude,longitude to line, sample.  The raster data is
then "plotted" or placed in to that pixel location.  lev2raster
supports more than one band of raster data as long as the data is
stored contiguously in the raster data file (defined in CONFIG).

lev2raster can operate in several modes.  The MODE parameter allows the
user to create a new level 2 ISIS image cube using the "INIT" option.
The MODE="ADD" option allows the user to add raster data to an existing
level 2 projected file.

The INIT mode relies on the user to provide sufficient information to
create a proper level 2 cube.  There are several ways to do this.  The
easiest way is to provide the name of an existing level 2 image cube
in the INITFROM parameter.  The user can then modify many of the
projection characteristics using other input parameters.  The second
way is to completely provide all the information in input parameters.
The following is a list of projection parameters that can be used to
specify (INITFROM not provided) or alter (when INITFROM file is given)
projection characteristics:

TARGDEF  - The name of the target object from whence the data came.
           For example this can be "MARS", "EUROPA" or some other
	   supported planetary body.  It is typically only needed to
	   specify planet radii and the direction of postive longitude.
	   See $ISISDATA/targets for supported and recognized bodies.
	   This parameter is ignored if INITFROM is given, required if
	   its not given.
	
MAPPARS  - String to specify the name of the desired projection and any
           parameters specific to it as needed.  See the PDF description
	   in mappars.pdf. This file describes all supported ISIS
	   projections and their parameters.  This parameter is optional
	   if INITFROM is given and can be used to specify a completely
	   different projection.  It is required if INITFROM is not
	   given.  Example: "SINU:0,OCENTRIC".
	
LATRANGE - Use this parameter to set the minimum and maximum latitude to
           represent in the output projection.  All raster data that
	   falls outside this latitude range will not be included in the
	   output file.  If INITFROM is given, the ranges in this
	   projection are used.  It can be used to alter the latitude
	   range in INITFROM if so desired.  It is required when
	   INITFROM is not specified. Example: LATRANGE=(-40.5,-10.2)
	
LONRANGE - Use this parameter to set the minimum and maximum longitude
           to represent in the output projection.  All raster data that
	   falls outside this longitude rnage will not be included in
	   the output file.  If INITFROM is given, the ranges in this
	   projection are used.  It can be used to alter the longitude
	   range in INITFROM if so desired.  It is required when
	   INITFROM is not specified.  Example: LONRANGE=(10.5,45.0)

KM       - This parameter sets the resolution of the output projection
           in units of kilometers per pixel. Only one of KM or DEG can
	   be specified, not both.  One of KM or DEG is also required
	   for all runs of lev2raster.

DEG      - This parameter sets the resolution of the output projection
           in units of pixels per degree.  Only one of DEG or KM can be
	   specified, not both.  One of KM or DEG is also required for
	   all runs of lev2raster.
	
LATSYS   - This parameter is used *solely* to designate the latitude
           coordinate system LATRANGE parameter is specified in.  This
	   allows the user to specify these ranges in either
	   planetocentric or planetographic.
	
LONSYS   - This parameter is used *solely* to designate the longitude
           coordinate system LONRANGE parameter is specified in.  This
	   allows the user to specify these ranges in either -180 to 180
	   (180) or 0 to 360 (360) ranges.
	
The ADD option for MODE will allow the user to add input raster data
to an existing level 2 projected image.  This file can come from any
source and is not restricted to files created in previous lev2raster
runs.  In this case, all input projection modification parameters are
ignored.  These are TARGDEF, MAPPARS, LATRANGE, LONRANGE, KM, DEG,
LATSYS, LONSYS, and LONDIR.  The file specified in TO defines all these
and incoming latitude and longitude data are placed according to the
projection in the file.

The UPDATE parameter informs lev2raster how to handle the actual
incorporation of raster data when it encounters existing data.  Only for
UPDATE = "REPLACE", does this eliminate the need to read in existing
data from the input cube.  This option simply takes each raster DN and
replaces data at that pixel location with incoming data.  The UPDATE
mode = "PRESERVE" will look at each input pixel location and determine
if any data already exists there.  If so, the existing data will remain
in the output file and the input data is discarded.  For UDPATE =
"AVERAGE", the input data is merged, or averaged, with any existing data
in the input TO file.  An accurate average is maintained if the original
TO file was created using lev2raster.  A backplane named "RASTER_COUNT"
is created for all image cubes created using lev2raster.  This backplane
maintains a count of the number of "hits", or the number of pixels that
were placed at that particular line and sample location.  The average of
that location is computed using the following formula:

 odn[i] = ((idn[i] * RASTER_COUNT) + raster_dn[i]) / (RASTER_COUNT + 1)
 RASTER_COUNT = RASTER_COUNT + 1

This maintains a running average at that line/sample location for all
bands in the output image cube.  Note that this strategy is applied only
when the RASTER_COUNT backplane exists in the TO file.  Otherwise, a
normal average is computed for each band using:

 odn[i] = (idn[i] + raster_dn[i]) / 2.0

In the above equations, "odn" is the resulting output pixel, "idn" is
the existing input pixel, "raster_dn" is the input raster dn value,
"[i]" indicates the band, and "RASTER_COUNT" is the value of the
backplane count at that pixel location.

The PMEROFF parameter is a special parameter used to adjust longitudes
for offsets in prime meridians for certain planetary bodies.  The
motivation for this parameter comes from the data returned from the
Mars Global Surveyor (MGS) Mars Observer Camera (MOC), Thermal Emission
Spectrometer (TES) and Mars Observer Laser Altimeter (MOLA) and values
used for the prime meridian values for Mars for these data.  In ISIS,
MOC data was processed using IAU 2000 values for the prime meridian.
These values come directly from the contents of target definition files
in the $ISISDATA/targets directory, namely mars.def.N where N is the
highest occuring integer value.  At the time of this writing, MOC used
mars.def.3 which uses IAU 2000 values for PRIME_MERIDIAN_0 = 176.7215.
MOLA used IAU 1991 values for PRIME_MERIDIAN_0 = 176.868.  And TES used
PRIME_MERIDIAN_0 =176.901.  In order to compare these products directly,
one must adjust the longitude values of one to comparable prime meridian
of the other.  This parameter lives specifically for this purpose.  For
example, if we want to compare TES data to a specific MOC image (which
can be specified in the INITFROM parameter) all TES longitudes must be
adjusted to the MOC (IAU 2000) prime meridian value.  PMEROFF should
specify the difference that will be added to all longitudes in the
raster file prior to computing the output sample/line coordinate.  In
this example, we use 176.7215 (MOC) - 176.901 (TES) = -0.1795.

RASTER CONFIGURATION (CONFIG) FILE
The file specified by the CONFIG parameter defines the location and type
of the latitude, longitude and raster data values.  lev2raster supports
both binary data and ASCII data.  The descriptions of each one is
slightly different.  In general, the file is comprised of
"keyword = value" statements that define the location of the latitude,
longitude and raster data values in each record.  The file is similar
to PDS files but may not be completely compliant to PDS standards.
For example, a # character is used to designate a comment.  Comments
can also exist using the C language style.  Text can exist between "/*"
and "*/" characters.  Note that comments are not allowed on the same
line as a statement.  Blank lines are also allowed.

The configuration file has a general keyword section and three objects
that describe the latitude, longitude and raster data.  The general
keyword section describes information about the actual raster data file
and some general information about the data itself.  Each object
contains information specific to the data it is describing.

Following is a description of keywords that are in the general raster
configuration keywords section:

INTERCHANGE_FORMAT - This required keyword defines the type of raster
  data file as "BINARY" or "ASCII" in nature.  These are the only
  valid/supported types.

LATSYS - This required keyword specifies that latitudes are expressed
  in the "OCENTRIC" or "OGRAPHIC" latitude coordinate system.

LONSYS - This required keyword specifies that longitudes are expressed
  in ranges of -180 to 180 (180) or 0 to 360 (360).  Longitudes
  contained in the raster data file that exceed the specified range are
  adjusted to the designated range.

LONDIR - This required keyword specifies the direction of positive
  longitude is "WEST" or "EAST".  Longitude values in the raster data
  file are assumed to be expressed in the designated direction.

MAP_SCALE - This keyword specifies the scale of a single pixel or DN in
  spatial dimensions.  MAP_SCALE defines the pixel in kilometers per
  pixel.  Pixels are assumed to be square.  This value is also compared
  with the resolution specified in the mapping labels.  The values
  *must* be equivalent or an error condition will ensue.  MAP_RESOLUTION
  may be used instead of this keyword but one or the other must be
  present.

MAP_RESOLUTION - This keyword may be used instead of MAP_SCALE to define
  the pixel scale of the projection.  This value is specified in degrees
  per pixel.  Only one of MAP_RESOLUTION or MAP_SCALE should be
  specified.  Its definition is the same as MAP_SCALE except its units.

^RASTER - This required keyword specifies the name of the file
  containing the data to rasterize.  This is a binary file for
  INTERCHANGE_FORMAT = "BINARY" or an ASCII file for INTERCHANGE_FORMAT
  = "ASCII".  Contents of the configuration file describe the format of
  this raster data file.  It is a double quoted string and may contain
  environment variables and absolute paths prefixing the actual name of
  the file.

RECORD_SIZE - This keyword is required only for binary data files.  It
  is used to specify the size in bytes of each binary record in the
  raster data file.  It is needed to establish proper access to each set
  of latitude, longitude and raster data contained in the raster data
  file.  This keyword is ignored for ASCII raster data files.

START_BYTE - This optional keyword is used only for binary raster data
  files.  It is used to specify the size/length in bytes of a header in
  the binary data file.  It can also be viewed as specifing the number
  of bytes to skip at the beginning of the binary data file to establish
  the start of the first record in the file.  This keyword cannot be
  used in conjunction with the START_RECORD and will take precedence if
  both are specified.

START_RECORD - This optional keyword is used to specify where to start
  reading data from in the raster file.  For binary raster files, this
  is always a multiple of RECORD_SIZE bytes.  For ASCII files, this is
  a line number.  Valid ranges start with 1 being the first record/line
  in the raster file to N being the last record.  For binary files, this
  cannot be used with START_BYTE.

RECORDS - This optional keyword specifies the number of records to read
  from the raster data file.  This keyword can be used with both binary
  and ASCII raster data files.

LATITUDE - This OBJECT structure is required and defines the latitude
  field in the raster data file.  The format is similar to a PDS OBJECT
  definition.  The LATITUDE object format is:
    OBJECT = LATITUDE
      DATA_TYPE = 
      COLUMN_NUMBER =  #  For ASCII raster data only
         -OR-
      START_BYTE =          #  For binary raster data only
      BYTES =       #  For binary raster data only
    END_OBJECT = LATITUDE
  The values of the keywords differs for binary and ASCII.  See the
  relevant sections below for the complete definition of each raster
  data file type.

  All latitude values must be expressed in units of degrees.

LONGITUDE - This OBJECT structure is required and defines the longitude
  field in the raster data file.  The format is similar to a PDS OBJECT
  definition.  The LONGITUDE object format is:
    OBJECT = LONGITUDE
      DATA_TYPE = 
      COLUMN_NUMBER =  #  For ASCII raster data only
         -OR-
      START_BYTE =          #  For binary raster data only
      BYTES =       #  For binary raster data only
    END_OBJECT = LONGITUDE
  The values of the keywords differs for binary and ASCII.  See the
  relevant sections below for the complete definition of each raster
  data file type.

  All longitude values must be expressed in units of degrees.

RASTER - This OBJECT structure is required and defines the raster data
  field in the raster data file.  The format is similar to a PDS OBJECT
  definition.  The RASTER object format is:
    OBJECT = RASTER
      COUNT = n
      DATA_TYPE = 
      ITEMS = 
      COLUMN_NUMBER =  #  For ASCII raster data only
         -OR-
      START_BYTE =          #  For binary raster data only
      BYTES =       #  For binary raster data only
    END_OBJECT = RASTER
  The values of the keywords differs for binary and ASCII.  See the
  relevant sections below for the complete definition of each raster
  data file type.

  Note that "ITEMS" is only required if there is more than one band in
  the raster data file.

  Optional keywords in this object allow the user to specify details
  about spectral data.  These keywords are BAND_BIN_ORIGINAL_BAND,
  BAND_BIN_CENTER and BAND_BIN_WIDTH.  BAND_BIN_ORIGINAL_BAND
  is an integer keyword and specifies the original band number for each
  band.  If it does not exist in the config file, it defaults to 1 to n
  where n is the number of bands specified in the RASTER object (COUNT
  keyword).  BAND_BIN_CENTER is a real keyword and specifies the
  wavelength of each band in micrometers.  If this keyword is not given,
  it defaults to 1.0 to ((n) * 1.0).  BAND_BIN_WIDTH is a real keyword
  and specifies the Full Width at Half Maximum (FWHM).  If not provided
  it defaults to 1.0 to ((n) * 1.0).

  Generally, any keyword or comment may exist in the raster
  configuration file but they will be ignored.


ASCII RASTER CONFIGURATION FORMAT
An ASCII RASTER configuration file is identified by the value of the
INTERCHANGE_FORMAT keyword.  This keyword *must* have the value "ASCII".

The ASCII format for the raster configuration file describes the number
of header lines, the text fields for latitude, longitude and raster data
and the details about each element.  An ASCII raster data text field is
defined to be a number, integer or floating point form, that is
consistantly delimited by a set of characters.  The field delimiters are
typically a space or tab character.  The default field delimiter
characters used in lev2raster are space, tab and carrage return.  The
CONFIG file can specify a new character set to use as field delimiters
using the "FIELD_DELIMITERS" keyword.  This will *replace* the defaults
with whatever is specified in the value of the characters string.  An
example adding a comma to the list would be as follows:

FIELD_DELIMITERS = " \t\r,"

Note the characters '\t' and '\r'.  These are tab and carriage return
characters that are converted to their appropriate binary representation
in the lev2raster application.  You must specify all possible delimiters
in this keyword values.  Also note that double and single quoted strings
are supported and parsed correctly.  Because of this, double quoted
strings cannot contain double quotes (single quotes are OK, however) and
single quoted strings cannot contain single quotes (but double quotes
are OK).

Here is a small example of a raster data file named raster.dat that
contains 5 columns of data: detector, latitude, longitude, phase and
albedo data fields:

detector     latitude       longitude    phase    albedo
1        66.919998504    30.509999318    20.34    0.1224
2        65.489998536    30.699999314    20.34    0.1233
3        63.179998588    31.069999306    20.34    0.1216


Here is an example raster configuration file that describes this data
file:

######################################################################
#_Title raster.conf - Example ASCII config file for lev2raster
#
#_Descr This file describes four columns of data that is to be
#       rasterized by lev2raster.
#
#_Hist  Mar 08 2002 Kris Becker, USGS, Flagstaff Original Version
#_End
#######################################################################
INTERCHANGE_FORMAT = "ASCII"
LATSYS = "OCENTRIC"
LONSYS = 360
LONDIR = "WEST"
MAP_SCALE = 3.150 

^RASTER = "raster.dat"
START_RECORD = 2

OBJECT                = LONGITUDE
  DATA_TYPE           = ASCII_REAL
  COLUMN_NUMBER       = 3
  DESCRIPTION         = "Areocentric west longitude of target point"
  UNIT                = "DEGREE"
END_OBJECT            = LONGITUDE

OBJECT                = LATITUDE
  DATA_TYPE           = ASCII_REAL
  COLUMN_NUMBER       = 2
  DESCRIPTION         = "Areocentric latitude of target point"
  UNIT                = "DEGREE"
END_OBJECT            = LATITUDE

OBJECT                = RASTER
  COLUMN_NUMBER       = 5
  ITEMS               = 1
  DATA_TYPE           = ASCII_REAL
  DESCRIPTION         = "Data to rasterize in output cube"
  UNIT                = "albedo"
  BAND_BIN_ORIGINAL_BAND = 1
  BAND_BIN_CENTER = 0.0234
  BAND_BIN_WIDTH = 0.0015
END_OBJECT           = RASTER


The only valid data types for ASCII fields are "ASCII_REAL" and
"ASCII_INTEGER".  lev2raster will automatically count the total number
of records, or lines in the ASCII case, prior to processing.  Users can
limit the number of records processed by adding the "RECORDS" keyword
with a number that is less than or equal to the lines in the file less
the header lines.

BINARY RASTER CONFIGURATION FORMAT
Binary raster configuration files are identified by the value of the
INTERCHANGE_FORMAT keyword.  It *must* have the value "BINARY".

Binary raster config files have to specify a bit more information than
ASCII raster files.  The size of a binary record must be provided to
establish the size in bytes of each record.  The RECORD_SIZE keyword is
used to specify the number of bytes in all binary records in the file.
Each latitude, longitude and raster data fields must exist in the same
location within each record.

An additional keyword named START_BYTE can be used to specify the number
of bytes to skip to read the first record.  This is useful for binary
files that contain some kind of header.  START_BYTE specfies the first
byte of the first record where the first byte in the files is 1 (which
is the default).

Suppose we have a binary file named raster.bin of the same example we
used in the ASCII example with the following configuration:

Field      Byte Location    Data Type   Data Byte Size  Count
Detector               1   PC_INTEGER                4      1
Latitude               5      PC_REAL                8      1
Longitude             13      PC_REAL                8      1
Phase                 21      PC_REAL                8      1
Albedo                29      PC_REAL                4      2

Note the different types of each field.  lev2raster supports many more
types that is needed in ASCII files.  Each type has a system prefix
prepended to it that identifies its byte ordering.  In the above
example, the data was created on a PC or DEC Alpha system and is a least
significant byte (LSB) order using IEEE floating point representation.
Data created on a Sun Microsystems architecture is most significant byte
(MSB) order also using IEEE.  Only IEEE floating point values are
supported.  lev2raster has the ability to convert input raster data to
the proper byte order based upon these values.  So data created on a Sun
system can be read and converted on a PC system.

lev2raster supports the following data types:

Data                              DATA_TYPE    BYTES
1-byte unsigned integer    UNSIGNED_INTEGER        1
1-byte signed integer               INTEGER        1
2-byte unsigned integer    UNSIGNED_INTEGER        2
2-byte signed integer               INTEGER        2
4-byte unsigned integer    UNSIGNED_INTEGER        4
4-byte signed integer               INTEGER        4
4-byte real                            REAL        4
8-byte real                            REAL        8

The DATA_TYPE and BYTES keywords are all that is required to define any
of these data types.  lev2raster internalizes these data as 4-byte real
or 8-byte real ONLY.  Latitude and longitude values are internalized as
8-byte real (doubles) regardless of the actual representation.  Raster
data is always internalized as 4-byte real (float) regardless of the
actual data type.  Refer to the PDS workbook for further information on
PDS data type descriptions.

Here is the binary raster configuration file for the above binary data
description:

#######################################################################
#_Title raster.conf - Example binary config file for lev2raster
#
#_Descr raster.conf contains all the parameters that describe the
#       binary data described above.
#
#_Hist  Mar 08 2002 Kris Becker, USGS, Flagstaff Original Version
#_End
#######################################################################
INTERCHANGE_FORMAT = "BINARY"
LATSYS = "OCENTRIC"
LONSYS = 360
LONDIR = "WEST"
MAP_SCALE = 3.150 

^RASTER = "raster.bin"
RECORD_SIZE = 36 
START_BYTE = 1


OBJECT                = LONGITUDE
  DATA_TYPE           = PC_REAL
  START_BYTE          = 13
  BYTES               = 8
  DESCRIPTION         = "Areocentric west longitude of target point"
  UNIT                = "DEGREE"
END_OBJECT            = LONGITUDE

OBJECT                = LATITUDE
  DATA_TYPE           = PC_REAL
  START_BYTE          = 5
  BYTES               = 8
  DESCRIPTION         = "Areocentric latitude of target point"
  UNIT                = "DEGREE"
END_OBJECT            = LATITUDE

OBJECT                = RASTER
  DATA_TYPE           = PC_REAL
  START_BYTE          = 29
  BYTES               = 4
  ITEMS               = 2
  DESCRIPTION         = "Data to rasterize in output cube"
  UNIT                = "albedo"
  BAND_BIN_ORIGINAL_BAND = (1,2)
  BAND_BIN_CENTER = (0.0234, 0.0249)
  BAND_BIN_WIDTH = (0.0015, 0.0015)
END_OBJECT           = RASTER


GEOMETRIC COORDINATE SYSTEMS
The new ISIS geometry software, referred to as "Lev", has added
functionality for supporting different latitude and longitude
coordinate geometry.  LATSYS, LONSYS and LONDIR are used to specify
this information to ISIS geometry software so that projections can be
properly supported.

In the Lev software, there are 3 occurances of these parameters in one
form or another.  In lev2raster there is one additional occurance in the
raster configuration file that I will describe below.

1)  LATSYS and LONSYS appear explicity in user interface PDF files.
    This is mostly limited to geometry initialization applications such
    as levinit.  lev2raster also has these parameters.

    They are in level 2 (projection application) PDFs to notify the
    application which coordinate system input values are specified in.
    For example, LATRANGE require a minimum and maximum latitude range
    of representation.  LATSYS tells the application if the user
    provides them in planetographic (OGRAPHIC) or planetocentric
    (OCENTRIC) latitude coordinates.   LONSYS exists to notify the
    application how longitude ranges as specified in LONRANGE are
    specified.  They can range from -180 to 180 (180) degrees or 0 to
    360 (360) degrees.

2)  LATSYS and LONSYS are also found in the ISIS image cube labels in
    the IMAGE_MAP_PROJECTION keyword group.  LATSYS is stored in the
    KEYWORD_LATITUDE_TYPE keyword and used to establish subsequent user
    inputs and reported values.  LONSYS is stored in the
    LONGITUDE_SYSTEM keyword and specifies how longitudes are used and
    reported in subsequent ISIS applications.

3)  An equivalent to LATSYS is also used in the MAPPARS parameter for
    some projections.  This is of the form MAPPARS="SINU:0,OCENTRIC".
    Here, this notifies the Lev software the desired latitude system to
    used to compute physical storage locations (i.e., line/sample) for
    the geometric data.  Note that Simple Cylindrical and Sinusoidal
    projections can use both OCENTRIC and OGRAPHIC latitude coordinate
    systems to store data.  ALL OTHER PROJECTIONS USE OGRAPHIC!!

4)  The lev2raster application needs LATSYS, LONSYS and LONDIR in the
    raster configuration file to fully describe these elements for each
    latitude and longitude coordinate read from the raster data file.
    These can be entirely different than the other sources - lev2raster
    converts the raster geometry coordinates to whatever is needed for
    projection compatability.  LONDIR is an additional parameter used to
    specify the direction of positive longitude of the raster longitude
    geometry.

For lev2raster to be thorough and perform correctly, all these
parameters must be considered carefully.  See also the mappars PDF in
the ISIS system for further information.

PROGRAMMER: Kris Becker, USGS, Flagstaff, Az

ParmDescriptionDefault
TO
Output rasterized level 2 cube
filename to create or add raster
data to
NONE
INITFROM
Optional input ISIS level 2
cube name used to initialize
projection and label parameters
--
MODE
File processing mode:
INIT - Create new file
ADD  - Add data to existing
       file
"INIT"
UPDATE
Update mode for existing
data merge:
REPLACE  - replace any data
           at output location
PRESERVE - do not replace any
           existing data
AVERAGE  - Average existing data
           with new data
"AVERAGE"
CONFIG
Name of text configuration
file for the binary raster
data
--
TARGDEF
Target definition filename
used only to establish planet
or body radii (level 2)
--
MAPPARS
Map projection and parameters
(e.g. MAPPARS="SINU:0,OCENTRIC")
--
LATRANGE
Latitude range
--
LONRANGE
Longitude range
--
KM
Image resolution (km/pix)
      or
--
DEG
Image resolution (pix/deg)
--
LATSYS
Latitude system used to report
values in:  OGRAPHIC or OCENTRIC
(default OGRAPHIC)
"OGRAPHIC"
LONSYS
Longitude system used to report
values in:
360 - 0 to 360
180 - -180 to 180
(default 360)
360
PMEROFF
Prime meridian adjustment
offset in degrees
0.0

ADDITIONAL NOTES:

ParmDescription
TO
Name of the output cube file for the MODE="INIT" option.
For the MODE="ADD" option is also the input file that the
raster file will be added/merged to.
INITFROM
Optional name of an existing ISIS level 2 projected file
which will be used to initialize the TO level 2 parameters.
This is very useful if the goal is to produce a projected
image for direct comparison to an existing product.
lev2raster will allow further modification to the projection
through other input parameters.  For example, you may have a
data set that has a different pixel resolution that another
product.  You would like to compare the two products
directly so it needs to have the same LATITUDE and LONGITUDE
ranges and projection parameters. The only difference being
the pixel resolution, the comparison product can be
specified in INITFROM and the user can use KM or DEG to
alter the pixel resolution.  Once you have created the
rasterized product at a different resolution, use the ISIS
application "lev2tolev" to specify the same pixel resolution
as the original product you wish to compare to.

See also lev2raster general help for further details on use
of this parameter.
MODE
This parameter specifies the action for handling the output
file specified in the TO parameter.  lev2raster can be used
to create a new level 2 image completely from scratch using
the "INIT" mode.  The user must supply the following minimum
parameters:

TARGDEF
MAPPARS
LATRANGE
LONRANGE
KM or DEG

The caller can provide the name of an existing ISIS level 2
projected file where all parameters are initialized from in
the INITFROM parameter.  The caller can also selectively
change any aspect of the projection using the above
parameters.

The other option is to update an existing level 2 projected
file using the "ADD" mode.  The file specified in TO must
exist and be a level 2 projected ISIS file.  All parameters
but CONFIG and UPDATE are ignored in this mode.
UPDATE
UPDATE provides users control over how raster data is added
to the file.  In may cases, data may map to the same line
and sample. The user may decide to use the UPDATE="REPLACE"
option which is essentially last-in precedence.  The last
value that maps into a particular line/sample replaces any
value previously there.  UPDATE="PRESERVE" has the opposite
effect - it will honor any exist valid value and never
replace it with any raster data that maps to the line/sample
location. The last option, UPDATE="AVERAGE" is a compromise
of the two options.  This option creates a BAND suffix named
"RASTER_COUNT" that accumulates the number of raster DN that
maps to the line/sample locations and maintains a running
average of this location.  A "running average" is
implemented in such a way that the final result is always
readily available after a run of lev2raster.  This is
acheived by taking the DN value at the line/sample location,
multiplying it be the count of DN previously added to it,
then adding in the incoming DN value and diving this sum by
the old count plus one. The count is then incremented by one
and rewritten to the backplane.  There are several
considerations to be aware of when this option is used.
1) When a file is initialized with this mode, it must be
used for any subsequent lev2raster run or incorrect results
may occur.  2) Selecting this option for a file that was not
originally initialized with option is allowed but it runs in
a different mode.  It will average any existing value with
the incoming DN but does not maintain a running average.  It
will only average the two values.  The problem with this
technique is that the last value in will have far more
weight if more than two values are averaged.  3)  To disable
this option, one can physically remove the RASTER_COUNT BAND
suffix using the ISIS "dsk2dsk" application and applying an
appropriate SFROM.
TARGDEF
This parameter is used to specify target parameters
definitions such as radii, omega 0, etc...  For lev2raster,
it is used only to define planet or body radii.  This is
essential for ISIS level 2 routines to compute latitude/
longitude and line/sample coordinates on the target body.
This parameter is not needed if INITFROM is provided and it
contains the desired target information.

TARGEF can be provided as the name of a planet (e.g., MARS)
in which case a file of the form "TARGDEF.def.n" will be
searched for in the $ISISDATA/targets directory.  "n" is
the highest occuring number starting with 1.  For example,
if Mars is the desired target then the default value will
be "$ISISDATA/targets/mars.def.n", "n" being the highest
version found.  Users can also specify an explicit file from
which to initialize from.  The format must follow the same
as those in the $ISISDATA/targets directory and one of these
files is a good starting point to developing your own.

This parameter is needed only when creating new files
(MODE="INIT") *and* INITFROM is not provided or is not
of the desired target body.
MAPPARS
This parameter is used to specify the map projection and its
specific parameters.  For example, "SINU:0,OCENTRIC" implies
Sinusoidal map projection with a central longitude of 0 and
values reported in planetocentric coordinate systems.

**NOTE** For a detailed explanation of MAPPARS, tutor the
mappars.pdf (i.e., TAE> tutor mappars).

This parameter is needed only when creating a new output
file (MODE="INIT") *and* INITFROM is not specified or does
not contain the proper projection parameters.
LATRANGE
Specifies the latitude range of the output projection.
LATRANGE(1) is the minimum latitude, LATRANGE(2) is the
maximum.  The coordinates specified here are subject to the
LATSYS parameter coordinate specification and must be
expressed in the system specified in this parameter.
LONRANGE
Specifies the longitude range of the output projection.
LONRANGE(1) is the minimum longitude, LONRANGE(2) is the
maximum.  The coordinates specified here are subject to the
LONSYS parameter coordinate specification and must be
expressed in the system specified in this parameter.
KM
This specifies the map resolution in kilometers/pixel.
DEG
This specifies the map resolution pixels/degree.
LATSYS
This parameter is used to define the latitude system
computed by "lev1" programs.  Valid values are either
OGRAPHIC or OCENTRIC.  The default is OGRAPHIC.  Your
selection is written to the labels of the cube or table
file.  This effects programs which output or use the
latitude, for example, "qview", "lev1stats",
"lev1tolev2".

See also lev2raster general help for a very detailed
discussion on this and its associated parameters.
LONSYS
This parameter is used to define the longitude system
computed by "lev1" programs.  Valid values are either 180 or
360.  The default is 360 which implies longitudes will be
output in the range of 0 to 360.  The value 180 implies
longitudes will be output in the range of -180 to 180.
Your selection is written to the labels of the cube or
table file.  This effects programs which output or use the
latitude, for example, "qview", "lev1stats",
"lev1tolev2".

See also lev2raster general help for a very detailed
discussion on this and its associated parameters.
PMEROFF
This parameter allows the user to make adjustments to
each longitude value to adjust for differing prime
meridian values.  TES is one example where this parameter
is useful.

TES used IAU 1994 prime meridian values to compute
longitudes.  When attempting to compare/overlay TES
data to MGS MOC or MOLA data, the longitudes more than
likely were computed using a different prime meridian
for MARS.  By simply providing the difference between
the prime meridians for each instrument, TES can be
better aligned with MOC or MOLA.

This value is *added* to each longitude prior to mapping
to an output pixel location.  It is assumed to in units
of degrees.

Last updated: Jan 31 2005
File: pdfs2.html

Contact us online at the Isis Support Center: http://isisdist.wr.usgs.gov

ISIS Documentation Home Page