ISIS Application Documentation
Convert camera image to a map projection
Description
Categories
Groups
History
Description
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".
Categories
Related Applications to Previous Versions of ISIS
This program replaces the following
applications
existing in previous versions of ISIS:
- cam2map
- lev1tolev2
- plansinu
- planorth
Parameter Groups
Files
Name
|
Description
|
FROM |
Input cube to project
|
MAP |
File containing mapping parameters
|
TO |
Newly mapped cube
|
MATCHMAP | Match the map file |
Output Map Resolution
Name
|
Description
|
PIXRES | Defines how the pixel resolution in the output map file is obtained |
RESOLUTION | Pixel resolution |
Output Map Ground Range
Ring Longitude Seam Options
Name
|
Description
|
RINGLONSEAM |
How should images at the ring longitude seam be handled
|
Options
Files:
FROM
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
|
Files:
MAP
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
|
Files:
TO
Description
This file is the map projected (level2) image.
Type
| cube |
File Mode
| output |
Filter
|
*.cub
|
Files:
MATCHMAP
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
|
Output Map Resolution:
PIXRES
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
|
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
|
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
|
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
|
|
Output Map Resolution:
RESOLUTION
Description
Specifies the resolution in either meters per pixel or pixels per degree
Type
| double |
Minimum
| 0.0
(exclusive)
|
Output Map Ground Range:
DEFAULTRANGE
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
|
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
|
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
|
|
Output Map Ground Range:
MINRINGRAD
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)
|
Output Map Ground Range:
MAXRINGRAD
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
|
|
Output Map Ground Range:
MINRINGLON
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 |
Output Map Ground Range:
MAXRINGLON
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
|
|
Output Map Ground Range:
TRIM
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 |
Ring Longitude Seam Options:
RINGLONSEAM
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.
|
|
Options:
INTERP
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.
|
|
Options:
WARPALGORITHM
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
|
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
|
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
|
|
Options:
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)
|
History
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.
|
Jeff Anderson | 2012-04-30 |
Add forward and reverse patch rubbersheeting parameters.
|
Debbie A. Cook | 2012-07-06 |
Updated Spice members to be more compliant with Isis coding standards. References #972.
|
Ken Edmundson and Debbie A. Cook | 2013-03-06 |
Revised to work with ring data. References #975.
|
Jeannie Backer | 2013-03-12 |
Added appTests. Test coverage appears low (60% scope, 60% line, 38% function), however these
tests cover a large portion in all three categories for the code that does not apply to the GUI helper methods.
References #775.
|
Jeannie Backer | 2013-03-12 |
Re-added "if MATCHMAP" statements since the IsisAml is not interpreting exclusions as expected.
Added exclusion - if MATCHMAP is true, then the parameter RINGLONSEAM is excluded. References #775.
|