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".