ISIS Application Documentation
pixel2map | Printer Friendly View | TOC | Home |
Convert camera image to a map projection using a forward driven algorithm
Overview | Parameters | Example 1 | Example 2 | Example 3 | Example 4 |
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:
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:
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 EndGroupThe 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. CategoriesRelated Applications to Previous Versions of ISISThis program replaces the following application existing in previous versions of ISIS:
History
|
Parameter GroupsFiles
Output Average
Output Map Resolution
Output Map Ground Range
Longitude Seam Options
|
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: |
|
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 |
|
Filter | *.cub |
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 |
|
Filter | *.lis |
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 |
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 |
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: |
|
This parameter is used to specify how the pixel resolution is obtained for the output map projected cube.
Type | string | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Default | CAMERA | |||||||||||||||
Option List: |
|
Specifies the resolution in either meters per pixel or pixels per degree
Type | double |
---|---|
Minimum | 0.0 (exclusive) |
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: |
|
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) |
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 |
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 |
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 |
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 |
The field of view for each pixel is determined by the time range specified.
Type | string | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Default | INSTANTANEOUS | |||||||||
Option List: |
|
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) |
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: |
|
Example 1Default 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
Output Images
|
Example 2LONSEAM=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
Output Image
|
Example 3Instantaneous 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
Output Image
|
Example 4FULL 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
Output Image
|