Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions


ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation


pixel2map

Standard View | TOC | Home

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

Description
Categories
Groups
Examples
History


Description

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:

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.


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
FOVRANGEThe time range to be used to determine the FOV.
NUMIFOVThe number of instantaneous FOVs used to create the full FOV.

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. Processing a single cube at a time is recommended to avoid averaging output pixels with other observations not acquired close in time.

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

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

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 $ISISROOT/appdata/templates/maps
Default $ISISROOT/appdata/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 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
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 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

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/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

Output Map Ground Range: FOVRANGE

Description

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

Type string
Default INSTANTANEOUS
Option List:
Option Brief Description
INSTANTANEOUSUses 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
FULLEXPOSUREUses 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.

Output Map Ground Range: NUMIFOV

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)

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 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
AUTOAutomatically 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.
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.

Examples


Example 1

Default settings with MRO CRISM

Description

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.

Command Line

pixel2map from=crism.cub to=crism_default.cub
Project the CRISM cube using default pixel2map settings.

Input Image

Input CRISM image

CRISM input image

Parameter Name: FROM

A CRISM image is being used for the input.

Output Images

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.


Example 2

LONSEAM=CONTINUE with Cassini VIMS

Description

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.

Command Line

pixel2map from=C1621694254_1.ir.band248.cub map=$ISISROOT/appdata/templates/maps/equirectangular.map to=default.cub lonseam=continue
Project a VIMS-IR cube into an equirectangular mapping. When the longitude boundary is reached, continue to project pixels into the cube's longitude domain. The image is split at the longitude boundary that it crosses, the entire range of the target body is included in the output.

Input Image

Input VIMS-IR cube

Ingested VIMS-IR cube

Parameter Name: FROM

A VIMS-IR cube ingested with vims2isis.

Output Image

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.


Example 3

Instantaneous FOV with Dawn VIR

Description

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.

Command Line

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
Project the DAWN VIR image into an equirectangular projection using the default instantaneous field of view (FOVRANGE=INSTANTANEOUS) to determine the output pixel projections.

Input Image

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

Output image FOVRANGE=INSTANTANEOUS

Output image using FOVRANGE=INSTANTANEOUS

Parameter Name: TO

This is the output image for the first run (FOVRANGE=INSTANTANEOUS).


Example 4

FULL FOV with Dawn VIR

Description

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.

Command Line

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
Project the DAWN VIR image into an equirectangular projection using the full field of view of each pixel to determine the output pixel projections. This accounts for any smear that occurs with the long exposure times of the pixels.

Input Image

Input image

Input image for pixel2map

Parameter Name: FROM

This is the input DAWN VIR (IR) image for this example.

Output Image

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).


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.
Jeannie Backer2016-10-24 Added feature to allow user to use full exposure duration to get polygons corresponding to real FOV. Improved coding standards. Fixes #4476.
Ian Humphrey2016-11-18 Previous pixel2map was ignoring cube attributes when storing the FROM parameter internally. Running pixel2map now allows band selection on the FROM cube and FROMLIST cubes. Fixes #4520.
Ian Humphrey2016-11-30 IsisCube labels and tables are now attached to the output cubes if there is a single input image. Fixes #4433. Removed unused UniveralGroundMap instance. References #4495.
Curtis Rose2016-12-09 Added tests to for all errors. Fixed a check so now all files in a list have to have the same number of bands selected. References #4535.
Jesse Mapel2017-01-04 Added the NUMIFOV parameter to determine how many IFOVs are used when creating a full FOV. References #4576.
Jesse Mapel2017-04-10 Modified to no longer keep all cubes in the fromlist open. This resulted in crashing due to reaching the maximum number of open files when the fromlist was large. Cubes will now be opened one at a time and then closed before opening the next cube. Fixes #4761.
Ian Humphrey2017-05-23 Updated documentation and added examples. Fixes #4537.