cam2map

This program projects an ISIS level0 or level1 cube to a map (ISIS level2 cube). The input cube requires SPICE data and therefore spiceinit should be executed prior to running cam2map. The map projection is defined using a PVL file which is specified in cam2map in the MAP parameter. Note: the system defaults to the Sinusoidal projection (ISIS projection based templates are located in $ISISROOT/appdata/templates/maps). To learn more about using map projections in ISIS, refer to the ISIS Workshop "Learning About Map Projections".

If you only entered the input cube (FROM) and output cube (TO) and changed no other parameters, the following are the defaults for the Mapping group. Note: this is the PVL format you'll see in both the level2 ISIS cube header and the MAP file:

  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
    

If you need to generate your own map file you can use the maptemplate program, or alternatively, hand create a file using any text 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 (0-360). However, if the 180 (-180,180) domain definition creates a smaller projected cube, then use it instead.
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.

Alternatively, 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=yes 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=yes and the map file is missing a keyword like PixelResolution, the application will fail with a PVL error. Setting MATCHMAP=no 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 essential 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. Otherwise, the program will throw and error.

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 are 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, the program will compute the default longitude range of the cube to MinimumLongitude=0 and MaximumLongitude=360. A larger than necessary output image will be created, with size inversely proportional to 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.

Description

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

Description

A file containing the desired output mapping parameters in PVL format. This file can be a simple label file, or can be 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.

Type	cube
File Mode	output
Filter	*.cub

Description

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	PIXRES RESOLUTION DEFAULTRANGE MINLAT MAXLAT MINLON MAXLON LONSEAM

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.

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

Description

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	MINLAT

Description

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

Description

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	MINLON

Description

The image is modified. The pixel dimensions of the file are retained; therefore, the number of pixels is the same. However, the pixels that fall outside the default or specified latitude and longitude range are set to NULL.

If camera is selected:

• You can opt to trim or not trim
• You can trim by entering the lat/lon range
• You cannot use the minimize parameter

If map is selected:

• You can opt to trim or not trim
• You can trim by entering lat/lon range
• You cannot use the lonseam parameter
• You cannot use the minimize parameter

Type	boolean
Default	FALSE

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 turn 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 correct 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.

Description

This is the type of interpolation to be performed on the input.

Type	string
Default	CUBICCONVOLUTION
Option List:	Option Brief Description NEARESTNEIGHBOR Nearest Neighbor Each output pixel will be set to the pixel nearest the calculated input pixel. BILINEAR Bi-Linear interpolation Each output pixel will be set to the value calculated by a bi-linear interpolation of the calculated input pixel. CUBICCONVOLUTION Cubic Convolution interpolation Each output pixel will be set to the value calculated by a cubic convolution interpolation of the calculated input pixel.

Description

This parameter is used to choose the warping algorithm, either the forward patch algorithm or the reverse patch algorithm. The default is to automatically choose the algorithm based on the input camera type (e.g., framing, linescan, pushframe).

Type	string
Default	AUTOMATIC
Option List:	Option Brief Description FORWARDPATCH Forward patch warp algorithm Patches are uniformly distributed over the input cube (FROM). For each input patch, the lat/lons of the four corners coordinates are computed using the camera model. Those four lat/lon coordinates are used by the map projection to determine four output pixel coordinates. Then the four output to input image coordinates are fit with two affine transforms. That is, isamp=f(osamp,oline) and iline=g(osamp,oline) where f = A+B*osamp+C*oline and similarly for g. If the estimated input/sample line (as computed by the affine transform) at the center of the patch is within a tenth of a pixel of the actual computation using the projection and camera model, the affine transforms are used to place the calculated input pixels in the output patch (using the specified INTERPOLATOR). Exclusions OCCLUSION Inclusions PATCHSIZE REVERSEPATCH Reverse patch warp algorithm Patches are uniformly distributed over the output cube (map projected product). For each output patch, the lat/lons of the four corners coordinates are computed using the map projection. Those four lat/lon coordinates are used by the camera model to determine four input pixel coordinates. Then the four output to input image coordinates are fit with two affine transforms. That is, isamp=f(osamp,oline) and iline=g(osamp,oline) where f = A+B*osamp+C*oline and similarly for g. If the estimated input/sample line (as computed by the affine transform) at the center of the patch is within a tenth of a pixel of the actual computation using the projection and camera model, the affine transforms are used to place the calculated input pixels in the output patch (using the specified INTERPOLATOR). Inclusions PATCHSIZE AUTOMATIC Automatically select warp algorithm The automatic option will choose the appropriate algorithm depending on the camera type of the input cube (TO). If the cube is a framing camera image, the reverse algorithm will be used with a PATCHSIZE of 4. If the cube is a line scan image, the forward algorithm will be used with a PATCHSIZE of 5. If the cube is a push frame camera (e.g., LRO WAC, MRO MARCI, or THEMIS VIS) the forward transform with a PATCHSIZE of the pushframe framelet height will be used. It is recommended that you always use automatic for push frame cameras to ensure the patch size does not cross multiple framelets. Exclusions PATCHSIZE OCCLUSION

Description

The forward and reverse patch algorithms try to fit an affine transform between the camera model coordinate and projection coordinate using the four corners of the patches. Patches that are too large may run faster at the risk of missing higher resolution information about the DTM. For example, a patch of 256x256 may have the same elevation at the four corners and center of the grid, but a crater may exist in one of the four quadrants of the patch. The crater, up to 128 pixels in diameter, may not be properly orthorectified. In general, small patch sizes are recommended (e.g., 4, 8).

Type	integer
Minimum	1 (inclusive)

Description

This parameter is used to toggle the occlusion detection algorithm. If set true, then the occlusion detection algorithm locates and nullifies occluded pixels. A pixel is determined to be occluded if the lat/lon value of the pixel in projected image space does not match (within a tolerance) the lat/lon value of the pixel in unprojected image space.

Highly dependent on DEM / image pixel resolution and accuracy of coregistration between the two.

This parameter also significantly increases projection time. It is recommended that this option is only used on images with known areas of occlusion.

Type	boolean
Default	false

This example is the first of two different runs of cam2map demonstrating the LONSEAM option. In this case it is set to AUTO. All the user input parameters in this example are identical to the following example except for LONSEAM and TO. The default for LONSEAM is AUTO.

cam2map from=EN0108830655M.cub map=../IN/sinu.map to=EN0108830655M_sinu_auto.cub

cam2map LONSEAM=AUTO GUI

Example GUI The top of the GUI shows the parameters filled in for input files, output file, and output map resolution. The middle of the GUI illustrates the 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. The bottom of the GUI shows 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 demonstrating LONSEAM set to AUTO. Contrast this output with the next example which was created with the LONSEAM set to CONTINUE.

This example is the second of two different runs of cam2map demonstrating the LONSEAM option. In this case it is set to CONT. All the user input parameters in this example are identical to the previous example except for LONSEAM and TO.

cam2map from=EN0108830655M.cub map=../IN/sinu.map to=EN0108830655M_sinu_cont.cub lonseam=cont

cam2map LONSEAM=CONTINUE GUI

Example GUI The top of the GUI shows parameters filled in for input files, output file, and output map resolution. The middle of the GUI illustrates 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. The bottom of the GUI shows 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=CONTINUE

Output image for cam2map LONSEAM=CONTINUE Parameter Name: TO This is the output of cam2map demonstrating LONSEAM set to CONT. Contrast this output with the previous example which was created with the LONSEAM set to AUTO.

This example is the first of two different runs of cam2map demonstrating usage of MATCHMAP. In both this example and the next, MATCHMAP is set to YES. In this case MAP is an ISIS level 2 image. The mapping parameters of the output file will be read from the mapping group of the MAP level 2 image.

cam2map from=EN0108827082M.lev1.cub map=EN0108828436M.lev2.cub to=EN0108827082M.lev2.cub matchmap=yes

cam2map MATCHMAP GUI

Example GUI The top of the GUI reveals 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. The middle of the GUI shows 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). The bottom of the GUI shows 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 demonstrating 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.

This example is the second of two different runs of cam2map demonstrating usage of MATCHMAP. In both this example and the previous, MATCHMAP is set to YES. However, in this case MAP is an ISIS map file. The mapping parameters of the output file will be read from this map file.

cam2map from=EN0108827082M.lev1.cub map=EN0108828436M.map to=EN0108827082M.lev2.cub matchmap=yes

cam2map MATCHMAP MAP GUI

Example GUI The top of the GUI illustrates 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. The screen shot of the middle of GUI shows the 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). The bottom of the GUI shows 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 demonstrating 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.

In the GUI below, cam2map is set up to project the input (level1) image to a (level2) projected image. The latitude and longitude ranges are calculated using the CAMERA option, but note the trim option is not selected in order to output the full extent of the input image. In the example immediately following, the GUI is set up to trim the image to a specific latitude and longitude boundary (TRIM=YES).

cam2map from=P01_001489_2688_XI_88N339W.lev1eo.cub map=./npole.map to=no_trim_P01_001489_2688_XI_88N339W.lev1eo.cubSINU18 defaultrange=camera

TRIM=NO GUI

Example GUI Screen shot of the entire GUI with parameters filled in for FROM file, TO file, default PIXRES, and Output Map Ground Range set to the CAMERA of the input cube. The rest of the parameters are all set to the defaults.

TRIM=NO output

Output image for cam2map TRIM=NO Parameter Name: TO This is the output of cam2map with TRIM turned off.

This cam2map GUI is set up to trim the image to a specific latitude and longitude boundary.

cam2map from=P01_001489_2688_XI_88N339W.lev1eo.cub map=./npole.map to=trim2_P01_001489_2688_XI_88N339W.lev1eo.cub trim=yes defaultrange=camera minlat=87.3 maxlat=89.11 minlon=8 maxlon=74

TRIM=YES GUI

Example GUI Screen shot of the entire GUI with parameters filled in for FROM file, TO file, default PIXRES, Output Map Ground Range set to the CAMERA of the input cube, TRIM=YES, and MIN/MAX LAT/LON ranges are defined. The rest of the parameters are all set to the defaults.

TRIM=YES output

Output image for cam2map TRIM=YES Parameter Name: TO This is the output of cam2map with TRIM turned on.

Below is a Cassini ISS wide-angle image of Enceladus, in sinusoidal projection. It illustrates the anomaly that can happen using certain projections when TRIM=NO. Notice the "duplicated" data. The next example will show how to correct this problem.

cam2map from=CISSWA_Enceladus.cub map=sinu180.map to=CISSWA_Enceladus_notrim.cub defaultrange=camera

TRIM=NO GUI

Example GUI Entire cam2map GUI with parameters filled in for FROM file, TO file, default PIXRES, and Output Map Ground Range set to the CAMERA of the input cube. The rest of the parameters are all set to the defaults. Note: the DEFAULT value for the TRIM parameter is NO, and therefore, it is not necessary to define TRIM.

Map file	Input map file defining the attributes of the desired output map projection. This file is in PVL format.

TRIM=NO output

Output image for cam2map TRIM=NO Parameter Name: TO This is the output of the cam2map Sinusoidal projection with TRIM turned off.

Below is the same Cassini ISS wide-angle image of Enceladus used in Example #7. The GUI definitions illustrate how to use TRIM to eliminate the duplicated data created by this particular projection.

cam2map from=CISSWA_Enceladus.cub map=sinu180.map to=CISSWA_Enceladus_notrim.cub defaultrange=camera trim=yes

TRIM=YES GUI

Example GUI Entire cam2map GUI with parameters filled in for FROM file, TO file, default PIXRES, Output Map Ground Range set to the CAMERA of the input cube, and TRIM=YES. The rest of the parameters are all set to the defaults.

Map file	Input map file defining the attributes of the desired output map projection. This file is in PVL format.

TRIM=YES output

Output image for cam2map TRIM=YES Parameter Name: TO This is the output of the cam2map Sinusoidal projection with TRIM turned on.