Isis 3 Application Documentation
cam2map | Standard View | TOC | Home |
Convert camera image to a map projection
Description
Categories
Groups
Examples
History
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 EndGroupThe 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.
Name | Description |
---|---|
FROM | Input cube to project |
MAP | File containing mapping parameters |
TO | Newly mapped cube |
MATCHMAP | Match the map file |
Name | Description |
---|---|
PIXRES | Defines how the pixel resolution in the output map file is obtained |
RESOLUTION | Pixel resolution |
Name | Description |
---|---|
DEFAULTRANGE | Defines how the default ground range is determined |
MINLAT | Minimum Latitude |
MAXLAT | Maximum Latitude |
MINLON | Minimum Longitude |
MAXLON | Maximum Longitude |
TRIM | Null all pixels outside lat/lon boundaries |
Name | Description |
---|---|
LONSEAM | How should images at the longitude seam be handled |
Name | Description |
---|---|
INTERP | Type of interpolation |
The specification of the input cube to be projected. The cube must have been initialized using the spiceinit program.
Type | cube |
---|---|
File Mode | input |
Filter | *.cub |
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 |
This file is the map projected (level2) image.
Type | cube |
---|---|
File Mode | output |
Filter | *.cub |
This forces all of the mapping parameters to come from the map file. Additionally, when the map file is an image the TO file will have the same number of lines and samples as the map file.
Type | boolean |
---|---|
Default | false |
Exclusions |
|
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 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: |
|
The minimum latitude of the output map. 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 output map. 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 |
|
The minimum longitude of the output map. 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 output map. 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 |
|
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 |
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: |
|
This is the type of interpolation to be performed on the input.
Type | string | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Default | CUBICCONVOLUTION | ||||||||||||
Option List: |
|
Demonstrates the AUTO LONSEAM option
cam2map GUI part 1
|
Example GUI top of page Screen shot of top of GUI with parameters filled in for input files, output file, and output map resolution. |
cam2map GUI part 2
|
Example GUI middle of page Screen shot of middle of GUI with parameters filled in for the output map ground range and the longitude seam options. Under the output map ground range section, notice the grayed out parameters. These values are computed and not allowed to be modified when DEFAULTRANGE = MINIMIZE. This is the default. The LONSEAM option has been set to AUTO in this example. |
cam2map GUI part 3
|
Example GUI bottom of page Screen shot of the bottom of the GUI showing the Options menu. The default value for INTERP is selected (CUBICCONVOLUTION). |
Input Messenger image
|
Input image for LONSEAM examples
Parameter Name:
FROM This is a Messenger narrow angle camera image. |
Map file | Input map file defining the desired output map projection. This file is in PVL format. |
---|
Output of cam2map run with LONSEAM=AUTO
|
Output image for cam2map LONSEAM=AUTO
Parameter Name:
TO This is the output of cam2map demonstating LONSEAM set to AUTO. Contrast this output with the next example which was created with the LONSEAM set to CONT. |
Demonstrates the AUTO LONSEAM option
cam2map GUI part 1
|
Example GUI top of page Screen shot of top of GUI with parameters filled in for input files, output file, and output map resolution. |
cam2map GUI part 2
|
Example GUI middle of page Screen shot of middle of GUI with parameters filled in for the output map ground range and the longitude seam options. Under the output map ground range section, notice the grayed out parameters. These values are computed and not allowed to be modified when DEFAULTRANGE = MINIMIZE. This is the default. The LONSEAM option has been set to CONT in this example. |
cam2map GUI part 3
|
Example GUI bottom of page Screen shot of the bottom of the GUI showing the Options menu. The default value for INTERP is selected (CUBICCONVOLUTION). |
Input Messenger image
|
Input image for LONSEAM examples
Parameter Name:
FROM This is a Messenger narrow angle camera image. |
Map file | Input map file defining the desired output map projection. This file is in PVL format. |
---|
Output of cam2map run with LONSEAM=CONT
|
Output image for cam2map LONSEAM=CONT
Parameter Name:
TO This is the output of cam2map demonstating LONSEAM set to CONT. Contrast this output with the previous example which was created with the LONSEAM set to AUTO. |
Demonstrates one of two different ways to use MATCHMAP
cam2map GUI part 1
|
Example GUI top of page Screen shot of top of GUI with parameters filled in for input files, output file, and output map resolution. Notice that with MATCHMAP checked the remaining output map resolution parameters are grayed out to show that they are no longer available for input. All the mapping parameters will be read from the level 2 image entered for MAP. |
cam2map GUI part 2
|
Example GUI middle of page Screen shot of middle of GUI showing parameters for the output map ground range and the longitude seam options. Under the output map ground range section, notice all the parameters are grayed out. These values are all read or computed from the parameters in the mapping group of the level 2 image entered as the MAP and not allowed to be modified because MATCHMAP=YES. The LONSEAM option has been set to AUTO in this example (the default). |
cam2map GUI part 3
|
Example GUI bottom of page Screen shot of the bottom of the GUI showing the Options menu. The default value for INTERP is selected (CUBICCONVOLUTION). |
Input Messenger image
|
Input image for MATCHMAP examples
Parameter Name:
FROM This is a Messenger narrow angle camera image. |
Input level 2 image used for MAP
|
Input image for MATCHMAP examples
Parameter Name:
MAP This is a Messenger narrow angle camera image previously projected into an equirectangular map. |
Output of cam2map run with MATCHMAP=YES and map file
|
Output image for cam2map LONSEAM=AUTO
Parameter Name:
TO This is the output of cam2map demonstating the use of MATCHMAP=YES with an Isis level 2 image as MAP. Contrast this output with the level 2 image used as MAP and with the next example which was also created with MATCHMAP=YES, but uses an Isis map file as MAP. |
Demonstrates one of two different ways to use MATCHMAP
cam2map GUI part 1
|
Example GUI top of page Screen shot of top of GUI with parameters filled in for input files, output file, and output map resolution. Notice that with MATCHMAP checked the remaining output map resolution parameters are grayed out to show that they are no longer available for input. All the mapping parameters will be read from the map file. The application will throw an error if any required information is missing. |
cam2map GUI part 2
|
Example GUI middle of page Screen shot of middle of GUI showing parameters for the output map ground range and the longitude seam options. Under the output map ground range section, notice all the parameters are grayed out. These values are all read or computed from the map file values and not allowed to be modified because MATCHMAP=YES. The LONSEAM option has been set to AUTO in this example (the default). |
cam2map GUI part 3
|
Example GUI bottom of page Screen shot of the bottom of the GUI showing the Options menu. The default value for INTERP is selected (CUBICCONVOLUTION). |
Input Messenger image
|
Input image for MATCHMAP examples
Parameter Name:
FROM This is a Messenger narrow angle camera image. |
Map file | Input map file defining the desired output map projection. This file is in PVL format. |
---|
Output of cam2map run with MATCHMAP=YES and map file
|
Output image for cam2map LONSEAM=AUTO
Parameter Name:
TO This is the output of cam2map demonstating the use of MATCHMAP=YES with an Isis map file as MAP. Contrast this output with the previous example, which was also created with MATCHMAP=YES, but uses an Isis level 2 image for MAP. |
Kay Edwards | 1986-09-02 | Original version |
Jeff Anderson | 2003-05-02 | Converted to Isis 3.0 |
Jeff Anderson | 2003-06-05 | Added to Camera category |
Stuart Sides | 2003-07-29 | Modified filename parameters to be cube parameters where necessary |
Jeff Anderson | 2003-12-01 | Reworked defaults for user parameters |
Jeff Anderson | 2004-01-21 | Modified resolution parameters to eliminate inclusion/exclusion dependences. |
Jeff Anderson | 2004-02-13 | Added AUTOLON parameter |
Jeff Anderson | 2004-02-25 | Fixed bug with ground range user option |
Elizabeth Miller | 2005-10-25 | Added appTest |
Jacob Danton | 2005-12-02 | Updated appTest |
Elizabeth Miller | 2006-03-23 | Fixed appTest to reflect changes made in all camera models |
Tracie Sucharski | 2006-04-04 | Check to see if center of input image projects, if it does, force the tile containing center to be processed in ProcessRubberSheet. |
Jeff Anderson | 2006-04-04 | Reworked user interface |
Elizabeth Miller | 2006-04-10 | Reworked code for new user interface and added helper buttons |
Elizabeth Miller | 2006-05-18 | Depricated CubeProjection and ProjectionManager to ProjectionFactory |
Elizabeth Miller | 2006-05-30 | Moved Helper buttons and fixed error checking in helper methods |
Elizabeth Miller | 2006-09-06 | Modified call to ProjectionFactory CreateForCube method to include a value of false for the newly added sizeMatch parameter |
Jeff Anderson | 2006-12-06 | Test to see if target is sky and abort |
Jeff Anderson | 2007-03-13 | Add minimize option for DEFAULTRANGE |
Steven Lambright | 2007-06-22 | Fixed typo and corrected XML |
Steven Lambright | 2007-08-22 | Fixed lonseam option to work with minimize option correctly |
Stuart Sides | 2008-02-11 | Fixed bug where the ground range was not pulled from the map file when it was supposed to be (using DEFAULTRANGE = MAP). |
Christopher Austin | 2008-04-18 | Added the MATCHMAP option. |
Steven Lambright | 2008-05-12 | Removed references to CubeInfo |
Christopher Austin | 2008-07-15 | Changed MATCHMAP to default off |
Steven Lambright | 2008-08-04 | Changed MATCHMAP to have exclusions. If MATCHMAP is true, the PIXRES and DEFAULTRANGE options can not be set. Changed the code to enforce MATCHMAP. |
Steven Lambright | 2008-09-10 | Added the ability to change ProcessRubberSheet's tiling sizes. Now the Camera will decide upon the tiling sizes used in ProcessRubberSheet, in order to fix problems found with the push frame cameras which have small framelet sizes (less than 64 pixels tall). This is a passive ability with respect to the user; no options or differences should be noticable. |
Christopher Austin | 2008-10-31 | Fixed DEFAULTRANGE > CAMERA option to accept MINLAT, MAXLAT, MINLON, and MAXLON as overriding values. |
Christopher Austin | 2009-01-27 | Fixed parameter names. |
Travis Addair | 2009-08-10 | Mapping group parameters are now placed into the print file. |
Steven Lambright | 2011-01-31 | Improved documentation |
Jai Rideout | 2011-02-10 | Print file now includes PixelResolution, Scale, UpperLeftCornerX, and UpperLeftCornerY in Mapping group. |
Lynn Weller and Debbie A. Cook | 2012-01-17 | Updated documentation text, added glossary links, and improved compatability with Isis documentation. |