Home

Quick Links

Software Manual
GitHub
API Reference

Documentation Versions

Latest Release
Dev
8.3.0
8.2.0
8.1.0
8.0.0
7.2.0
7.1.0
7.0.0
6.0.0
3.9.0
3.5.0
USGS

ISIS Application Documentation

nocam2map

Standard View | TOC | Home

Map project a cube without a camera model

Description
Categories
Groups
History

Description

This program will map project a raw instrument cube without a camera model. However, the lack of a camera model requires latitude/longitude information at each pixel in the raw cube. This must be facilitated through a latitude cube and longitude cube with the same size as the raw instrument cube.

The procedure to project the input cube is output driven. That is, we create an output map cube (as specified by the user) and at each output pixel, compute its projected latitude/longitude using the projection parameters. Using this coordinate we must search for that position in the two input cubes (latitude/longitude). If found, we will have a sub-pixel location that has a 1-1 correspondence with the raw instrument pixel. An interpolator (nearest neighbor, bilinear, or cubic convolution) is then used to compute a value for the output pixel.

Therefore, the root of the problem is finding the latitude/longitude in the two input cubes as it is a 2-dimensional search. We do this by first creating two polynomial functions of a user-specified order (DEGREE), one for sample and one for line. These functions, f(lat,lon) = sample and g(lat,lon) = line, are derived using a least-squares computation by collecting a sparse set of control points (line,samp)-to-(lat,lon). The sparseness is controlled by the SINC and LINC. Unfortunately, the polynomial is not accurate enough to supply the mapping to sub-pixel accuracy. The level of errors between the control points and the derived equations can be written to the RESIDUAL file for examination.

To achieve sub-pixel accuracy, we use the polynomials to get us close (generally within 6 pixels). Using this estimated location, two affine transforms are computed by collecting a small 3x3 window of control points. These equations are used to further refine the estimated location. We iterate this process until our estimated sample/line is within an acceptable tolerance (TOLERANCE) of latitude/longitude values contained in the two cubes (LATCUBE/LONCUBE) or until the number of iterations is exceeded (ITERATIONS).

Defining the output map projection is controlled as follows: 

        1To compute the scale we find the number of pixels from pixel (1, 1)
        to pixel (nsamples, nlines) in the input cube:
        sqrt[(nsamples-1)2 + (nlines-1)2]
        And the angle across this line:
        acos(cos(latitude_point1) * cos(latitude_point2) * cos(longitude_point1 - longitude_point2) + sin(latitude_point1) * sin(latitude_point2))
        The scale is equal to the number of pixels divided by the angle in pixels per degree.

If the program is run on an image with a camera model contained in the label, much of the model information is deleted in the output cube. This avoids display conflicts between the built in display solution of the camera model and that generated by the projection function.

This application fails to produce correct output with smaller cubes sized 5x1, 1x5 or smaller. The error message provided is: "**ERROR** Unable to solve-least squares using QR Decomposition. The upper triangular R matrix is not full rank in LeastSquares.cpp at 402." This issue occurs because there is not enough information provided by small cubes for the equations used.

Categories

Parameter Groups

Files

Name Description
FROM Input cube to be mapped
LATCUBE Input cube to read latitude values
LATTYPEThe latitude type
LONCUBE Input cube to read longitude values
LONDIRThe longitude direction
TO Newly mapped cube

Polynomial Fit

Name Description
DEGREEDegree of polynomial functions
SINCSample Increment
LINCLine Increment
RESIDUALSFile to write residuals to
NOWARPSpecify whether or not to warp the image

Mapping

Name Description
MAP File containing mapping parameters
PIXRES Defines how the pixel resolution in the output map file is obtained
RESOLUTIONPixel resolution
TARGETThe target planet to map from/to
EQURADIUSEquatorial radius of target
POLRADIUSPolar radius of target

Output Map Ground Range

Name Description
DEFAULTRANGEDefines how the default ground range is determined
MINLATStarting latitude
MAXLATEnding latitude
MINLONStarting longitude
MAXLONEnding longitude

Affine Correction

Name Description
TOLERANCEGeometric tolerance in pixels
ITERATIONSThe number of iterations to meet tolerance

Interpolation

Name Description
INTERPType of interpolation

Files: FROM

Description

This will specify the raw instrument cube to be mapped.

Type cube
File Mode input
Filter *.cub

Files: LATCUBE

Description

The DN values from this cube will be used as the latitude values for the input cube. The number of samples and lines must match the FROM cube.

Type cube
File Mode input
Filter *.cub

Files: LATTYPE

Description

Specify the latitude type, as either planetographic latitude or planetocentric latitude.

Type string
Default PLANETOCENTRIC
Option List:
Option Brief Description
PLANETOCENTRICPlanetocentric Latitude Sets the latitude to be in planetocentric coordinates.
PLANETOGRAPHIC Planetographic latitude Sets the latitude to be in planetographic coordinates.

Files: LONCUBE

Description

The DN values from this cube will be used as the longitude values for the input cube. The number of samples and lines must match the FROM cube.

Type cube
File Mode input
Filter *.cub

Files: LONDIR

Description

Specify the longitude direction, either positive east or positive west.

Type string
Default POSITIVEEAST
Option List:
Option Brief Description
POSITIVEEASTPositive East Longitude Sets the longitude direction to be positive east.
POSITIVEWESTPositive West Longitude Sets the longitude direction to be positive west.

Files: TO

Description

This file will contain the map projected cube.

Type cube
File Mode output
Filter *.cub

Polynomial Fit: DEGREE

Description

The order of the polynomial functions to compute sample/line from latitude/longitude.

Type integer
Default 3

Polynomial Fit: SINC

Description

The number of samples skipped over when adding points to the polynomial functions.

Type integer
Internal Default Computed

Polynomial Fit: LINC

Description

The number of lines skipped over when adding points to the polynomial functions.

Type integer
Internal Default Computed

Polynomial Fit: RESIDUALS

Description

If a file is specified, residuals for each point (line, sample) are written to the file for examination.

Type filename
File Mode output
Internal Default none

Polynomial Fit: NOWARP

Description

If set to true, the output cube will not be processed and warped. The program will simply calculate the polynomial fit with errors.

Type boolean
Default false
Exclusions
  • TO
  • MAP
  • PIXRES
  • RESOLUTION
  • TARGET
  • EQURADIUS
  • POLRADIUS
  • DEFAULTRANGE
  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON
  • TOLERANCE
  • ITERATIONS
  • INTERP

Mapping: MAP

Description

A file containing the desired output mapping parameters in PVL form. This file can be a simple hand produced label file. It can also be an existing cube label which contains a Mapping group. You can produce map file using the maptemplate program.

Type filename
File Mode input
Default Path $ISISROOT/appdata/templates/maps
Default $ISISROOT/appdata/templates/maps/sinusoidal.map
Filter *.map *.cub

Mapping: PIXRES

Description

This parameter is used to specify how the pixel resolution is obtained for the output map projected cube.

Type string
Default COMPUTE
Option List:
Option Brief Description
COMPUTECompute pixel resolution from input cube This option will automatically determine the pixel resolution from the input cube. The scale in pixels per degree is computed by calculating the angle from pixel (1,1) to pixel (nsamples, nlines) across the input cube and dividing the number of pixels across the line from pixel (1,1) to pixel (nsamples, nlines) by the angle.

Exclusions

  • RESOLUTION
MAPRead 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 pixel resolution from user in meters per pixel This option allows the user to specify the pixel resolution in meters per pixel using the RESOLUTION parameter.

Inclusions

  • RESOLUTION
PPD Get pixel resolution from user in pixels per degree This option allows the user to specify the pixel resolution in pixels per degree using the RESOLUTION parameter.

Inclusions

  • RESOLUTION

Mapping: RESOLUTION

Description

Specifies the pixel resolution in either meters per pixel or pixels per degree.

Type double
Minimum 0.0 (exclusive)

Mapping: TARGET

Description

This will specify the target planet to map from/to, i.e. Mars, Venus, etc.

Type string
Internal Default Read from FROM cube

Mapping: EQURADIUS

Description

The equatorial radius can be read using the NAIF routines to get the radius from the specified target planet, or read from the user.

Type double
Internal Default Read from Naif PCK kernel file
Minimum 0.0 (exclusive)
Inclusions
  • POLRADIUS

Mapping: POLRADIUS

Description

The polar radius can be read using the NAIF routines to get the radius from the specified target planet, or read from the user.

Type double
Internal Default Read from Naif PCK kernel file
Minimum 0.0 (exclusive)
Inclusions
  • EQURADIUS

Output Map Ground Range: DEFAULTRANGE

Description

This parameter is used to specify how the default latitude/longitude ground range for the output map projected cube 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 cube. Essentially, the ground range and pixel resolution are used to compute the size (samples and line) of the output cube.

Type string
Default COMPUTE
Option List:
Option Brief Description
COMPUTE 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.
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.

Output Map Ground Range: MINLAT

Description

The minimum latitude of the ground range. If this is entered by the user, it will override the default camera or map file 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)

Output Map Ground Range: MAXLAT

Description

The maximum latitude of the ground range. If this is entered by the user, it will override the default camera or map file 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

Output Map Ground Range: MINLON

Description

The minimum longitude of the ground range. 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

Output Map Ground Range: MAXLON

Description

The maximum longitude of the ground range. 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

Affine Correction: TOLERANCE

Description

When computing the sample/line to be mapped from input to output, the sample and line are determined from the polynomial fit function. The transform then calculates the pixel differences in stereographically projected latitude/longitude from the input at sample/line to the output's stereographically projected latitude/longitude. If this difference is greater than the tolerance, then an affine transformation is iteratively used until the difference is less than the tolerance or is set to null after a set number of iterations.

Type double
Default 1.0
Minimum 0.0 (exclusive)

Affine Correction: ITERATIONS

Description

If the tolerance has not been met in the number of iterations specified, then the pixel is not mapped to the output.

Type integer
Default 10
Minimum 1 (inclusive)

Interpolation: INTERP

Description

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

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

History

Noah Hilt2008-08-01 Original Version
Christopher Austin2009-01-27 Fixed parameter names
Noah Hilt2009-03-02 The min/max longitude/latitude are now converted from the input domain to the map file's domain if necessary.
Travis Addair2009-08-10 Mapping group parameters are now placed into the print file.
Annie Howington and Tracie Sucharski2012-01-13 Updated documentation.
Tracie Sucharski2012-12-06 Changed to use TProjection instead of Projection. References #775
Sasha Browsnberger2015-02-12 If it exists, certain camera model information is removed from the label in the output image.
Kristin Berry2015-07-22 Added NaifStatus::CheckErrors() to see if any NAIF errors were signaled. References #2248
Jeannie Backer2016-05-10 Replaced calls to NAIF routines (bodn2c and bodvar) with call to static method Isis::Target::radiiGroup. References #3934
Curtis Rose2016-05-16 Fixed an issue with small cubes (9x9 or less) causing application to become stuck in an infinite loop. References #2284. Also added to the description a message about why the application fails on small cubes (5x1, 1x5, or less).
U.S. Department of the Interior | U.S. Geological Survey
ISIS | Privacy & Disclaimers | Astrogeology Research Program
To contact us, please post comments and questions on the USGS Astrogeology Discussion Board
To report a bug, or suggest a feature go to: ISIS Github
File Modified: 02/24/2025 16:09:17