MAPCOORD__DEFINE Name
MAPCOORD__DEFINE
Purpose
The purpose of this object is to set up a map coordinate space for
for other objects. The program assumes you will use MAP_PROJ_INIT
to set up the map structure that is the basis for the map projection
space. Additionally, the program can accommodate up to 20 map overlay
objects. These are Catalyst objects that draw graphics in a map coordinate
data space (examples are MAP_OUTLINE and MAP_GRID in the Catalyst "graphics"
directory). The MAPCOORD object cannot, of course, draw map overlays. But,
the CatImage object is written in such a way that if a MAPCOORD object
is used to set up the data coordinate space, then if overlays are present
in the map object, each map overlay object will have its DRAW method called
in turn, in the order in which they are specified in the map overlay array.
See the keywords SET_MAP_OVERLAY and SET_MO_POSITION for details.
Authors
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
Category
Objects, Coordinates Syntax
theObject = Obj_New("MAPCOORD")
Arguments
map_projection The name or the reference number of a valid CGTP map projection. See
the on-line documentation for MAP_PROJ_INIT for details. Default is 111,
Lambert Azimuthal with spherical datum.
Keywords
CENTER_LATITUDE: The center latitude of the map projection.
CENTER_LONGITUDE: The center longitude of the map projection.
DATUM: The name or index number of the DATUM. "Sphere" by default. See
the on-line documentation for MAP_PROJ_INIT for details.
SPHERE_RADIUS: The radius, in meters, of the sphere used as the DATUM.
SEMIMAJOR_AXIS: The distance, in meters, of the semi-major axis of the reference ellipsoid.
SEMIMINOR_AXIS: The distance, in meters, of the semi-minor axis of the reference ellipsoid.
LIMIT: A vector of limits for the map projection: [latmin, lonmin, latmax, lonmax].
ZONE: The zone of UTM and State Plane projections.
Any additional keywords defined for MAP_PROJ_INIT are allowed. And, in addition to those, the following:
GRID_OBJECT: An overlay object, such as MAP_GRID, for drawing map grid lines. The MAPCOORD
object cannot draw grids, but provides a logical place to store such
an object. One advantage of storing the object here is that cleanup of
the object is possible without the user having to do it themselves.
This keyword is depreciated in favor of MAP_OVERLAY. If it is used,
and the OVERLAY_POSITION keyword is not defined, then OVERLAY_POSITION
is set to 1.
LATLON_RANGES: If this keyword is set, the XRANGE and YRANGE keywords are assumed to
be in units of longitude and latitude, respectively. The map structure returned
from Map_Proj_Init will be used to convert these values to the appropriate UV
coordinates for internal storage.
OUTLINE_OBJECT: An overlay object, such as MAP_OUTLINE, for drawing map outlines. The MAPCOORD
object cannot draw outlines, but provides a logical place to store such
an object. One advantage of storing the object here is that cleanup of
the object is possible without the user having to do it themselves.
This keyword is depreciated in favor of MAP_OVERLAY. If it is used,
and the OVERLAY_POSITION keyword is not defined, then OVERLAY_POSITION
is set to 0.
PARENT: An object reference of the parent object. If provided, the MAPCOORD object
will add itself to the parent with the COORDS_OBJECT keyword to SETPROPERTY.
The parent should be a subclassed CATDATAATOM object.
POSITION: A four-element array representing the position of the plot in the window.
Use normalized coordinates (0 to 1) in this order: [x0, y0, x1, y1]. The
default is [0,0,1,1].
MAP_OVERLAY: A 20-element object array of overlay objects. An overlay object
is an object that draws graphics in a map coordinate data space.
Note: Overlay objects must be written with a DRAW method, and they must
have a MAP_OBJECT keyword in a SetProperty method. When they are added
to the MAPCOORD object, the MAPCOORD object will be made their parent
(so they are not accidentally destroyed) and the SetProperty method will
be called with the MAP_STRUCTURE keyword set equal to the MAPCOORD map structure.
OVERLAY_POSITION: A scalar or vector with the same number of elements as MAP_OVERLAY.
This keyword is used to tell IDL where to store the object in the overlay
object array. It should be a number in the range of 0 to 19. If undefined,
the overlay object array is searched for invalid objects, and the overlay
object is stored at the lowest index containing an invalid object.
XRANGE: A two-element array representing the X range of the map projection in a 2D
Cartesian (x,y) coordinate system. These are sometimes called UV coordinates.
If undefined, the longitude range of -180 to 180 is used with the map structure
to create the XRANGE array.
YRANGE: A two-element array representing the Y range of the map projection in a 2D
Cartesian (x,y) coordinate system. These are sometimes called UV coordinates.
If undefined, the latitude range of -90 to 90 is used with the map structure
to create the YRANGE array.
_EXTRA: Any keywords appropriate for superclass INIT methods.
Superclasses
CATCOORD
CATATOM
CATCONTAINER IDLITCOMPONENT
IDL_CONTAINER
Class Structure
class = { MAPCOORD, $
overlays: ObjArr(20), $ ; A storage location for map overlays.
map_projection_keywords: Ptr_New(), $ ; A storage location for MAP_PROJ_INIT keywords.
center_latitude: 0.0D, $ ; The latitude at the center of the map projection.
center_longitude:0.0D, $ ; The lontigude at the center of the map projection.
limit: Ptr_New(), $ ; The limit of the map projection.
zone: 0, $ ; The UTM zone of the map projection.
theDatums: Ptr_New(), $ ; Information about available map datums.
thisDatum: datumStruct, $ ; The particular datum structure for this map projection.
theProjections: Ptr_New(), $ ; Information about available map projections.
thisProjection: mapStruct, $ ; The particular map projection structure for this map projection.
INHERITS CATCOORD $ ; The superclass object.
}
Messages
None.
Modification History
Written by: David W. Fanning, 28 December 2008.
Modified the way the map overlays were handled to be more flexible. 9 January 2009. DWF.
Reworked the program to make it more flexible with a wide variety of GTCP map projections. 2 June 2009.
Fixed some typos in the word "position". 10 June 2009. DWF.
Had to make some modifications to accommodate UTM and State Plane projections. 28 August 2009. DWF.
Removed the POSTITION, XRANGE, and YRANGE keywords from the SetProjection method, where they
didn't really belong. 22 November 2009. DWF.
Removed more vestiges of the MAP_STRUCTURE keyword in INIT method. 14 December 2009. DWF.
Added MAP_PROJECTION keyword to GetProperty and SetProperty methods. 16 December 2009. DWF
Added MAP_PROJ_KEYWORDS keyword to GetProperty and SetProperty methods. 22 December 2009. DWF.
If LIMIT is changed in the SetProperty method AND XRANGE and YRANGE keywords are not used, then
the xrange and yrange are updated to reflect the new limits. 28 Dec 2009. DWF.
The map projection was not being set correctly if the map projection was passed as
string value. 9 Feb 2010. DWF.
Setting the SPHERE_RADIUS keyword on some methods accessed a non-existent field "datum'
instead of the field "thisDatum". Fixed. 9 Feb 2010. DWF.
Mis-spelled SEMIMINOR_AXES keyword in the GetProperty method. Fixed. 10 March 2010. DWF.
Added ADD_GRID, ADD_OUTLINE, and DRAW_OVERLAYS keywords. 12 April 2010. DWF.
Modified the way map overlays are added with MAP_OVERLAY keyword to INIT and SetProperty
methods. 15 June 2010. DWF.
Added ZONE keyword to the GetProperty method. 22 June 2010. DWF.
Switch UTM datum from WGS84 to WALBECK to avoid UTM projection bug in all versions
of IDL prior to IDL 8.2, when it is suppose to be fixed. For more information,
see this article: http://www.idlcoyote.com/map_tips/utmwrong.php. 31 Oct 2011. DWF.