maptemplate

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
   

The example above contains both required and optional keywords.


2. 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.
   
   
3. 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 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 button is used to select a Map File Template, the 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 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.

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

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

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

Description

The center longitude to use for the mapping group.

Type	double

Description

The center latitude to use for the mapping group.

Type	double

Description

The scale factor to use for the mapping group.

Type	double

Description

The first standard parallel to use for the mapping group.

Type	double

Description

The second standard parallel to use for the mapping group.

Type	double

Description

The pole latitude to use for the mapping group.

Type	double

Description

The pole longitude to use for the mapping group.

Type	double

Description

The pole rotation to use for the mapping group.

Type	double

Description

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

Type	double

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

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

Description

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

Type	string

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.

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.

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.

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

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

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

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

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

Description

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

Type	double
Less Than	MAXLON

Description

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

Type	double
Greater Than	MINLON

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

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

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.

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.

maptemplate map=out.txt clon=0.0

Maptemplate GUI

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

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.

maptemplate map=out.txt projection=LambertConformal clon=0.0 clat=90.0 par1=45.0 par2=55.0 targopt=user targetname=MARS