ringscam2map

This program projects an ISIS level0 or level1 cube to a map (ISIS level2 cube). The input cube requires SPICE data and therefore the program spiceinit should be run on it with shape set to RingPlane prior to ringscam2map. The map projection is defined using a PVL file specified with the MAP parameter. The system default is to use the Planar projection ($ISISROOT/appdata/templates/maps/planar.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
RingLongitudeDirection	CounterClockwise
RingLongitudeDomain	Normally, 360. However, if the 180 domain causes less area to need to be projected then 180.
MinimumRingRadius MaximumRingRadius MinimumRingLongitude MaximumRingLongitude	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

    RingLongitudeDirection     = CounterClockwise
    RingLongitudeDomain        = 360 (Could be automatically adjusted to 180 by RINGLONSEAM)

    MinimumRingRadius          = Computed from the input camera cube
    MaximumRingRadius           = Computed from the input camera cube
    MinimumRingLongitude          = Computed from the input camera cube
    MaximumRingLongitude          = Computed from the input camera cube

    ProjectionName         = Planar
    CenterRingLongitude        = Average of MinimumRingLongitude and MaximumRingLongitude
    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, RingLongitudeDirection, RingLongitudeDomain, ProjectionName, and projection specific parameters (e.g., CenterRingLongitude, CenterRingRadius) 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 ring radius and ring longitude values default, the application will determine the coverage of each image. However, if the mosaic Ring Radius and Ring 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         = Planar
   CenterRingLongitude        = 0
   PixelResolution        = 10000 <meters>
 EndGroup
   

Finally, depending on the projection, problems can occur with cubes that fall on the projection ring longitude seam. For example, if you are making a mosaic with RingLongitudeDomain = 360 and your cube crosses 0/360 seam, this program would compute the default ring longitude range of the cube to MinimumRingLongitude = 0 and MaximumRingLongitude = 360. A very large output image could be created depending on the pixel resolution. The RINGLONSEAM 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. Note that if the user chooses to match the map file, then the user can not set this parameter. The program will behave as if RINGLONSEAM="CONTINUE".

Description

The specification of the input cube to be projected. The cube must have been initialized using the spiceinit program with shape set to RingPlane.

Type	cube
File Mode	input
Filter	*.cub

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/planar.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 MINRINGRAD MAXRINGRAD MINRINGLON MAXRINGLON RINGLONSEAM

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 ring ground ranges (radius and longitude) 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 MINRINGRAD, MAXRINGRAD, MINRINGLON, MAXRINGLON 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 merdians and/or parallels and hence large output images. The amount of padding can be quite large for extremely high resolution maps. Exclusions MINRINGRAD MAXRINGRAD MINRINGLON MAXRINGLON TRIM Inclusions RINGLONSEAM CAMERA Compute default range from input cube This option will automatically determine the ring radius range (mininum ring radius, maximum ring radius) and the ring longitude range (minimum ring longitude, maximum ring longitude) from the input camera model cube specified using the FROM parameter. Inclusions RINGLONSEAM MAP Read default range from map file This option will read the ring ranges (RingRadiusMininum, RingRadiusMaximum, RingLongitudeMinimum and RingLongitudeMaximum keywords) from the input map file. All four values are expected to be defined. Exclusions RINGLONSEAM

Description

The minimum ring radius of the output map. If this is entered by the user it will override the default camera or map value. Units are meters.

Type	double
Internal Default	Use default range
Minimum	0. (inclusive)
Maximum	9999999999.0 (inclusive)

Description

The maximum ring radius of the output map. If this is entered by the user it will override the default camera or map value. Units are meters.

Type	double
Internal Default	Use default range
Minimum	0.0 (inclusive)
Maximum	999999999999.0 (inclusive)
Greater Than	MINRINGRAD

Description

The minimum ring longitude of the output map. If this is entered by the user it will override the default camera or map value. By default, clockwise ring 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 ring 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 ring 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	MINRINGLON

Description

If this option is selected, pixels outside the ring radius range or the ring longitude range will be trimmed (set to null). This is useful for certain projections whose lines of ring radius and ring longitude are not parallel to image lines and sample columns.

Type	boolean
Default	FALSE

Description

With this option you can turn on/off the automatic ring longitude domain switching that occurs when a file crosses the boundary of the ring longitude domain (0 to 360 or -180 to 180). If the automatic 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 AUTO If the cube crosses the seam, automatically switch the RingLongitudeDomain. If the cube crosses the ring longitude seam, then the program will automatically compute the RingLongitudeDomain. When the cube is near 0 or 360 degrees, the program will assume 180 RingLongitudeDomain. When the cube is near 180 or -180 degrees, the program will assume 360 RingLongitudeDomain. ERROR If the cube crosses the seam, abort the program. If the cube has a LongitudeDomain of 360 and the image crosses the seam at 0/360 degrees or or the cube has a LongitudeDomain of 180 and the image crosses the seam at -180/180 degrees, then the program will exit with an error message. CONTINUE If the cube crosses the seam, continue program and keep the RingLongitudeDomain. If the cube crosses the ring longitude seam, the program will continue. The RingLongitudeDomain will not be changed from the domain in the map file. If the map file does not have a RingLongitudeDomain, the default of 360 LongitudeDomain 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

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 radius/longitude of the four corner coordinates are computed using the camera model. Those four radius/longitude 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, inputsamp=f(outputsamp,outputline) and inputline=g(outputsamp,outputline) where f = A+B*outputsamp+C*outputline 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 specificed INTERPOLATOR). Inclusions PATCHSIZE REVERSEPATCH Reverse patch warp algorithm Patches are uniformly distributed over the output cube (map projected product). For each output patch, the radius/longitude of the four corners coordinates are computed using the map projection. Those four radius/longitude 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, inputsamp=f(outputsamp,outputline) and inputline=g(outputsamp,outputline) where f = A+B*outputsamp+C*outputline 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 specificed 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

Description

The forward and reverse patch algorithms try to fit an affine tranform between the camera model coordinate and projection coordinate using the four corners of the patches. Patchs 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 diamter may not be properly orthorectified. In general, small patch sizes are recommended (e.g., 4, 8). NOTE: For FORWARDPATCH, if the entered PATCHSIZE is less than or equal to 1, it is automatically reset to 3.

Type	integer
Minimum	1 (inclusive)