pixel2map

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

• The pixel2map application uses a forward driven algorithm.
• Each input pixel is converted to a polygon and rasterized into the output projected image by calculating output pixels that fall in the boundary of the input pixel.
• The space between pixels is retained in the output projected cube.

Versus

• The cam2map application uses a reverse driven algorithm.
• Each input pixel is not converted to a polygon and rasterized into the output projected image. The input pixels are calculated by pixels situated at the same latitude and longitude.
• The space between pixels are interpolated thus gaps are filled in the output projected cube.

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.

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 FROM A 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 FROMLIST Input 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

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

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

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

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

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 CENTER Add 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. WHOLEPIXEL Add 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.

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 CAMERA Compute resolution from input cube This option will automatically determine the resolution from the input cube specified using the FROM parameter. Exclusions RESOLUTION MAP Read 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

Description

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

Type	double
Minimum	0.0 (exclusive)

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 MINIMIZE Minimize 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

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)

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

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

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

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

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 AUTO Automatically 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. ERROR Abort program if cube crosses seam If the cube crosses the longitude seam the program will exit with an error message CONTINUE Continue 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.