Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions


ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation


maptemplate

Printer Friendly View | TOC | Home

Create map file template for a projection

Overview Parameters Example 1 Example 2

Description

This program produces a PVL formatted file that contains the mapping group keywords required to transform an image to a map projection.

Required Input

  • Map File Template output filename
  • Projection name
  • Additional parameters required for specific projections
  • Input list if CALC option will be used

Output

A PVL formatted Map File Template containing mapping group keywords for the selected projection. The '.map' extension is appended to the output file automatically, if the file extension is not provided by the user. The output file may contain all or some of the map specifications listed below:

  • User-preferred projection type (required)
  • Other keywords required for specific projections
  • Target body radii
  • Latitude/longitude coverage or ground range
  • Pixel resolution
  • Latitude and longitude definitions
  • Distance from center of target
  • Standard parallels

Map File Template Creation

To convert a raw instrument/camera cube (Level1) to a map projected image (Level2) the user must (1) create a custom PVL formatted text file, (2) use this maptemplate application to produce one, or (3) use the automated, projection-specific Map File Template in $ISISROOT/templates/appdata/maps. Whichever method that you choose, the Map File Template should contain the necessary keywords to project an image.

Map File Template Creation Choices:

  1. PVL formatted text file: you must make a list of parameters based on the projection you wish to use, and input the appropriate values for each. The following example is a custom Map File Template for defining the projection of an image of Mars to the sinusoidal projection:
     Group = Mapping
     TargetName         = Mars
     EquatorialRadius   = 3396190.0 <meters>
     PolarRadius        = 3376200.0 <meters>
     LatitudeType       = Planetocentric
     LongitudeDirection = PositiveEast
     LongitudeDomain    = 360
    
     ProjectionName     = Sinusoidal
     CenterLongitude    = 227.95679808356
    
     MinimumLatitude    = 10.766902750622
     MaximumLatitude    = 34.44419678224
     MinimumLongitude   = 219.7240455337
     MaximumLongitude   = 236.18955063342
    
     PixelResolution    = 426.87763879023 <meters/pixel>
     End_Group
    
  2. The example above contains both required and optional keywords.

  3. The maptemplate application: maptemplate will prompt you for all the necessary parameters to project your image. However, the planar and ring cylindrical projections are excluded from use in the application, because it requires keywords that are not defined in the program.

  4. Templates in $ISISROOT/templates/appdata/maps: the template contains all the parameters necessary to project an image, and only the Projection name is "uncommented" in the file. This is because some projections only require that you enter a projection name, and the default values are computed for the remaining keywords. In such cases where the default value cannot be calculated using the camera model or ISIS system default, you must "uncomment" the appropriate line(s) of the template and set the values. See example below:
    Group = Mapping
      ProjectionName  = LambertConformal
    # CenterLatitude  = 0.0 <degrees>
    # CenterLongitude = 0.0 <degrees>
    # Earth (ographic)
    # FirstStandardParallel  = 33.0 <degrees>
    # SecondStandardParallel = 45.0 <degrees>
    
    # Mars (ographic)
    # FirstStandardParallel  = 35.83 <degrees>  *Remove # to uncomment and change 35.83 to your value
    # SecondStandardParallel = 59.17 <degrees>  *Remove # to uncomment and change 59.17 to your value
      End_Group
    

Identifying Required Parameters:

The following is a list of projections and keywords that are required. When a keyword is missing, and you try to project an image using projection software like cam2map, an error will occur. Below is a list of projections and the keywords that must be in the Map File Template:

PROJECTION ASSIGN VALUES FOR THESE KEYWORDS
Lambert Conformal FirstStandardParallel, SecondStandardParallel
Oblique cylindrical PoleLatitude, PoleLongitude, PoleRotation
Point perspective Distance
Planar (unavailable in maptemplate) CenterRingRadius, CenterRingLongitude, RingLongitudeDirection, RingLongitudeDomain
Ring cylindrical (unavailable in maptemplate) CenterRingRadius, CenterRingLongitude, RingLongitudeDirection, RingLongitudeDomain


How the defaults are set for Mapping Group keywords:

DEFAULT SOURCE MAPPING GROUP KEYWORDS
From Label TargetName
From camera model CenterLatitude, CenterLongitude, MaximumLatitude, MaximumLongitude, MinimumLatitude, MinimumLongitude, PixelResolution, Scale
ISIS Map defaults LatitudeType (ocentric), LongitudeDomain (360), LongitudeDirection (East), ScaleFactor (1)
From PCK file for Target EquatorialRadius, PolarRadius
Not computed, user must set CenterRingLongitude, CenterRingRadius, Distance, FirstStandardParallel, MaximumRingLongitude, MaximumRingRadius, MinimumRingLongitude, MinimumRingRadius, PoleLatitude, PoleLongitude, PoleRotation, RingLongitudeDirection, RingLongitudeDomain, SecondStandardParallel


Maptemplate GUI Interface

Radio buttons in the GUI are used to select options. Once an option is selected, the required parameters pertinent to that option become activated; therefore the user should complete the highlighted fields in the different parameter sections. Use the right scroll bar on the right side of the GUI to see all the available options.

The Gear Button button is used for RNGOPT and RESOPT options. If the button is clicked, the range will be calculated and automatically entered in the GUI fields with the appropriate values. For SELECT, the File Tree Icon button is used to select a Map File Template, the View File Icon button is use to view the contents of the selected file at the bottom of the GUI, and the "Down Arrow" button is used to load the contents of the selected file into the appropriate GUI fields. When the target name is set and no other value is specified, the View File Icon button next to EQRADIUS is used to display the system radii in the log area.

Parameter Setting Action

PARAMETER ACTION
NONE No keywords regarding the target will be added to the Map File Template. The value for the required keywords is derived based on the ISIS defaults at the time of projection. If a target name is specified and no value is entered for radius, the system radii will be used.
USER The user must enter the target and the preferred settings for the selected projection. The user can select meters per pixel (MPP) or pixels per degree (PPD) to define the units for the value entered for Resolution. If MPP is chosen, the value is set for the keyword PixelResolution. If PPD is chosen, the value is set for the keyword Scale.
SELECT The target definition information is retrieved from an existing Map File Template. The information can be displayed in the log area or loaded into appropriate GUI fields. The Help buttons located by the radial fields can only be used when the GUI is used to specify the parameters.
CALC The application maptemplate will calculate the values using the files in the input list specified in the FROMLIST parameter. For the ground range, the keywords MinimumLatitude, MaximumLatitude, MinimumLongitude, and MaximumLongitude are set. The values for ground range are in degrees. For the resolution, the keywords PixelResolution and Scale are set. All the calculated values for resolution will be meters per pixel for the keyword PixelResolution.
RESCALCOPT The PixelResolution value is set based on whether the user selected HIGH, LOW, or AVERAGE when the CALC option is used to calculate the resolution.

Other Uses for Your Created Map file: The output Map File can be used in applications that use projections, such as cam2map, map2map, mapsize, skymap, and more.

See "Learning About Map Projections" to learn more about mapping keywords.



Categories


Related Objects and Documents

Applications


History

Elizabeth Ribelin2005-09-13 Original Version
Elizabeth Miller2005-11-17 Added .map extension to TO file and fixed bug with spaces in the projection name
Elizabeth Miller2006-05-18 Deprecated CubeProjection and ProjectionManager to ProjectionFactory
Robert Sucharski2006-06-02 Redid GUI, added code to calculate ground range and resolution using FROMLIST, and added Help buttons
Steven Lambright2008-04-23 Added oblique cylindrical projection
Steven Lambright2009-02-05 Fixed a problem that occurred when using "TARGOPT=USER", "RNGOPT=CALC" and not entering "EQRADIUS" or "POLRADIUS"
Steven Lambright2011-12-19 Updated documentation as per Ella Lee's recommendations in preparation for the January 2012 release.
Kimberly Oyama2013-04-03 Added support for Point Perspective Projection. Fixes #212.
Debbie A. Cook2013-04-16 Changed to use TProjection instead of Projection. References #775
Ella Mae Lee2013-11-25 Added LambertAzimuthalEqualArea and Robinson projections. Updated the user documentation, fixes #845.
Ella Mae Lee2013-12-12 Backward compatability issue due to parameter name change: TARGOPT options changed from SYSTEM to SELECT, IMAGE to NONE, and TARGDEF to FILE. The description was modified to describe the behavior when selected, fixes #845.
Jeannie Backer2016-04-22 Added error message to alert to the user when the program fails to find TargetRadii. Added errors appTest. References #3892

Parameter Groups

Files

Name Description
MAP Output text file containing mapping keywords and values
FROMLIST Input list of images used when calculation option is selected

Projection

Name Description
PROJECTION Projection selection for the map file

Projection Parameters

Name Description
CLON Center Longitude
CLAT Center Latitude
SCALEFACTOR Scale Factor
PAR1 First Standard Parallel
PAR2 Second Standard Parallel
PLAT Pole Latitude
PLON Pole Longitude
PROT Pole Rotation
DIST Distance from the center of the target in kilometers.

Target Parameters

Name Description
TARGOPT Target Selection Options
FILE Name of the Map File
TARGETNAME Name of the Target
LATTYPE Latitude type
LONDIR Longitude Direction
LONDOM Longitude Domain
EQRADIUS Equatorial Radius
POLRADIUS Polar Radius

Ground Range Parameters

Name Description
RNGOPT Ground Range Selection Options
MINLAT Minimum Latitude
MAXLAT Maximum Latitude
MINLON Minimum Longitude
MAXLON Maximum Longitude

Resolution Parameters

Name Description
RESOPT Resolution Selection Options
RESOLUTION Resolution
RESCALCOPT Calculated Resolution Selection Options
X

Files: MAP


Description

This file will contain the mapping information for a projection. If this file currently exists, the application overwrites the file. The '.map' extension will automatically append to the filename entered if you do not type in an extension. If the file name in the GUI field does not have the extension, add ".map" to the string before pressing the button to display the contents.

Type filename
File Mode output
Filter *.map *.cub
Close Window
X

Files: FROMLIST


Description

A list of file names that will be used to calculate the values when (CALC) option is selected for the ground range (RNGOPT) or resolution (RESOPT) parameters. It is also used when a user selects the help button for the two parameters.

Type filename
File Mode input
Internal Default Input list that is used only when CALC option is invoked
Filter *.lis
Close Window
X

Projection: PROJECTION


Description

This is the name of the projection for the map file being created. The maptemplate application currently does not support Planar and Ring Cylindrical projections.

Type string
Default SINUSOIDAL
Option List:
Option Brief Description
SINUSOIDAL Sinusoidal Projection Create a maptemplate for a sinusoidal projection.

Exclusions

  • CLAT
  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
MERCATOR Mercator Projection Create a maptemplate for a Mercator projection.

Exclusions

  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
  • CLAT
TRANSVERSEMERCATOR Transverse Mercator Projection Create a maptemplate for a transverse Mercator projection.

Exclusions

  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
  • CLAT
  • SCALEFACTOR
ORTHOGRAPHIC Orthographic Projection Create a maptemplate for an orthographic projection.

Exclusions

  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
  • CLAT
POLARSTEREOGRAPHIC Polar Stereographic Projection Create a maptemplate for a polar stereographic projection.

Exclusions

  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
  • CLAT
SIMPLECYLINDRICAL Simple Cylindrical Projection Create a maptemplate for a simple cylindrical projection.

Exclusions

  • CLAT
  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
EQUIRECTANGULAR Equirectangular Projection Create a maptemplate for an equirectangular projection.

Exclusions

  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
  • CLAT
LAMBERTCONFORMAL Lambert Conformal Projection Create a maptemplate for a Lambert conformal projection.

Exclusions

  • SCALEFACTOR
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
  • CLAT
  • PAR1
  • PAR2
LAMBERTAZIMUTHALEQUALAREA Lambert Azimuthal Equal-area Projection Create a maptemplate for a Lambert azimuthal equal area projection.

Exclusions

  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON
  • DIST

Inclusions

  • CLON
  • CLAT
OBLIQUECYLINDRICAL Oblique Cylindrical Projection Create a maptemplate for an oblique cylindrical projection.

Exclusions

  • CLON
  • CLAT
  • SCALEFACTOR
  • PAR1
  • PAR2
  • DIST

Inclusions

  • PROT
  • PLAT
  • PLON
POINTPERSPECTIVE Point Perspective Projection Create a maptemplate for a point perspective projection.

Exclusions

  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON

Inclusions

  • CLON
  • CLAT
  • DIST
ROBINSON Robinson Projection Create a maptemplate for a Robinson projection.

Exclusions

  • CLAT
  • DIST
  • SCALEFACTOR
  • PAR1
  • PAR2
  • PROT
  • PLAT
  • PLON

Inclusions

  • CLON
Close Window
X

Projection Parameters: CLON


Description

The center longitude to use for the mapping group.

Type double
Close Window
X

Projection Parameters: CLAT


Description

The center latitude to use for the mapping group.

Type double
Close Window
X

Projection Parameters: SCALEFACTOR


Description

The scale factor to use for the mapping group.

Type double
Close Window
X

Projection Parameters: PAR1


Description

The first standard parallel to use for the mapping group.

Type double
Close Window
X

Projection Parameters: PAR2


Description

The second standard parallel to use for the mapping group.

Type double
Close Window
X

Projection Parameters: PLAT


Description

The pole latitude to use for the mapping group.

Type double
Close Window
X

Projection Parameters: PLON


Description

The pole longitude to use for the mapping group.

Type double
Close Window
X

Projection Parameters: PROT


Description

The pole rotation to use for the mapping group.

Type double
Close Window
X

Projection Parameters: DIST


Description

Distance from the center of the target in kilometers: value should be greater than the target radius.

Type double
Close Window
X

Target Parameters: TARGOPT


Description

This option specifies how the target information will be created. The default is NONE. The other options are SELECT and USER. The NONE option will not add any target information to the map file, allowing the target information from the image to be used. The SELECT option allows the user to select an existing file with mapping group, and load the target loaded information in the GUI fields. The target information is written to the output file. The USER option allows the user to specify their target information.

Type string
Default NONE
Option List:
Option Brief Description
NONE No Target Information Output No target information is put into the map template file. This information is retrieved or calculated for the image at the time of projection.

Exclusions

  • FILE
  • TARGETNAME
  • EQRADIUS
  • POLRADIUS
  • LATTYPE
  • LONDIR
  • LONDOM
SELECT Select Existing File This parameter is used to select an existing File with mapping group information. The contents of the map file must be loaded into the GUI fields for the keywords to be written to the output Map file.

Exclusions

  • TARGETNAME
  • EQRADIUS
  • POLRADIUS
  • LATTYPE
  • LONDIR
  • LONDOM

Inclusions

  • FILE
USER User Input The user defines the target name, latitude type, longitude direction, longitude domain, equatorial radius, and polar radius.

Exclusions

  • FILE

Inclusions

  • TARGETNAME
  • LATTYPE
  • LONDIR
  • LONDOM
Close Window
X

Target Parameters: FILE


Description

This is the Map File Template that is used to set the target specific values in the mapping group for the projection.

Type filename
Filter *.map *.txt *.def *.pvl *.cub
Close Window
X

Target Parameters: TARGETNAME


Description

This is the name of the Target (your planet of interest) for the projection.

Type string
Close Window
X

Target Parameters: LATTYPE


Description

The latitude type for the projection. It can either be Planetocentric or Planetographic. PLANETOCENTRIC is the default.

Type string
Default PLANETOCENTRIC
Option List:
Option Brief Description
PLANETOCENTRIC Planetocentric Sets the latitude type in the mapping template to Planetocentric.
PLANETOGRAPHIC Planetographic Sets the latitude type in the mapping template to Planetographic.
Close Window
X

Target Parameters: LONDIR


Description

The longitude direction for the projection. It can have a direction of Positive East or Positive West. POSITIVEEAST is the default.

Type string
Default POSITIVEEAST
Option List:
Option Brief Description
POSITIVEEAST PositiveEast Longitude Direction Longitude values increase to the east.
POSITIVEWEST PositiveWest Longitude Direction Longitude values increase to the west.
Close Window
X

Target Parameters: LONDOM


Description

The longitude domain for the projection. It can either have a domain of 180 or 360. 360 is the default.

Type string
Default 360
Option List:
Option Brief Description
360 0 to 360 degree longitude values Sets the longitude domain in the mapping template to 360 degrees.
180 -180 to 180 degree longitude values Sets the longitude domain in the mapping template to 180 degrees.
Close Window
X

Target Parameters: EQRADIUS


Description

The equatorial radius value to put in the map template. If this value is left blank, the system default will be used.

Type double
Internal Default IAU Default
Close Window
X

Target Parameters: POLRADIUS


Description

The polar radius value to put in the Map File Template. If this value is left blank, the system default will be used.

Type double
Internal Default IAU Default
Close Window
X

Ground Range Parameters: RNGOPT


Description

This option specifies how the ground range information will be created. NONE is the default value. The other options are USER and CALC. For the NONE option, none of the ground range information is written to the map template file, allowing the range to be calculated from the image at the time of projection. For the USER option, the user enters their values for the ground range. For the CALC option, maptemplate calculates the ground range using the files in the input list (FROMLIST). If CALC option is used, the MinimumLatitude, MaximumLatitude, MinimumLongitude, and MaximumLongitude are added to the mapping group after the calculation is performed.

Type string
Default NONE
Option List:
Option Brief Description
NONE No ground range keywords are output No ground range values will be put into the mapping template. These values will be computed from the image at the time of projection.

Exclusions

  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON
USER User Entered Values The user enters the values to be used for the ground range.
CALC Calculate Ground Range Using Input List The values used for ground range will be calculated using the files in (FROMLIST).

Exclusions

  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON
Close Window
X

Ground Range Parameters: MINLAT


Description

The minimum latitude value in the mapping template will be set to this user entered value.

Type double
Minimum -90 (inclusive)
Maximum 90 (exclusive)
Less Than MAXLAT
Close Window
X

Ground Range Parameters: MAXLAT


Description

The maximum latitude value in the mapping template will be set to this user entered value.

Type double
Minimum -90 (exclusive)
Maximum 90 (inclusive)
Greater Than MINLAT
Close Window
X

Ground Range Parameters: MINLON


Description

The minimum longitude value in the mapping template will be set to this user entered value.

Type double
Less Than MAXLON
Close Window
X

Ground Range Parameters: MAXLON


Description

The maximum longitude value in the mapping template will be set to this user entered value.

Type double
Greater Than MINLON
Close Window
X

Resolution Parameters: RESOPT


Description

This option specifies how the resolution information will be created. The default is NONE. The other options are MPP, PPD, and CALC. The NONE option does not write any resolution information to the map file, allowing the resolution to be calculated from the image at the time of projection. The MPP and PPD option allow the user to enter their own value in meters per pixel or pixels per degree for the resolution. The CALC option will calculate the resolution using the files listed in the FROMLIST parameter.

Type string
Default NONE
Option List:
Option Brief Description
NONE No resolution keywords are output No resolution value will be put into the mapping template. It will be computed from the image at the time of projection.

Exclusions

  • RESOLUTION
  • RESCALCOPT
MPP Specify the PixelResolution in meters per pixel The unit for PixelResolution is set to meters per pixel in the map template file.

Exclusions

  • RESCALCOPT
PPD Specify the Scale in pixels per degree The unit for Scale is set to pixels per degree in the map template file.

Exclusions

  • RESCALCOPT
CALC Calculate Resolution Using Input Parameter FROMLIST The resolution will be calculated using the files in the FROMLIST parameter. The value that is returned will be in meters per pixel and assigned to PixelResolution keyword.

Exclusions

  • RESOLUTION
Close Window
X

Resolution Parameters: RESOLUTION


Description

This value is assigned to PixelResolution keyword if CALC or MPP was chosen, or Scale if PPD was chosen by the user.

Type double
Close Window
X

Resolution Parameters: RESCALCOPT


Description

This option specifies how the resolution information calculated for the files in FROMLIST will be used to set the value for PixelResolution. The default is HIGH. The other options are LOW and AVERAGE. The HIGH option gets the highest resolution from the list of images, the LOW option gets the lowest resolution, and the AVERAGE option calculates the average resolution from all of the files in the FROMLIST parameter to set the value for PixelResolution in the map template. All options output the resolution in meters per pixel.

Type string
Default HIGH
Option List:
Option Brief Description
HIGH Select Highest / Best Resolution Select the highest/best resolution from the images in the input list to define PixelResolution. Output is in meters per pixel.
LOW Select Lowest / Worst Resolution Select the lowest/worst resolution from the images in the input list to define PixelResolution. Output is in meters per pixel.
AVERAGE Calculate Average Resolution The average resolution is calculated from the input images and set to PixelResolution. Output is in meters per pixel.
Close Window

Example 1

Sinusoidal Map Template

Description

This example shows the contents of a PVL text file generated by the maptemplate application. The settings are in default status for this example except for the output filename and center longitude which must be entered by the user.
Group = Mapping
  ProjectionName     = Sinusoidal
  CenterLongitude    = 0.0
End_Group
End
        
The text above is the contents of the map template file when the following command line is executed.

Command Line

maptemplate map=out.txt clon=0.0
Run the maptemplate application specifying only the output file name and center longitude.

GUI Screenshot

Maptemplate GUI

Example GUI

Screenshot of maptemplate GUI before the center longitude was entered for the sinusoidal projection.


Example 2

Lambert Conformal Map Template

Description

This example shows the contents of a PVL text file for a Lambert conformal map projection based on user selected options. The output file, projection type, center latitude, center longitude, first and second standard parallels, target option, and target name are entered. The remaining settings are left in their default state.
Group = Mapping
  ProjectionName     = LambertConformal
  CenterLongitude    = 0.0
  CenterLatitude     = 90.0
  StandardParallel1  = 45.0
  StandardParallel2  = 55.0
  TargetName         = Mars
  EquatorialRadius   = 3396190.0 <meters>
  PolarRadius        = 3376200.0 <meters>
  LatitudeType       = Planetocentric
  LongitudeDirection = PositiveEast
  LongitudeDomain    = 360
End_Group
        
The text shown above is the contents of the output file created when the following command line is executed.

Command Line

maptemplate map=out.txt projection=LambertConformal clon=0.0 clat=90.0 par1=45.0 par2=55.0 targopt=user targetname=MARS
Run the maptemplate application by specifying the output file, projection type, center latitude, center longitude, first and second standard parallels, target option, and target name.