pixel2map

The pixel2map program projects an ISIS level0 or level1 cube to a map-projected, ISIS level2 cube. Please note that pixels that fall in either polar region (i.e. latitude of 90.0 degrees or -90.0 degrees) cannot currently be processed and are assigned as NULL pixels (i.e. this is currently unsupported).

In order for pixel2map to run successfully, input cubes must have SPICE data. The program spiceinit should be used to attach the appropriate SPICE data to input cubes. If a shape model is provided (or added in spiceinit by default), orthorectification is supported through the determination of the field-of-view (FOV) latitude/longitude coordinates as they map onto the digital elevation map (DEM). The pixel2map program also requires a map projection specification. The map projection is defined using a PVL file specified with the MAP parameter. The maptemplate program can be used to create a map projection file.

The cam2map program also projects a cube and is recommended for most mapping applications. The cam2map program assumes contiguous pixels and will interpolate to fill any gaps that occur in the output image during projection. The pixel2map program will preserve these gaps where the pixels are not contiguous. This program is designed to project cubes for the following cases:

• pixels do not overlap spatially
• data is smeared from long exposure times and drifting (see FOVRANGE=FULLEXPOSURE)
• data is captured from spectrometers
• CRISM
• DAWN VIR
• NEARS MSI
• VIMS

It is important to note that when projecting multiple spectrometer images within a single run of pixel2map, the hyperspectral information present in the input may be compromised in the output projection because individual overlapping pixels are averaged in the output pixel. With a single observation as input, the hyperspectral information will be preserved. With multiple observations as input (by using FROMTYPE=FROMLIST and FROMLIST), each observation may have different geometry depending on the timeframe the observations were acquired. Input pixels from each input observation mapped to an overlapping output surface pixel will be averaged.

The following table indicates how pixel2map and cam2map differ:

pixel2map	cam2map
Uses a forward driven algorithm for projection.	Uses a reverse driven algorithm for projection.
Each input pixel is converted to a FOV polygon, typically using the latitude/longitude of the pixel corners, and rasterized into the output projected image by calculating output pixels that fall in the boundary of the input pixel.	Each input pixel is not converted to a polygon to be rasterized. Up to 16 input pixels are interpolated around the center latitude and longitude of the output map pixel.
The space between pixels is retained in the output projected cube.	The space between pixels are interpolated thus gaps are filled in the output projected cube.
The output cube will be spatially accurate for non-continuous pixels.	The output cube may not be spatially accurate as output pixels are interpolated.

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 will also result in a different spatial outcome.

Left Cube: cam2map was chosen to project the cube. Notice the scan lines have been interpolated/filled. If you want to preserve gaps, cam2map will not achieve this result (but nearest-neighbor interpolation will be more accurate). In addition, the cube is no longer accurate (traceable for this type of instrument).

Right Cube: pixel2map was chosen to project the cube. Notice the gaps are retained in the output and the cube is spatially correct.

Mapping Parameterization

Several parameters of the map projection have default values when not specified in the map projection file. The default projection is the system sinusoidal projection. 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 coordinate 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 with a Mapping group that is used to determine the default output map geometric extents and resolution. 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 Latitude 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 the 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. Problems at the Longitude Seams of The ISIS Workshop "Learning About Map Projections" includes an example to help illustrate the problem.

Output of pixel2map

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

Instantaneous FOV (IFOV) vs. Full FOV

As mentioned above, pixel2map uses a forward-driven mapping algorithm to create a projection. In short, this means that pixel2map determines a polygon (footprint) FOV for each input pixel and rasterizes it into the output image space. Depending on what the METHOD parameter has been set to, the input pixel DN value is included in the average of any output pixels that fall within the polygon.

The default behavior of pixel2map is FOVRANGE=INSTANTANEOUS. This means that the IFOV at the center time of the exposure is being used to determine each pixel's footprint. For spectrometers that have longer exposure times, this method does not adequately address any smearing that can occur due to drifting during the exposure. In order to account for smearing, FOVRANGE=FULLEXPOSURE can be used. This method determines a pixel's polygon by finding the IFOV polygons at the start time, middle time, and end time of the exposure and then drawing an envelope around these polygons. The images below visually demonstrate the differences between the two FOVRANGE parameter values.

For more details, see the parameter description for FOVRANGE or examples 3 and 4.

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. Processing a single cube at a time is recommended to avoid averaging output pixels with other observations not acquired close in time. 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 effectively projects and mosaics all input cubes given in the list to the same output map projected file. Use this option with caution. Overlapping output pixels will be averaged. If the input images vary in input resolution, viewing and illumination conditions, the output average could compromise the spectral data. 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 effectively 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	$ISISROOT/appdata/templates/maps
Default	$ISISROOT/appdata/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 override 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. Recall that any pixels that fall within the polar regions (-90 and 90 degrees latitude) will be assigned NULL values in the output.

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 meridians 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 minimum/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 minimum/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/longitude 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

The field of view for each pixel is determined by the time range specified.

Type	string
Default	INSTANTANEOUS
Option List:	Option Brief Description INSTANTANEOUS Uses the IFOV corresponding to the center pixel time. The IFOV at the center of the exposure will be used to map each pixel. Exclusions NUMIFOV FULLEXPOSURE Uses the full FOV for the entire exposure time. The full field of view will be used to map each pixel. This is determined by finding IFOVs at NUMIFOV times during the exposure. The maximum ground coverage area found by combining all of these IFOVs is used as the full FOV. This helps account for any smearing that occurs when drift occurs during exposure. NOTE: This option is currently not available for framing cameras.

Description

The number of instantaneous FOVs used to create the full FOV. The IFOVs are spaced equally in time across the exposure duration. The first IFOV will always be the beginning of the exposure and the last IFOV will always be the end of the exposure. Warning: increasing this number will dramatically increase the processing time of pixel2map. This parameter will almost never need to be changed from a default of 3. If the input image was captured by a spot spectrometer, has a long exposure time, and has non-linear drift, then increasing this number slightly may help create a more accurate full FOV. Again, it is very rare, if at all, that this parameter value should be changed.

Type	integer
Default	3
Minimum	3 (inclusive)

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 turned off then you have the choice of making the program continue or exit when the cube does cross the boundary.

Type	string
Default	AUTO
Option List:	Option Brief Description AUTO Automatically adjust 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.

In this example, we demonstrate projecting a CRISM image using the default pixel2map parameters. Note that the output retains the gaps in the data, indicating that the input pixels do not overlap spatially.

pixel2map from=crism.cub to=crism_default.cub

Input CRISM image

CRISM input image Parameter Name: FROM A CRISM image is being used for the input.

Output projected image	Output projected image Parameter Name: TO Project output image using default settings. Note the gaps in the projection.
Output count image	Output count image The count cube generated by pixel2map. Pixel values indicate how many input pixels were used to generate the average value for the respective output pixel.

In this example, we project a VIMS-IR image using the LONSEAM=CONTINUE parameter setting. This means when we cross the longitude boundary in the image, the longitude domain is not automatically reset. The output image is split at the longitude boundary that it crosses; therefore the entire range of the target body is included in the output, a full 360 degree longitude. Note that a count cube is still created when running the commands below, it is just ignored in this example.

pixel2map from=C1621694254_1.ir.band248.cub map=$ISISROOT/appdata/templates/maps/equirectangular.map to=default.cub lonseam=continue

Input VIMS-IR cube

Ingested VIMS-IR cube Parameter Name: FROM A VIMS-IR cube ingested with vims2isis.

Output projected VIMS-IR cube

Map projected VIMS-IR cube across the longitude seam Parameter Name: TO The output cube is projected across the longitude seam. When using LONSEAM=CONTINUE, the output cube longitude domain will not be reset when the data crosses the longitude seam. For this image, a large gap of NULL pixels shows up in the output because the entire longitude range of the target body is included.

In this example, we project a DAWN VIR image using an instantaneous field of view and a full field of view to determine the output pixels. This demonstrates FOVRANGE=INSTANTANEOUS (default setting for FOVRANGE). Note that a count cube is still created when running the commands below, it is just ignored in this example. Compare this with FOVRANGE=FULLEXPOSURE in Example 4.

pixel2map from=VIR_IR_1B_1_506266095_refl_1.b75.l1.cub map=$ISISROOT/appdata/templates/maps/equirectangular.map to=dawn_vir_instantaneous_fov.cub

Input image

Input image for pixel2map Parameter Name: FROM This is the input DAWN VIR (IR) image for this example. Note the output "strips" and compare these with the output image in Example 4.

Output image FOVRANGE=INSTANTANEOUS

Output image using FOVRANGE=INSTANTANEOUS Parameter Name: TO This is the output image for the first run (FOVRANGE=INSTANTANEOUS).

In this example, we project a DAWN VIR image and use each pixel's full field of view to determine the output pixels. This example demonstrates FOVRANGE=FULLEXPOSURE. Note that a count cube is still created when running the commands below, it is just ignored in this example.

pixel2map from=VIR_IR_1B_1_506266095_refl_1.b75.l1.cub map=$ISISROOT/appdata/templates/maps/equirectangular.map to=dawn_vir_full_fov.cub fovrange=fullexposure

Input image

Input image for pixel2map Parameter Name: FROM This is the input DAWN VIR (IR) image for this example.

Output image FOVRANGE=FULLEXPOSURE

Output image using FOVRANGE=FULLEXPOSURE Parameter Name: TO This is the output image for FOVRANGE=FULLEXPOSURE. When comparing to the previous example, note that the output image data accommodates drift (the "strips" are wider).