ISIS Application Documentation

maplab

Printer Friendly View | TOC | Home

Add Mapping group to the labels of a cube

Overview

Parameters

Example 1

Example 2

Example 3

Example 4

Description

The maplab application is used to geo-reference a map-projected cube by adding or updating the Mapping Group with projection and geo-referencing information. Maplab takes as input a map-projected cube and a map file. The user has the option to geo-reference by (LATITUDE,LONGITUDE)-coordinates or by (X,Y)-map-projected-coordinates that correspond to a given (SAMPLE,LINE)-coordinate in the input cube.

The map file must contain information pertaining to the specifics of the cube's map-projection parameters, along with the target, body radius, longitude direction, latitude type and scale. We suggest running the maptemplate program to generate the map file provided as input.

NOTE that when selecting a SAMPLE and LINE for referencing known coordinates to a pixel, pixel coordinate (0.5, 0.5) is the top-left corner of the top-left pixel in the cube. By extension, (1.0, 1.0) is the center of the top-left pixel, and (1.5, 1.5) is the lower-right corner of the top-left pixel.

History

Jeannie Walldren	2008-01-17	Original version
Christopher Austin	2008-04-18	The input map will now use pixels/degree if no pixel resolution is found. If neither are present, throws an error. Both PixelResolution and Scale (pixels/degree) keywords will be in the output.
Travis Addair	2009-11-06	Added error checking to ensure that the provided map file has all the necessary keywords for later processing, and enhanced documentation to discuss necessary keywords and pixel coordinates.
Mackenzie Boyd	2011-04-11	Changed parameter LONG to LON, removed duplicate code.
Tracie Sucharski	2012-12-06	Changed to use TProjection instead of Projection. References #775

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/21/2025 19:28:12

Parameter Groups

Input Files

Name	Description
FROM	Input file to be geo-referenced
MAP	Input map file

Input Values

Name	Description
SAMPLE	Sample position in the cube
LINE	Line position in the cube
COORDINATES	Options for coordinate systems
X	X map-projected coordinate corresponding to (SAMPLE,LINE), meters
Y	Y map-projected coordinate corresponding to (SAMPLE,LINE), meters
LAT	Latitude coordinate corresponding to (SAMPLE,LINE), degrees
LON	Longitude coordinate corresponding to (SAMPLE,LINE), degrees

Input Files: FROM

Description

The cube whose label will be updated with Mapping Group information.

Type	cube
File Mode	input
Filter	*.cub

Close Window

Input Files: MAP

Description

File containing map projection parameters.

Type	filename
File Mode	input
Filter	*.map

Close Window

Input Values: SAMPLE

Description

The SAMPLE coordinate in the cube that corresponds to a known (X,Y) or (LATITUDE,LONGITUDE) coordinate. In ISIS, the upper-left corner of the upper-left pixel has coordinate 0.5.

Type	double

Close Window

Input Values: LINE

Description

The LINE coordinate in the cube that corresponds to a known (X,Y) or (LATITUDE,LONGITUDE) coordinate. In ISIS, the upper-left corner of the upper-left pixel has coordinate 0.5.

Type	double

Close Window

Input Values: COORDINATES

Description

A list of the different types of coordinates allowed by the application.

Type

string

Default

Option List:

Option

Brief

Description

Allows X, Y as Input Values

This option allows the user to enter the (X,Y) map projected coordinate (in meters) that corresponds to the given (SAMPLE,LINE) coordinate. This option excludes LATITUDE and LONGITUDE input values.

Exclusions

Inclusions

LATLON

Allows LAT, LON as Input Values

This option allows the user to enter the (LATITUDE,LONGITUDE) coordinate that corresponds to the given (SAMPLE,LINE) coordinate. The (LATITUDE,LONGITUDE) coordinate is in decimal degrees, and must be in the same LatitudeType and LongitudeDomain listed in the map file. This option excludes X and Y input values.

Exclusions

Inclusions

Close Window

Input Values: X

Description

The map-projection X-coordinate, in meters, corresponding to the the given (SAMPLE,LINE) coordinate of the cube.

Type	double

Close Window

Input Values: Y

Description

The map-projection Y-coordinate, in meters, corresponding to the given (SAMPLE,LINE) coordinate of the cube.

Type	double

Close Window

Input Values: LAT

Description

Latitude coordinate, in decimal degrees, for the given (SAMPLE,LINE) coordinate of the cube. It must be in the same LatitudeType listed in the map file.

Type	double

Close Window

Input Values: LON

Description

Longitude coordinate, in decimal degrees, for the given (SAMPLE,LINE) coordinate of the cube. It must be in the same LongitudeDomain listed in the map file.

Type	double

Close Window

Example 1

GeoTiff Header

Description

Most outside applications use the top left pixel (either upper-left edge or center) to define their location in X, Y. For example, a GeoTiff with an internal header, uses the upper left edge and for an example may report: Upper Left (2883258.0, 979924.0) -- meaning (X, Y). Thus for maplab, one would need to use the same top left corner of the pixel for ISIS, as illustrated in the command line below.

Command Line

maplab from=input.cub map=projection.map sample=0.5 line=0.5 x=2883258.0 y=979924.0

Mapping the upper-left of an ISIS cube (0.5, 0.5) to the upper left of the example image (2883258.0, 979924.0).

Data Files

Links open in a new window.

For this example, the original label already contained a Mapping Group.

Object = IsisCube 
  ...
  Group = Mapping
    ProjectionName     = Sinusoidal
    CenterLongitude    = 227.95679821639
    TargetName         = Mars
    EquatorialRadius   = 3396190.0 <meters>
    PolarRadius        = 3376200.0 <meters>
    LatitudeType       = Planetocentric
    LongitudeDirection = PositiveEast
    LongitudeDomain    = 360
    MinimumLatitude    = 10.76690271209
    MaximumLatitude    = 34.444196777763
    MinimumLongitude   = 219.72404560653
    MaximumLongitude   = 236.18955082624
    UpperLeftCornerX   = -480000.00000057 <meters>
    UpperLeftCornerY   = 2042000.0 <meters>
    PixelResolution    = 1000.0 <meters/pixel>
    Scale              = 59.274697523306 <pixels/degree>
    TrueScaleLatitude  = 0.0
  End_Group
  ...
End_Object

After the command line is run, the original Mapping Group is revised.

 
Object = IsisCube
  ...
  Group = Mapping
    ProjectionName     = Sinusoidal
    CenterLongitude    = 227.95679821639
    TargetName         = Mars
    EquatorialRadius   = 3396190.0 <meters>
    PolarRadius        = 3376200.0 <meters>
    LatitudeType       = Planetocentric
    LongitudeDirection = PositiveEast
    LongitudeDomain    = 360
    MinimumLatitude    = 10.76690271209
    MaximumLatitude    = 34.444196777763
    MinimumLongitude   = 219.72404560653
    MaximumLongitude   = 236.18955082624 
    UpperLeftCornerX   = 2883258.0 <meters>
    UpperLeftCornerY   = 979924.0 <meters>
    PixelResolution    = 1000.0 <meters/pixel>
    Scale              = 59.274697523306 <pixels/degree>
    TrueScaleLatitude  = 0.0
  End_Group
  ...
End_Object

Example 2

GIS Worldfile

Description

A typical image that has a "GIS Worldfile", in contrast to an internal GeoTiff header, uses the center of the top left pixel to define its location in X, Y. Thus a Worldfile might look like myImage.wld or *.tfw, *.jgw, *.pgw (depending on image type):

          2.0           Cellsize in X (meters)
          0.0           rotation/skew (normally 0)
          0.0           rotation/skew (normally 0)
          -2.0          Cellsize in Y (meters)
          -24243.731055 Upper-left pixel center X (meters)
          815863.281183 Upper-left pixel center Y (meters)

Thus for this example the user would need to run the program with the command line that follows.

Command Line

maplab from=input.cub map=projection.map sample=1 line=1 x=-24243.731055 y=815863.281183

Mapping the center of the upper-left pixel of an ISIS cube (1.0, 1.0) to the center of the upper left of the example image (2883258.0, 979924.0).

Example 3

Simple Cylindrical Global Case

Description

Say the global file is 1440x720 or 4ppd (and perfectly 0 to 360 lon and -90 to 90 lat). This global case would be run as follows.

Command Line

maplab from=input.cub map=projection.map sample=0.5 line=0.5 coordinates=latlong lon=0 lat=90

Or assuming clon is set to 180, > maplab ... sample=720.5 line=360.5 x=0 y=0

Example 4

Polar File

Description

Generally one will try to bring in a polar file which is 0 to 360 lon, extends to a common lat range, and centered at the pole (clat = 90 or -90). Nothing about the extent in meters is needed if the center of the image is again 90 or -90 lat. Again GIS/RS application will still to the upper left pixel but manually this can be harder to use than just using the center which will be defined as X,Y = 0,0 when in a Polar or Lambert Azimuthal projection. Using an example where the polar image is 2000 lines by 2000 samples then the run would look like:

Command Line

maplab from=input.cub map=projection.map sample=1000.5 line=1000.5 x=0 y=0

Assuming clat is 90 or -90.

Quick Links

Documentation Versions

maplab

Description

Categories

History

Parameter Groups

Input Files

Input Values

Input Files: FROM

Description

Input Files: MAP

Description

Input Values: SAMPLE

Description

Input Values: LINE

Description

Input Values: COORDINATES

Description

Exclusions

Inclusions

Exclusions

Inclusions

Input Values: X

Description

Input Values: Y

Description

Input Values: LAT

Description

Input Values: LON

Description

Example 1

Description

Command Line

Data Files

Example 2

Description

Command Line

Example 3

Description

Command Line

Example 4

Description

Command Line