Home
About ISIS
Support
Download

ISIS 3

Documentation
Tutorials
Technical Documents

ISIS 2

Documentation
Tutorials
Technical Documents

Search

USGS

ISIS 3 Application Documentation


pixel2map

Standard View | TOC | Home

Convert camera image to a map projection using a forward driven algorithm

Description
Categories
Groups
History


Description

This specialized program projects an ISIS level0 or level1 cube to a map projected (ISIS level2) cube.

The program, cam2map, also projects a cube, and is recommended for most mapping applications. Use pixel2map to project cubes where pixels do not overlap, for instance in data from a point instrument such as Cassini VIMS, or the Mars Reconnaissance Orbiter CRISM instrument where scan lines may not overlap.

Note: pixel2map cannot currently process the input pixel which contains either pole (i.e. latitude of 90.0 degrees or -90.0 degrees), which will cause a NULL pixel in your output map projected cube where the pole is located.

How pixel2map and cam2map differ

Versus

The examples below are Mars Reconnaissance Orbiter/CRISM cubes where scan lines do not overlap in their original state. The major difference is in the output of the application used to project the cube. Both applications will project the cube, but also result in a different spatial outcome. Left Cube: cam2map was chosen to project the cube. Notice the scan lines have been interpolated thus filled. If you want to preserve gaps, cam2map will not achieve this result. In addition, the cube is no longer spatially correct. Right Cube: pixel2map was chosen to project the cube. Notice how the gaps are retained in the output. The cube is spatially correct.

The input cube requires SPICE data and therefore the program spiceinit should be run on it prior to pixel2map. The map projection is defined using a PVL file specified with the MAP parameter. The default projection is the system Sinusoidal projection ($ISIS3DATA/base/templates/maps/sinusoidal.map). To learn more about using map projections in ISIS, refer to the ISIS Workshop "Learning About Map Projections".

If you need to generate your own map file you can use the maptemplate program or alternatively, hand create a file using your favorite editor. The file need only specify the ProjectionName as defaults will be computed for the remaining map file parameters. The following table indicates how the defaults are established:

PARAMETER DEFAULT
TargetName Read from Instrument group in the input cube labels
EquatorialRadius
PolarRadius
Read from SPICE pck file set during spiceinit. The pck file is defined in the Kernels group via the TargetAttitudeShape keyword
LatitudeType Planetocentric
LongitudeDirection PositiveEast
LongitudeDomain Normally, 360. However, if the 180 domain causes less area to need to be projected then 180.
MinimumLatitude
MaximumLatitude
MinimumLongitude
MaximumLongitude
Computed from the input cube or read from the map file. However, any combination of the four values can then be overridden by the user. The values the user specifies are expected to be in the coodinate system of the projection.
PixelResolution
Scale
Computed from the input cube or read from the map file. The value can be overridden by the user.

If you only entered the input cube (FROM) and output cube (TO) and changed no other parameters the following is the default Mapping group:

  Group = Mapping
    TargetName             = Obtained from the Instrument group
    EquatorialRadius       = Obtained from TargetAttitudeShape kernel
    PolarRadius            = Obtained from TargetAttitudeShape kernel

    LatitudeType           = Planetocentric
    LongitudeDirection     = PositiveEast
    LongitudeDomain        = 360 (Could be automatically adjusted to 180 by LONSEAM)

    MinimumLatitude        = Computed from the input camera cube
    MaximumLatitude        = Computed from the input camera cube
    MinimumLongitude       = Computed from the input camera cube
    MaximumLongitude       = Computed from the input camera cube

    ProjectionName         = Sinusoidal
    CenterLongitude        = Average of MinimumLongitude and MaximumLongitude
    PixelResolution        = Computed from the input camera cube
  EndGroup
    
The map file can be an existing map projected (level2) cube. A level2 cube has PVL labels and contains the Mapping group. Depending on the values of the input parameters, the output cube can use some or all of the keyword values of the map file. For instance, setting MATCHMAP=true causes all of the mapping parameters to come from the map file, resulting in an output cube having the same number of lines and samples as the map file. If MATCHMAP=true and the map file is missing a keyword like PixelResolution, the application will fail with a PVL error. Setting MATCHMAP=false allows for some of the mapping components to be overridden by the user or computed from the FROM cube.

If you are attempting to construct a mosaic, it is important that the PixelResolution, EquatorialRadius, PolarRadius, LatitudeType, LongitudeDirection, LongitudeDomain, ProjectionName, and projection specific parameters (e.g., CenterLongitude, CenterLatitude) are the same for all cubes. That is, you should create one map file and use it as input for all the cubes in your mosaic. By letting the minimum and maximum latitude and longitude values default, the application will determine the coverage of each image. However, if the mosaic Latiude and Longitude range is entered, each output image will be projected to the full size of the mosaic resulting in large file sizes and images with many NULL pixels. The following Mapping group could be used for mosaicking:

 Group = Mapping
   ProjectionName         = Sinusoidal
   CenterLongitude        = 0
   PixelResolution        = 100 <meters>
 EndGroup
   

Finally, depending on the projection, problems can occur with cubes that fall on the projection longitude seam. For example, if you are making a mosaic with LongitudeDomain = 360 and your cube crosses 0/360 seam, this program would compute the default longitude range of the cube to MinimumLongitude = 0 and MaximumLongitude = 360. A very large output image could be created depending on the pixel resolution. The LONSEAM parameter allows you to selectively handle this case. If you are making mosaics near the seam you will need to understand and alter the default for this parameter. Section 14 of The ISIS Workshop "Learning About Map Projections" includes an example to help illustrate the problem.

Output of pixel2map

A single input file produces a projected level2 cube. A list of files (filelist) produces an averaged mosaic as output. A count cube that contains the number of input pixels averaged into each output pixel is created along with the output cube or mosaic.


Categories


Related Applications to Previous Versions of ISIS

This program replaces the following application existing in previous versions of ISIS:

Parameter Groups

Files

Name Description
FROMTYPEFrom type selection (From or FromList)
FROMA single input cube to project
FROMLISTInput list of cubes to be projected
MAP File containing mapping parameters
TO Newly mapped cube

Output Average

Name Description
METHODMethod used to calculate average for output pixels

Output Map Resolution

Name Description
PIXRESDefines how the pixel resolution in the output map file is obtained
RESOLUTIONPixel resolution

Output Map Ground Range

Name Description
DEFAULTRANGEDefines how the default ground range is determined
MINLATMinimum latitude
MAXLATMaximum latitude
MINLONMinimum longitude
MAXLONMaximum longitude
TRIM Null all pixels outside lat/lon boundaries

Longitude Seam Options

Name Description
LONSEAM How should images at the longitude seam be handled

Files: FROMTYPE

Description

This parameter indicates whether a single cube will be entered in the 'FROM' parameter or a file containing a list of cubes will be given by the 'FROMLIST' parameter.

Type string
Default FROM
Option List:
Option Brief Description
FROMA single input cube to project The specification of the input cube to be projected. The cube must have been initialized using the spiceinit program. This option allows a single input cube to be processed.

Exclusions

  • FROMLIST
FROMLISTInput list of cubes to be projected This option allows a list to be used to process multiple input cubes. All cubes contained in this list will be projected to the same output cube given in the 'TO' parameter. This effictively projects and mosaics all input cubes given in the list to the same output map projected file.

Exclusions

  • FROM

Files: FROM

Description

The specification of the input cube to be projected. The cube must have been initialized using the spiceinit program. This option allows a single input cube to be processed.

Type cube
Exclusions
  • FROMLIST
Filter *.cub

Files: FROMLIST

Description

This option allows a list to be used to process multiple input cubes. All cubes contained in this list will be projected to the same output cube given in the 'TO' parameter. This effictively projects and mosaics all input cubes given in the list to the same output map projected file.

Type filename
File Mode input
Exclusions
  • FROM
Filter *.lis

Files: MAP

Description

A file containing the desired output mapping parameters in PVL. This file can be a simple label file, hand produced, or created via the maptemplate program. It can also be an existing cube or cube label which contains a Mapping group. In the latter case the FROM cube will be transformed into the same map projection, resolution, etc.

Type filename
File Mode input
Default Path $base/templates/maps
Default $base/templates/maps/sinusoidal.map
Filter *.map *.cub

Files: TO

Description

This file is the map projected (level2) image. If multiple input cubes were given in 'FROMLIST', they will all be projected into this output image. A "count" cube is also created with the same filename with '-count-' appended. The DN values in this output cube indicate how many input pixels were included in the average calculation to create the output pixel.

Type cube
File Mode output
Pixel Type real
Filter *.cub

Output Average: METHOD

Description

This parameter is used to determine which input pixels get added to the average to create the output pixel.

Type string
Default CENTER
Option List:
Option Brief Description
CENTERAdd to average if pixel centers overlap Add the input pixel to the average of the output pixel if it intersects with the center of the output pixel.
WHOLEPIXELAdd to average if any part of the input pixel overlaps the output pixel Add the input pixel to the average of the output pixel if it intersects with any part of the output pixel.

Output Map Resolution: PIXRES

Description

This parameter is used to specify how the pixel resolution is obtained for the output map projected cube.

Type string
Default CAMERA
Option List:
Option Brief Description
CAMERACompute resolution from input cube This option will automatically determine the resolution from the input cube specified using the FROM parameter.

Exclusions

  • RESOLUTION
MAPRead resolution from input map file This option will use either the PixelResolution (meters/pixel) or Scale (pixels/degree) in the map file.

Exclusions

  • RESOLUTION
MPP Get resolution from user in meters per pixel This option allows the user to specify the resolution in meters per pixel using the RESOLUTION parameter

Inclusions

  • RESOLUTION
PPD Get resolution from user in pixels per degree This option allows the user to specify the resolution in pixels per degree using the RESOLUTION parameter

Inclusions

  • RESOLUTION

Output Map Resolution: RESOLUTION

Description

Specifies the resolution in either meters per pixel or pixels per degree

Type double
Minimum 0.0 (exclusive)

Output Map Ground Range: DEFAULTRANGE

Description

This parameter is used to specify how the default latitude/longitude ground range for the output map projected image is obtained. The ground range can be obtained from the camera or map file. Note the user can overide the default using the MINLAT, MAXLAT, MINLON, MAXLON parameters. The purpose of the ground range is to define the coverage of the map projected image. Essentially, the ground range and pixel resolution are used to compute the size (samples and line) of the output image.

Type string
Default MINIMIZE
Option List:
Option Brief Description
MINIMIZEMinimize output image size This option will use the camera and projection in combination to ensure the output image size (samples, lines) is minimized. Using a ground range can cause NULL padding for projections with curved merdians and/or parallels and hence large output images. The amount of padding can be quite large for extremely high resolution maps.

Exclusions

  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON
  • TRIM

Inclusions

  • LONSEAM
CAMERA Compute default range from input cube This option will automatically determine the mininum/maximum latitude/longitude from the input camera model cube specified using the FROM parameter.

Inclusions

  • LONSEAM
MAP Read default range from map file This option will read the mininum/maximum latitude/longitude from the input map file. All four values are expected to be defined.

Exclusions

  • LONSEAM

Output Map Ground Range: MINLAT

Description

The minimum latitude of the ground range. If this is entered by the user it will override the default camera or map value. By default, planetocentric latitudes are assumed unless the MAP file specifies otherwise.

Type double
Internal Default Use default range
Minimum -90.0 (inclusive)
Maximum 90.0 (inclusive)

Output Map Ground Range: MAXLAT

Description

The maximum latitude of the ground range. If this is entered by the user it will override the default camera or map value. By default, planetocentric latitudes are assumed unless the MAP file specifies otherwise.

Type double
Internal Default Use default range
Minimum -90.0 (inclusive)
Maximum 90.0 (inclusive)
Greater Than
  • MINLAT

Output Map Ground Range: MINLON

Description

The minimum longitude of the ground range. If this is entered by the user it will override the default camera or map value. By default, positive east longitudes in the range of 0 to 360 are assumed unless the MAP file specifies otherwise.

Type double
Internal Default Use default range

Output Map Ground Range: MAXLON

Description

The maximum longitude of the ground range. If this is entered by the user it will override the default camera or map value. By default, positive east longitudes in the range of 0 to 360 are assumed unless the MAP file specifies otherwise.

Type double
Internal Default Use default range
Greater Than
  • MINLON

Output Map Ground Range: TRIM

Description

If this option is selected, pixels outside the latitude/longtiude range will be trimmed (set to null). This is useful for certain projections whose lines of latitude and longitude are not parallel to image lines and sample columns.

Type boolean
Default FALSE

Longitude Seam Options: LONSEAM

Description

With this option you can turn on/off the automatic longitude domain switching that occurs when a file crosses the boundary of the longitude domain (0-360 or -180 to 180). If the switching is turn off then you have the choice of making the program continue or exit when the cube does cross the bounday.

Type string
Default AUTO
Option List:
Option Brief Description
AUTOAutomatically correct Longitude Domain If the cube crosses the longitude seam automatically compute the LongitudeDomain. When the cube is near 0 or 360 degrees the program will assume 180 LongitudeDomain. When the cube is near 180 or -180 degrees it will assume 360 LongitudeDomain.
ERRORAbort program if cube crosses seam If the cube crosses the longitude seam the program will exit with an error message
CONTINUEContinue program if cube crosses seam If the cube crosses the longitude seam the program will continue. The LongitudeDomain in the map file will be used. If the map file does not have a LongitudeDomain, 0-360 will be used. Note that this could create an extremely large image.

History

Stacy Alley2008-02-13 Original version
Steven Lambright2008-05-13 Removed references to CubeInfo
Christopher Austin2008-01-27 Fixed parameter names
Tracie Sucharski2012-09-12 Restored from revision 3911 and updated for revised IEXception, iString and FileName classes.
Debbie Cook2012-10-11 Updated to use new Target class. References Mantis ticket #775 and #1114.
Tracie Sucharski, Stuart Sides2013-07-30 Renamed from vims2map, generalized for all instruments, improved performance and accuracy. Fixes #1604.
Janet Richie, Ella Lee2013-11-21 Updated documentation.
Sasha Brownsberger2015-01-19 Updated function calls to reflect changes to ProcessGroundPolygons object.