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:
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:
The example above contains both required and optional keywords.
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.
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:
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.
Added .map extension to TO file and fixed bug with spaces in the projection name
Elizabeth Miller
2006-05-18
Deprecated CubeProjection and ProjectionManager to ProjectionFactory
Robert Sucharski
2006-06-02
Redid GUI, added code to calculate ground range and resolution using FROMLIST, and
added Help buttons
Steven Lambright
2008-04-23
Added oblique cylindrical projection
Steven Lambright
2009-02-05
Fixed a problem that occurred when using "TARGOPT=USER", "RNGOPT=CALC" and not entering "EQRADIUS" or "POLRADIUS"
Steven Lambright
2011-12-19
Updated documentation as per Ella Lee's recommendations in preparation for
the January 2012 release.
Kimberly Oyama
2013-04-03
Added support for Point Perspective Projection. Fixes #212.
Debbie A. Cook
2013-04-16
Changed to use TProjection instead of Projection. References #775
Ella Mae Lee
2013-11-25
Added LambertAzimuthalEqualArea and Robinson projections. Updated the user
documentation, fixes #845.
Ella Mae Lee
2013-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 Backer
2016-04-22
Added error message to alert to the user when the program fails to find TargetRadii.
Added errors appTest. References #3892
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.
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
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.
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.
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).
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.
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.
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.
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.