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.
