MAP_IMAGE

The MAP_IMAGE function warps an image (or other dataset) to a Direct Graphics map projection. This function provides an easy method for displaying geographical data as an image on a map. The MAP_SET or MAP_PROJ_INIT procedures should be called prior to calling MAP_IMAGE.

MAP_IMAGE works in image (graphic) space. For each destination pixel (when COMPRESS is set to one) MAP_IMAGE calculates the latitude and longitude by applying the inverse map projection. This latitude and longitude are then used to index and interpolate the Image argument, obtaining an interpolated value for the destination pixel. The time required by MAP_IMAGE depends mainly on the number of pixels in the destination and the setting of the COMPRESS parameter.

Note: MAP_IMAGE is more efficient than MAP_PATCH when the input data set is large compared to the destination area. If the converse is true, MAP_PATCH is more efficient.

Examples

The following lines of code set up an orthographic map projection and warp a simple image to it.

; Create a simple image to be warped:
image = BYTSCL(SIN(DIST(400)/10))

; Display the image so we can see what it looks like before
; warping:
TV, image
latmin = -65
latmax = 65

; Left edge is 160 East:
lonmin = 160

; Right edge is 70 West = +360:
lonmax = -70 + 360
MAP_SET, 0, -140, /ORTHOGRAPHIC, /ISOTROPIC, $
   LIMIT=[latmin, lonmin, latmax, lonmax]
result = MAP_IMAGE(image,Startx,Starty, COMPRESS=1, $
   LATMIN=latmin, LONMIN=lonmin, $
   LATMAX=latmax, LONMAX=lonmax)

; Display the warped image on the map at the proper position:
TV, result, Startx, Starty

; Draw gridlines over the map and image:
MAP_GRID, latdel=10, londel=10, /LABEL, /HORIZON

; Draw continent outlines:
MAP_CONTINENTS, /coasts

Syntax

Result = MAP_IMAGE( Image [, Startx, Starty [, Xsize, Ysize]] [, LATMIN=degrees{-90 to 90}] [, LATMAX=degrees{-90 to 90}]
[, LONMIN=degrees{-180 to 180}] [, LONMAX=degrees{-180 to 180}] [, /BILINEAR] [, COMPRESS=value] [, SCALE=value] [, MAP_STRUCTURE=structure] [, MASK=variable]
[, MAX_VALUE=value] [, MIN_VALUE=value] [, MISSING=value] )

Return Value

Returns the image or dataset warped to the current map projection.

Arguments

Image

A two-dimensional array containing the image to be overlaid on the map.

Startx

A named variable that, upon return, contains the X coordinate position where the left edge of the image should be placed on the screen.

Starty

A named variable that, upon return, contains the Y coordinate position where the left edge of the image should be placed on the screen.

Xsize

A named variable that, upon return, contains the width of the image expressed in graphic coordinate units. If the current graphics device uses scalable pixels (PostScript, for example), the values of Xsize and Ysize should be passed to the TV procedure.

Ysize

A named variable that, upon return, contains the height of the image expressed in graphic coordinate units. If the current graphics device uses scalable pixels (PostScript, for example), the values of Xsize and Ysize should be passed to the TV procedure.

Keywords

LATMIN

The latitude corresponding to the first row of Image. The default is -90 degrees. Note also that -90°≤ LATMIN < LATMAX ≤ 90°.

LATMAX

The latitude corresponding to the last row of Image. The default value is 90 degrees. Note also that -90°≤ LATMIN < LATMAX ≤ 90°.

LONMIN

The longitude corresponding to the first (leftmost) column of the Image argument. Select LONMIN so that -180°≤ LONMIN ≤ 180°. The default value is -180.

LONMAX

The longitude corresponding to the last (rightmost) column of the Image argument. Select LONMAX so that it is larger than LONMIN. If the longitude of the last column is equal to (LONMIN - (360. /Nx)) MODULO 360, it is assumed that the image covers all longitudes (Nx being the total number of columns in the Image argument).

BILINEAR

Set this flag to use bilinear interpolation to soften edges in the returned image, otherwise, nearest neighbor sampling is used.

COMPRESS

This keyword, the interpolation compression flag, controls the accuracy of the results from MAP_IMAGE. The default is 4 for output devices with fixed pixel sizes. The inverse projection transformation is applied to each ith row and column. Setting this keyword to a higher number saves time while lower numbers produce more accurate results. Setting this keyword to 1 solves the inverse map transformation for every pixel of the output image.

SCALE

Set this keyword to the pixel/graphics scale factor for devices with scalable pixels (e.g., PostScript). The default is 0.02 pixels/graphic coordinate. This setting yields an approximate output image size of 350 x 250. Make this number larger for more resolution (and larger PostScript files and images), or smaller for faster, smaller, and less accurate images.

MAP_STRUCTURE

Set this keyword to a !MAP structure as returned from MAP_PROJ_INIT, to be used instead of the default !MAP projection. This keyword is useful to display the image in a UV (Cartesian) coordinate system instead of the !MAP coordinate system.

MASK

Set this keyword equal to a named variable that will contain a byte array of the same dimensions as the Result, containing a mask of the good values. Values in the Result that were set to MISSING (that is, values were either off the map or outside the range specified by the MIN_VALUE and MAX_VALUE keywords) will have a mask value of zero, while all other mask values will be one.

Tip: The MASK array allows you to distinguish values in the Result that were explicitly set to MISSING versus those that happen to have the same value. The array may also be useful in defining an alpha (transparency) channel for an object graphics image.

MAX_VALUE

Data points with values equal to or greater than this value will be treated as missing data, and will be set to the value specified by the MISSING keyword.

MIN_VALUE

Data points with values equal to or less than this value will be treated as missing data, and will be set to the value specified by the MISSING keyword.

MISSING

The pixel value to set areas outside the valid map coordinates. If this keyword is omitted, areas outside the map are set to 255 (white) if the current graphics device is PostScript, otherwise they are set to 0.

Version History

Pre 4.0	Introduced
6.1	Added MAP_STRUCTURE keyword