The MAP function displays map data in a graphics window.
Example
The following lines create the map shown at the top of this topic.
map = MAP('Hotine Oblique Mercator', $
ELLIPSOID='GRS1980', $
MARGIN=0.1, $
MERCATOR_SCALE=0.9996d, $
LIMIT=[40, -95, 50, -75], $
CENTER_LATITUDE=45.3091667d, $
HOM_AZIM_LONGITUDE=-86, $
HOM_AZIM_ANGLE=337.25556d, $
FALSE_EASTING=2546731.496d, $
FALSE_NORTHING=-4354009.816d, $
FILL_COLOR="light_blue", $
TITLE="Michigan GeoRef Projection")
grid = map.MAPGRID
grid.LINESTYLE = "dotted"
grid.LABEL_POSITION = 0
grid.FONT_SIZE=14
m1 = MAPCONTINENTS(/USA, $
FILL_COLOR="light green", COMBINE=0)
m2 = MAPCONTINENTS(/CANADA, $
FILL_COLOR="pale goldenrod")
m = map['Michigan']
m.FILL_COLOR = "green"
Additional Examples
See Map examples for additional examples using the MAP function.
Syntax
graphic = MAP(Projection, [, Map Properties=value] [, Map Grid Properties=value] [Keywords =value] [, Properties=value] )
Keywords
Keywords are applied only during the initial creation of the graphic.
/BUFFER, /CURRENT, /DEVICE, DIMENSIONS=[width, height], LAYOUT=array, LOCATION=[x, y], MARGIN=scalar or [left, bottom, right, top], /NO_TOOLBAR, /NODATA, /OVERPLOT, /WIDGETS
Properties
Properties can be set as keywords to the function during creation, or retrieved or changed using the "." notation after creation.
BACKGROUND_COLOR, BACKGROUND_TRANSPARENCY, FONT_COLOR, FONT_NAME, FONT_SIZE, FONT_STYLE, LIMIT, MAPGRID, MAP_PROJECTION, NAME, POSITION, TITLE, UVALUE, WINDOW, WINDOW_TITLE, XRANGE, YRANGE
Methods
Close
ConvertCoord
CopyWindow
Delete
Erase
Order
Print
Refresh
Rotate
Save
Scale
Select
Translate
MapForward
MapInverse
Return Value
The MAP function returns a reference to the MapProjection object. Use the returned reference to manipulate the graphic after creation by changing properties or calling methods.
Arguments
Projection
A string giving the name of the map projection. Available projections and their allowed parameters include:
# |
Name |
Allowed Map Parameters
|
Notes |
100 |
Geographic |
CENTER_LONGITUDE
|
No projection. |
101 |
UTM |
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, CENTER_LATITUDE, ZONE
|
All ellipsoids; cylindrical; conformal; scale is reduced along the central longitude (MERCATOR_SCALE=0.9996).
|
102 |
State Plane |
ZONE |
"Clarke 1866" or "GRS 1980" ellipsoid; uses either Transverse Mercator, Lambert Conformal Conic, or Hotine Oblique Mercator.
|
103 |
Albers Equal Area
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PAR1, STANDARD_PAR2, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; conic; equal-area; scale is true along the two standard parallels.
|
104 |
Lambert Conformal Conic
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PAR1, STANDARD_PAR2, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; conformal; scale is true along the two standard parallels.
|
105 |
Mercator |
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, TRUE_SCALE_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; cylindrical; conformal; scale is true along the true scale latitudes.
|
106 |
Polar Stereographic
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, TRUE_SCALE_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; azimuthal; conformal; scale is true along the true scale latitude.
|
107 |
Polyconic |
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; neither conformal nor equal-area; scale is true along all parallels and along the central meridian.
|
108 |
Equidistant Conic
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PARALLEL, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; equidistant; scale is true along all meridians and along one standard parallel.
|
208 |
Equidistant Conic
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, STANDARD_PAR1, STANDARD_PAR2, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; equidistant; scale is true along all meridians and along two standard parallels.
|
109 |
Transverse Mercator
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, MERCATOR_SCALE, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; cylindrical; conformal; scale is true (or reduced) along the center longitude.
|
110 |
Stereographic |
SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; azimuthal; conformal; scale is true at the center; directions from the center are true.
|
111 |
Lambert Azimuthal
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; azimuthal; equal-area; scale is true at the center; directions from the center are true for spherical and polar ellipsoidal.
|
112 |
Azimuthal Equidistant
|
SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; azimuthal; equidistant; distances measured from the center are true; directions from the center are true; scale is true at the center.
|
113 |
Gnomonic |
SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; also known as the Gnomic or Central projection; azimuthal and perspective; neither conformal nor equal-area; all great circles are straight lines; scale is true at the center; directions from the center are true.
|
114 |
Orthographic |
SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; azimuthal; neither conformal nor equal-area; scale is true in the direction of latitude lines for the polar aspect; directions from the center are true.
|
115 |
Near Side Perspective
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, HEIGHT, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids (default is Sphere); also known as the Vertical Perspective; azimuthal; neither conformal nor equal-area; scale is true at the center; directions from the center are true.
|
116 |
Sinusoidal |
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; pseudocylindrical; equal-area; scale is true along the central meridian and along all parallels.
|
117 |
Equirectangular |
SPHERE_RADIUS, CENTER_LONGITUDE, TRUE_SCALE_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; also known as equidistant cylindrical; neither conformal nor equal-area; scale is true along all meridians and along the true scale latitudes.
|
118 |
Miller Cylindrical
|
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; neither conformal nor equal-area; scale is true along the equator.
|
119 |
Van der Grinten |
SPHERE_RADIUS, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; neither conformal nor equal-area; scale is true along the equator.
|
120 |
Hotine Oblique Mercator
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, MERCATOR_SCALE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING, HOM_LONGITUDE1, HOM_LATITUDE1, HOM_LONGITUDE2, HOM_LATITUDE2
|
All ellipsoids; cylindrical; conformal; scale is true (or reduced) along the center line. Specified using two lat-lon points.
|
220 |
Hotine Oblique Mercator
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, MERCATOR_SCALE, HOM_AZIM_ANGLE, HOM_AZIM_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; cylindrical; conformal; scale is true (or reduced) along the center line. Specified using azimuthal angle and longitude of the center.
|
121 |
Robinson |
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; pseudocylindrical; neither conformal nor equal-area; scale is true along the 38° parallels.
|
122 |
Space Oblique Mercator
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, SOM_INCLINATION, SOM_LONGITUDE, FALSE_EASTING, FALSE_NORTHING, SOM_PERIOD, SOM_RATIO, SOM_FLAG
|
All ellipsoids; modified cylindrical; basically conformal; scale is true along the groundtrack. Specified using inclination, longitude, period, ratio, and flag.
|
222 |
Space Oblique Mercator
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, SOM_LANDSAT_NUMBER, SOM_LANDSAT_PATH, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; modified cylindrical; basically conformal; scale is true along the groundtrack. Specified using landsat number and path.
|
123 |
Alaska Conformal
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; conformal; modified stereographic using complex algebra transformations to reduce scale variations.
|
124 |
Interrupted Goode
|
SPHERE_RADIUS |
Sphere only; pseudocylindrical; equal-area; scale is true along the central meridians and along all parallels.
|
125 |
Mollweide |
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; pseudocylindrical; equal-area; scale is true along latitudes 40°44' N and S.
|
126 |
Interrupted Mollweide
|
SPHERE_RADIUS |
Sphere only; pseudocylindrical; equal-area; scale is true along the 40°44' parallels.
|
127 |
Hammer |
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; also known as Hammer-Aitoff; based on Lambert Azimuthal; equal-area but not azimuthal; scale is true at the center.
|
128 |
Wagner IV |
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; pseudocylindrical; equal-area; scale is true along the 42°59' parallels.
|
129 |
Wagner VII |
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING
|
Sphere only; modification of the Hammer; equal-area; scale is true at the center.
|
130 |
Oblated Equal Area
|
SPHERE_RADIUS, OEA_SHAPEM, OEA_SHAPEN, CENTER_LONGITUDE, CENTER_LATITUDE, FALSE_EASTING, FALSE_NORTHING, OEA_ANGLE
|
Sphere only; equal-area; lines of constant distortion follow approximately oval or rectangular paths.
|
131 |
Integerized Sinusoidal
|
SPHERE_RADIUS, CENTER_LONGITUDE, FALSE_EASTING, FALSE_NORTHING, IS_ZONES, IS_JUSTIFY
|
Sphere only; equal-area; same as sinusoidal but with discrete latitude bands.
|
132 |
Cylindrical Equal Area
|
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, STANDARD_PARALLEL, FALSE_EASTING, FALSE_NORTHING
|
All ellipsoids; cylindrical; equal-area; scale is true along the standard parallels (special cases: Lambert 0°, Behrmann 30°, Trystan Edwards 37.383°, Peters 44.138°, Gall orthographic 45°, Balthasart 50°.
|
133 |
GOES-R |
SEMIMAJOR_AXIS, SEMIMINOR_AXIS, CENTER_LONGITUDE, HEIGHT, FALSE_EASTING, FALSE_NORTHING |
All ellipsoids (default is GRS 1980); same properties as Near Side Perspective but (x, y) coordinates are in scan-angle radians. Default height is 35786023 meters. |
Map Properties
CENTER_LATITUDE
CENTER_LONGITUDE
ELLIPSOID
FALSE_EASTING
FALSE_NORTHING
HEIGHT
HOM_AZIM_ANGLE
HOM_AZIM_LONGITUDE
HOM_LATITUDE1 |
HOM_LATITUDE2
HOM_LONGITUDE1
HOM_LONGITUDE2
IS_JUSTIFY
IS_ZONES
LIMIT
MERCATOR_SCALE
OEA_ANGLE
OEA_SHAPEM |
OEA_SHAPEN
SEMIMAJOR_AXIS
SEMIMINOR_AXIS
SOM_FLAG
SOM_INCLINATION
SOM_LANDSAT_NUMBER
SOM_LANDSAT_PATH
SOM_LONGITUDE |
SOM_PERIOD
SOM_RATIO
SPHERE_RADIUS
STANDARD_PAR1
STANDARD_PAR2
STANDARD_PARALLEL
TRUE_SCALE_LATITUDE
ZONE |
See MAP_PROJ_INIT for descriptions of these properties.
Map Grid Properties
The following map graticule (grid) properties are available on creation:
BOX_ANTIALIAS
BOX_AXES
BOX_COLOR
BOX_THICK
CLIP COLOR
FILL_COLOR
FONT_NAME
FONT_SIZE |
FONT_STYLE
GRID_LATITUDE
GRID_LONGITUDE
HIDE
HORIZON_COLOR
HORIZON_LINESTYLE
HORIZON_THICK
LABEL_ALIGN |
LABEL_ANGLE
LABEL_COLOR
LABEL_FILL_BACKGROUND
LABEL_FILL_COLOR
LABEL_FORMAT
LABEL_POSITION
LABEL_SHOW
LABEL_VALIGN |
LATITUDE_MAX
LATITUDE_MIN
LINESTYLE
LONGITUDE_MAX
LONGITUDE_MIN
THICK
TRANSPARENCY
ZVALUE |
You may also get or set a property after creation, and the request will automatically be passed down to the MapGrid object. Or, you can use the MAPGRID property to retrieve a reference to the MapGrid, and then get or set properties directly on that object. See the MAPGRID function for a description of these properties.
Keywords
Keywords are applied only during the initial creation of the graphic.
BUFFER
Set this keyword to 1 to direct the graphics to an off-screen buffer instead of creating a window.
CURRENT
Set this keyword to create the graphic in the current window with a new set of axes. If no window exists, a new window is created. The WINDOW's SetCurrent method may be used to set the current window.
Or, set this keyword to an existing IDL Graphic reference to make that window be the current window and direct the new graphic to that window.
Tip: The CURRENT keyword is usually used with the LAYOUT keyword or POSITION property to produce a window which has multiple graphics in different locations.
Tip: For the graphic share the same axes as an existing graphic, use the OVERPLOT keyword instead.
DEVICE
Set this keyword if values are specified in device coordinates (pixels) for the MARGIN and POSITION keywords. (Normalized coordinates are the default for these keywords.)
DIMENSIONS
Set this keyword to a two-element vector of the form [width, height] to specify the window dimensions in pixels. If you do not specify a value for DIMENSIONS, IDL by default uses the values of the IDL_GR_WIN_HEIGHT and IDL_GR_WIN_WIDTH preferences for Windows platforms or the IDL_GR_X_HEIGHT and IDL_GR_X_WIDTH preferences for X Windows systems on UNIX.
Tip: The minimum width is set by the toolbar in the window, usually around 400 pixels. To create a smaller graphics window, use the NO_TOOLBAR keyword.
LAYOUT
Set this keyword to a three-element vector [ncol, nrow, index] that arranges graphics in a grid. The first dimension ncol is the number of columns in the grid, nrow is the number of rows, and index is the grid position at which to place the graphic (starting at element 1). This keyword is ignored if either OVERPLOT or POSITION is specified.
LOCATION
Set this keyword to a two-element vector [X offset, Y offset] giving the window's screen offset in pixels.
MARGIN
Set this keyword to the current graphic’s margin values in the layout specified by the LAYOUT property. Use a scalar value to set the same margin on all sides, or use a four-element vector [left, bottom, right, top] to specify different margins on each side.
By default, margin values are expressed in normalized units ranging from 0.0 to 0.5. If the DEVICE keyword is set, the values are given in device units (pixels).
This keyword is ignored if either OVERPLOT or POSITION is specified.
NO_TOOLBAR
By default the graphics window will have a toolbar containing some common tools such as Print and Save. Set this keyword to remove the toolbar. This keyword has no effect if the window is already created.
Tip: When the toolbar exists, the minimum window width is set to the toolbar's width, usually around 400 pixels. To create a smaller graphics window, use the NO_TOOLBAR keyword.
NODATA
Set this keyword to 1 to create the graphic, but without any data attached to it. The axes and title (if present) are also created and displayed. If the OVERPLOT keyword is specified, axis ranges will not change.
Note: You must still provide valid input arguments. The data range of the input arguments are used to automatically set the range of the axes. The [XYZ]RANGE properties may be used to override these default ranges.
OVERPLOT
Set this keyword to 1 (one) to place the graphic on top of the currently-selected graphic within the current window. The two graphics items will then share the same set of axes. If no current window exists, then this keyword is ignored and a new window is created.
If you have a graphic in another window that is not currently selected, you can also set this keyword to that graphic's reference to overplot on top of that graphic.
Tip: For the graphic to have a new set of axes, use the CURRENT keyword instead.
WIDGETS
By default, when running from the IDL Workbench, the graphics window will use the native widgets for your platform. Set this keyword to instead use IDL widgets for the graphics window. This keyword is ignored when running from the IDL command line, since IDL widgets are always used in that case.
Properties
BACKGROUND_COLOR
Set this property to a string or RGB vector indicating the graphic's background color. The default value is [255, 255, 255] (white). Set this property to a scalar value to remove the background color.
Tip: To set the background color of the entire window, retrieve the window object using the WINDOW property, and set the BACKGROUND_COLOR on the window object.
BACKGROUND_TRANSPARENCY
Set this property to an integer between 0 and 100 giving the percent transparency of the background color. The default is 100 (completely transparent).
Note: If the BACKGROUND_COLOR property is changed, and the current background transparency is 100, then the BACKGROUND_TRANSPARENCY will be automatically set to 0 (opaque) so that you can see the new color.
FONT_COLOR
Set this property to a string or RGB vector that specifies the color of the title (if present). The default value is "black".
FONT_NAME
Set this property equal to a string specifying the IDL or system font for the title (if present). The default value is "DejaVuSans".
FONT_SIZE
Set this property equal to an integer specifying the font size for the grid labels and title (if present). The default value is 9 points for the grid labels and 11 points for the title.
FONT_STYLE
Set this property equal to an integer or a string specifying the font style for the title (if present). Allowed values are:
Integer |
String |
Resulting Style |
0 |
"Normal" or "rm"
|
Default (roman) |
1 |
"Bold" or "bf" |
Bold |
2 |
"Italic" or "it"
|
Italic |
3 |
"Bold italic" or "bi"
|
Bold italic |
LIMIT
Set this property to a four-element vector of the form
[Latmin, Lonmin, Latmax, Lonmax]
that specifies the boundaries of the region to be mapped. (Lonmin, Latmin) and (Lonmax, Latmax) are the longitudes and latitudes of two points diagonal from each other on the region's boundary.
Note: If the longitude range in LIMIT is less than or equal to 180 degrees, map clipping is performed in lat/lon coordinates before the transform. If the longitude range is greater than 180 degrees, map clipping is done in Cartesian coordinates after the transform. For non-cylindrical projections, clipping after the transformation to Cartesian coordinates means that some lat/lon points that fall outside the bounds specified by LIMIT may not be clipped. This occurs when the transformed lat/lon points fall inside the cartesian clipping rectangle.
Note: Lonmin should be in the range –180 to +180. Lonmax should be in the range –180 to +540, and must be greater than Lonmin. The total range for the map (Lonmax – Lonmin) must be 360 degrees or less.
Note: For the azimuthal projections (Azimuthal Equidistant, Lambert Azimuthal, Orthographic, Polyconic, and Stereographic), by default the map is clipped so that only one hemisphere is visible. For example, if you have set CENTER_LATITUDE=90 to display the Northern Hemisphere, then the limit will default to [0, -180, 90, 180]. To display regions outside of the default hemisphere, you should set the LIMIT property to your desired limits. For example, to display the Azimuthal Equidistant projection from 30°S to 90°N:
m = Map('Azimuthal Equidistant', CENTER_LATITUDE=90, LIMIT=[-30, -180, 90, 180])
mc = MapContinents(/FILL, TRANSPARENCY=50)
MAPGRID (Get only)
This property retrieves a reference to the existing MAPGRID object.
MAP_PROJECTION
A string giving the name of the current map projection. This is the same as the Projection argument. After creation, use this property to retrieve or set the current map projection.
NAME
A string that specifies the name of the graphic. The name can be used to retrieve the graphic using the brackets array notation. If NAME is not set then a default name is chosen based on the graphic type.
POSITION
Set this property to a four-element vector that determines the position of the graphic within the window. The coordinates [X1, Y1, X2, Y2] define the lower left and upper right corners of the graphic. Coordinates are expressed in normalized units ranging from 0.0 to 1.0. On creation, if the DEVICE keyword is set, the units are given in device units (pixels).
Note: After creation, you can set the POSITION to either a two or four-element vector. If two elements are provided, the center of the graphic will be translated to that position. If four elements are provided, the graphics will be translated and scaled to fit the position.
TITLE
Set this property to a string specifying a title. The title properties may be modified using FONT_COLOR, FONT_NAME, FONT_SIZE, and FONT_STYLE. After creation the TITLE property may be used to retrieve a reference to the title text object, and the TEXTproperties may be used to modify the title object.
You can add Greek letters and mathematical symbols using a TeX-like syntax, enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details.
UVALUE
Set this property to an IDL variable of any data type.
WINDOW (Get Only)
This property retrieves a reference to the WINDOW object which contains the graphic.
WINDOW_TITLE
Set this property to the title of the IDL Graphic window. The title is displayed in the window's title bar.
XRANGE
A two-element vector giving the X data range to plot. The default behavior is to plot the entire data range.
YRANGE
A two-element vector giving the Y data range to plot. The default behavior is to plot the entire data range.
Version History
8.0 |
Introduced |
8.1 |
Added the following properties: MAP_PROJECTION, MAPGRID, UVALUE, WINDOW.
Added the following methods: Delete, MapForward, MapInverse.
|
8.2 |
Added BACKGROUND_COLOR, BACKGROUND_TRANSPARENCY, CLIP (Grid), LABEL_FORMAT (Grid) properties.
|
8.2.2 |
Change POSITION from a keyword to a property. Added Map Projection table.
|
8.6 |
Changed default font name and font size. |
8.6.1 |
Added ellipsoid support to Near Side Perspective projection, added GOES-R map projection. |
See Also
!COLOR, CONTOUR,
IMAGE,
MAPCONTINENTS,
MAPGRID,
MAP_PROJ_INIT
IDL Graphics Functions, Using IDL graphics