MAP_PROJ_FORWARD

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 created by MAP_PROJ_INIT.

Example

The example map_proj_forward_doc.pro creates a latitude and longitude grid with labels for the Goodes Homolosine map projection. This example file is installed in the IDL installation’s /example/doc/plot directory. To view the example code, enter .edit map_proj_forward_doc.pro at the IDL command line. To execute the code, enter map_proj_forward_doc at the IDL command line.

Syntax

Result = MAP_PROJ_FORWARD(Longitude [, Latitude] [, CONNECTIVITY=vector] [, /FILL] [, MAP_STRUCTURE=variable] [, 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.

Note: For most map projections the (x, y) coordinates will be in meters on the Earth's surface. For the GOES-R projection the (x, y) coordinates are in scan-angle radians.

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 m_j is an integer specifying the number of vertices that define the polyline or polygon (the vertex count), and each associated set of i₀...i_m_-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, m_j, equal to zero. (Note that if you set an m equal to zero, you must remove the associated set of i₀...i_m_-1 values as well.) To ignore the remaining entries in the CONNECTIVITY array, set the vertex count, m_j, 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, 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.

Thread Pool Keywords

This routine is written to make use of IDL’s thread pool, which can increase execution speed on systems with multiple CPUs. The values stored in the !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for details.

Note: Threading is only used when individual points are being transformed, and has no effect if either the POLYGONS or POLYLINES keyword is specified.

Version History

5.6	Introduced
6.1	FILL keyword added
6.2	Thread pool keywords added