The MAP function displays map data in a graphics window.

Example


The following lines create the map shown at the top of this topic.

; Set up map projection, draw a grid
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")
 
; Change some grid properties.
grid = map.MAPGRID
grid.LINESTYLE = "dotted"
grid.LABEL_POSITION = 0
grid.FONT_SIZE=14
 
; Insert some shapes.
m1 = MAPCONTINENTS(/USA, $
  FILL_COLOR="light green", COMBINE=0)
m2 = MAPCONTINENTS(/CANADA, $
  FILL_COLOR="pale goldenrod")
 
; Retrieve a shape and change its properties.
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