Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]

MAP_PROJ_FORWARD

Syntax | Return Value | Arguments | Keywords | Example | Version History | See Also

The MAP_PROJ_FORWARD function transforms map coordinates from longitude and latitude to Cartesian (x, y) coordinates, using either the !MAP system variable or a supplied map projection structure.

Syntax

Result = MAP_PROJ_FORWARD(Longitude [, Latitude] [, CONNECTIVITY=vector] [, /FILL] [, MAP_STRUCTURE=value] [, POLYGONS=variable] [, POLYLINES=variable] [,  /RADIANS] )

Return Value

The result is a (2, n) array containing the Cartesian (x, y) coordinates.

Note
If the POLYGONS or POLYLINES keyword is present, the number of points in the result may be different than the number of input points, depending upon whether clipping and splitting occurs.

Arguments

Longitude

An n-element vector containing the longitude values. If the Latitude argument is omitted, Longitude must be a (2, n) array of longitude and latitude pairs.

Latitude

An n-element vector containing latitude values. If this argument is omitted, Longitude must be a (2, n) array of longitude and latitude pairs.

Keywords

CONNECTIVITY

Set this keyword to a vector containing an input connectivity list for polygons or polylines. The CONNECTIVITY keyword allows you to specify multiple polygons or polylines using a single array. The CONNECTIVITY list is a one-dimensional integer array of the form:

where each mj is an integer specifying the number of vertices that define the polyline or polygon (the vertex count), and each associated set of i0...im-1 are indices into the arrays of vertices specified by the Longitude and Latitude arguments.

For example, to draw polylines between the first, third, and sixth longitude and latitude values and the fourth, sixth, ninth, and tenth longitude and latitude values, set the CONNECTIVITY array equal to [3,0,2,5,4,3,5,8,9].

To ignore a set of entries in the CONNECTIVITY array, set the vertex count, mj, equal to zero. (Note that if you set an m equal to zero, you must remove the associated set of i0...im-1 values as well.) To ignore the remaining entries in the CONNECTIVITY array, set the vertex count, mj, equal to -1.

This keyword is ignored if neither POLYGONS nor POLYLINES is present.

FILL

Set this keyword, along with the POLYGONS keyword, to perform a tessellation on the returned polygons after any clipping or splitting has been completed. This keyword is ignored if POLYGONS is not set.

Tip
The use of the FILL keyword avoids having to first pass your data through MAP_PROJ_FORWARD, and then again through the IDLgrTessellator object. Since IDLgrPolygon can only draw convex polygons correctly, you should use the FILL keyword when your input polygon is either complex (that is, if the polygon crosses itself) or concave. Tessellation is also useful if your data contains one polygon within another, such as an island within a lake within a country. In this case the CONNECTIVITY array could be used to pass all three polygons in to MAP_PROJ_FORWARD, and the FILL keyword would automatically perform the correct tessellation.

MAP_STRUCTURE

Set this keyword to a !MAP structure variable containing the projection parameters, as constructed by the MAP_PROJ_INIT. If this keyword is omitted, the !MAP system variable is used.

POLYGONS

Set this keyword to a named variable that will contain a connectivity array of the form described above in the CONNECTIVITY keyword.

If this keyword is present, the arrays specified by the Longitude and Latitude arguments are assumed to be the vertices of a closed polygon. In this case, polygon clipping and splitting is performed in addition to the map transform, and the connectivity array is returned in the specified variable.

If this keyword is not present, the arrays specified by the Longitude and Latitude arguments are assumed to be independent points and no clipping or splitting is performed.

POLYLINES

Set this keyword to a named variable that will contain a connectivity array of the form described above in the CONNECTIVITY keyword.

If this keyword is present, the arrays specified by the Longitude and Latitude arguments are assumed to be the vertices of a polyline. In this case, polyline clipping and splitting is performed in addition to the map transform, and the connectivity array is returned in the specified variable.

If this keyword is not present, the arrays specified by the Longitude and Latitude arguments are assumed to be independent points and no clipping or splitting is performed.

RADIANS

Set this keyword to indicate that the input longitude and latitude coordinates are in radians. By default, coordinates are assumed to be in degrees.

Example

The following example creates a latitude and longitude grid with labels for the Goodes Homolosine map projection. 

; Helper function. Constructs the polyline objects. 
PRO Ex_Map_AddPolyline, label, $ 
  gridLon, gridLat, sMap, oModel, oContainer, oFont, $ 
  LONGITUDE = longitude 
 
longitude = KEYWORD_SET(longitude) 
 
  ; Transform from lat/lon to X/Y cartesian. 
gridUV = MAP_PROJ_FORWARD(gridLon, gridLat, $ 
    MAP=sMap, POLYLINES = gridPoly) 
IF (N_ELEMENTS(gridUV) LT 2) THEN $ 
    RETURN 
 
  ; Construct label object if desired. 
IF (label NE '') THEN BEGIN 
    oLabel = OBJ_NEW('IDLgrText', label, $ 
      ALIGN = longitude ? 0.5 : 1, $ 
      FONT = oFont, VERTICAL_ALIGN=0.5) 
    oContainer->Add, oLabel 
ENDIF 
 
; Create the polyline object. 
oModel->Add, OBJ_NEW('IDlgrPolyline', gridUV, $ 
    LABEL_OBJ = oLabel, $ 
    LABEL_OFFSET = longitude ? 0.35 : 0, $ 
    /USE_LABEL_ORIENTATION, /USE_TEXT_ALIGN, $ 
    POLYLINE = gridPoly) 
 
END 
 
; Main function. Creates a grid over a map projection. 
PRO Ex_Map_Proj_Forward 
 
; Construct !MAP structure containing the projection. 
sMap = MAP_PROJ_INIT('Goodes Homolosine') 
 
; Create a graphics model to hold the visualizations. 
oModel = OBJ_NEW('IDLgrModel') 
oContainer = OBJ_NEW('IDL_Container') 
oFont = OBJ_NEW('IDLgrFont', SIZE = 4) 
oContainer->Add, oFont 
deg = STRING(176b)  ; degrees symbol in Truetype 
 
; Latitude lines. 
gridLon = DINDGEN(361) - 180 
latitude = 15*(INDGEN(11) - 5) 
 
FOR i = 0,(N_ELEMENTS(latitude) - 1) DO BEGIN 
  lat = latitude[i] 
  gridLat = REPLICATE(lat, 361) 
 
  ; Create the latitude label. 
  label = (lat EQ 0) ? 'Equ' : $ 
    STRTRIM(ABS(lat),2) + deg + (['N','S'])[lat LT 0] 
  Ex_Map_Addpolyline, label, gridLon, gridLat, $ 
    sMap, oModel, oContainer, oFont 
ENDFOR 
 
; Longitude lines. 
gridLat = DINDGEN(181) - 90 
 
; Add in some extra lines for the Goode projections. 
longitude = [20*(DINDGEN(18) - 9), $ 
  -179.999d, -20.001d, -100.001d, -40.001d, 80.001d] 
 
FOR i = 0,N_ELEMENTS(longitude) - 1 DO BEGIN 
  lon = longitude[i] 
  gridLon = REPLICATE(lon, 181) 
 
  ; Create the longitude label. 
  label = STRTRIM(ROUND(ABS(lon)),2) + deg 
  IF ((lon mod 180) NE 0) THEN $ 
    label = label + (['E','W'])[lon LT 0] 
  IF (lon NE FIX(lon)) THEN label = '' 
 
  Ex_Map_Addpolyline, label, gridLon, gridLat, $ 
    sMap, oModel, oContainer, oFont, /LONGITUDE 
ENDFOR 
 
; Visualize our map projection. 
XOBJVIEW, oModel, SCALE = 0.9, /BLOCK 
 
; Clean up our objects. 
OBJ_DESTROY, [oModel, oContainer] 
 
END

Version History

Introduced: 5.6

FILL keyword added: 6.1

See Also

MAP_PROJ_INIT, MAP_PROJ_INVERSE

Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]