.\
cgmap__define.pro
Graphics, Map Projections
Provides an easy way to set up a map projection coordinate space using GCTP map projections normally accessed via Map_Proj_Init. Allows an unlimited number of map overlays, and can provide a fresh map structure on demand, eliminating the problem of ephemerial map structures that plaqued Map_Proj_Init until IDL 8.x. This program is basically a wrapper for Map_Proj_Init, with additional features that make it superiour for working with map projections in IDL.
Only GCTP projections are allowed. If you wish to use projections normally set up with Map_Set, use the comparable cgMap_Set command.
Class description for cgMap
Inheritance
All ancestor classes: cgCoord cgContainer IDL_OBJECT IDL_CONTAINER
Properties
Properties in cgCoord
- _EXTRA set
- XLOG get set init
- XRANGE get set init
- POSITION get set init
- YRANGE get set init
- _REF_EXTRA get init
- YLOG get set init
Properties in cgContainer
- UVALUE get set init
- NAME get set init
- COUNT get
- _REF_EXTRA get set
Properties in cgMap
- CONTINENTS set init
- BOX_AXES set init
- CENTER_LONGITUDE get set init
- LATLON_RANGES set init
- DATUM get set init
- UVALUE get set init
- _EXTRA set init
- ADDCMD init
- ONIMAGE get set init
- NAME get set init
- LAND_COLOR init
- FILL init
- OVERLAYS get
- CCOLOR set init
- DRAW get set init
- WINDOW init
- FALSE_EASTING get set init
- XRANGE get set init
- LIMIT get set init
- POSITION get set init
- RADIANS get set init
- BCOLOR get set init
- HIRES get set init
- YRANGE get set init
- ERASE get set init
- BACKGROUND get set init
- SPHERE_RADIUS get set init
- ZONE get set init
- NOBORDER get set init
- _REF_EXTRA get
- TITLE get set init
- GRID set init
- GCOLOR set init
- SEMIMINOR_AXIS get set init
- COLOR get set init
- FALSE_NORTHING get set init
- ASPECT init
- ELLIPSOID get set init
- NOFORWARDFIX get set init
- MAP_PROJECTION get set
- CENTER_LATITUDE get set init
- ISOTROPIC init
- LCOLOR set init
- SEMIMAJOR_AXIS get set init
- LATLONBOX get
- BOUNDARY get
Fields
Fields in cgCoord
- _CG_POSITION [0.00000000D, 0.00000000D, 0.00000000D, 0.00000000D]
- _CG_YRANGE [0.00000000D, 0.00000000D]
- _CG_XRANGE [0.00000000D, 0.00000000D]
- _CG_XLOG 0L
- _CG_YLOG 0L
Fields in cgContainer
- _CG_TRASH obj_new()
- _CG_NAME ''
- _CG_UVALUE ptr_new()
Fields in IDL_OBJECT
- IDL_OBJECT_BOTTOM 0LL
- __OBJ__ obj_new()
- IDL_OBJECT_TOP 0LL
Fields in IDL_CONTAINER
- IDLCONTAINERVERSION 0S
- IDL_CONTAINER_TOP 0LL
- NLIST 0L
- PTAIL ptr_new()
- PHEAD ptr_new()
- IDL_CONTAINER_BOTTOM 0LL
Fields in cgMap
- _CG_CENTER_LONGITUDE 0.00000000D
- _CG_THEPROJECTIONS ptr_new()
- _CG_MULTI_POSITION [0.000000, 0.000000, 0.000000, 0.000000]
- _CG_CENTER_LATITUDE 0.00000000D
- _CG_BACKGROUND ''
- _CG_NOFORWARDFIX 0B
- _CG_NORTHING 0.00000000D
- _CG_ISOTROPIC 0B
- _CG_ASPECT 0.00000000D
- _CG_LIMIT ptr_new()
- _CG_RADIANS 0B
- _CG_EASTING 0.00000000D
- _CG_ERASE 0B
- _CG_THISPROJECTION { CGMAP_PROJECTION, NAME: '', INDEX: 0S, SPHEREONLY: 0S }
- _CG_TITLE ''
- _CG_COLOR ''
- _CG_OVERLAYS obj_new()
- _CG_THISDATUM { CGMAP_DATUM, INDEX: 0S, NAME: '', SEMIMAJOR_AXIS: 0.00000000D, SEMIMINOR_AXIS: 0.00000000D }
- _CG_ZONE 0S
- _CG_THEDATUMS ptr_new()
- _CG_ONIMAGE 0B
- _CG_NOBORDER 0B
- _CG_MAP_PROJECTION_KEYWORDS ptr_new()
Author information
- Author
FANNING SOFTWARE CONSULTING:
David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com
- Copyright
Copyright (c) 2011-2013, Fanning Software Consulting, Inc.
- History
Change History:
Brought over to the Coyote Library from a similar routine in the Catalyst Library. Updated to account for the bug that creates incorrect result in UTM projections when using the WGS84 ellipsoid. The Wallbeck ellipsoid is substituted for the WGS84 ellipsoid in this instance. David W. Fanning, 7 November 2011. Added IS_CYLINDRICAL method to solve a problem with grid labeling and drawing of grid lines. 16 Dec 2011. DWF. Added ERASE method to erase the display. 28 Dec 2011. DWF. Added check for identical range values in FORWARD method. 30 Dec 2011. DWF. I am convinced that the map structure returned by Map_Proj_Init, when there is a LIMIT used in the call contains a uv_box with incorrect latitude values. This is important because other routines (e.g., cgMapGrid) depend on these values. I've created a fix wherein I fixed the uv_box latitude values to correspond to the LIMIT of the map projection. 6 April 2012. DWF. Set the default CENTER_LATITUDE and CENTER_LONGITUDE to 0.0. 9 April 2012. DWF. Added NOFORWARDFIX keyword to allow skipping of the "fix" in the FORWARD method, as sometimes this is not needed or required. 29 June 2012. DWF. Fixed a problem that required having to set the UTM zone in addition to the latitude and longitude in a UTM projection. Now using cgUTMZone to determine the proper zone. 8 Aug 2012. DWF. Added a BOUNDARY keyword to the GetProperty method. 16 Aug 2012. DWF. Modified to allow Hotine Oblique Mercator map projections to work correctly. 7 Sept 2012. DWF. Additional changes to better handle IDL 8.2 map projections. 12 Sept 2012. DWF. Added LATLONBOX keyword to the GetProperty method to allow me to obtain the map boundary in the Google Map preferred notation of [north, south, east, west] in degrees. 30 Oct 2012. I was calculating the default X and Y range incorrectly for non-UTM map projections. I have now gone back to my original method of using the UV_BOX of the map structure to do this. However, there is still a problem with the UV_BOX when the center latitude is not zero. I still attempt to fix this problem in the code (SetMapProjection method). 3 Jan 2012. DWF. I added ASPECT and ISOTROPIC keywords to allow the setting of the aspect ratio of the map. 3 Jan 2012. DWF. Added zone to the information returned with MapInfo method if projection is UTM. 25 April 2013. DWF. The map aspect was disappearing because Total(!P.Multi) can occasionally be LT 0! Fixed. 3 July 2013. DWF. Added Hughes ellipsoid, used at NSIDC, as index 26 or as "Hughes". 11 Sept 2013. DWF. Fixed a bug in the way ellipsoids were selected when using numbers to choose elliposids. All ellipsoids with values over 20 were affected. 18 Sept 2013. DWF. Added FORMAT keyword to LanLonLabels method. 27 November 2013. DWF. Change EASTING and NORTHING keywords to FALSE_EASTING and FALSE_NOTHING to conform to Map_Proj_Init. 29 Nov 2013. DWF. Forgetting to add the false_easting and false_northing values to the structure in INIT method. 29 Nov 2013. DWF. Added Cylindrical Equal Area to list of projections that don't allow CENTER_LATITUDE keyword. 24 Dec 2014. DWF. Typo in code to handle ASPECT ratio was causing aspect ratio of output to be lost. Fixed. 19 Feb 2015. DWF.
Routines
result = cgMap::INIT( [map_projection] [, /ADDCMD] [, ASPECT=float] [, BACKGROUND=string] [, BCOLOR=string] [, /BOX_AXES] [, CCOLOR=string] [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, COLOR=string] [, /CONTINENTS] [, DATUM=string/integer] [, /DRAW] [, ELLIPSOID=string/integer] [, /ERASE] [, FALSE_EASTING=double] [, FALSE_NORTHING=double] [, /FILL] [, GCOLOR=string] [, /GRID] [, /HIRES] [, /ISOTROPIC] [, LAND_COLOR=string] [, /LATLON_RANGES] [, LCOLOR=string] [, LIMIT=FltArr(4)] [, NAME=string] [, /NOBORDER] [, /NOFORWARDFIX] [, /ONIMAGE] [, POSITION=FltArr(4)] [, /RADIANS] [, SEMIMAJOR_AXIS=double] [, SEMIMINOR_AXIS=double] [, SPHERE_RADIUS=double] [, TITLE=string] [, /WINDOW] [, XRANGE=various] [, YRANGE=various] [, UVALUE=any] [, ZONE=integer] [, _EXTRA=_EXTRA])
The initialization method for the cgMap object.
cgMap::AddCmd [, /REPLACE] [, METHOD=string]
Adds the object as a command (the DRAW method is called) in a cgWindow resizeable graphics window.
cgMap::AddOverlay, overLayObject
Adds the an overlay object into the overlay container of the object.
cgMap::Advance [, /DRAW]
Advances the map projection position to the next position of a multiple plot (using !P.MULTI).
cgMap::Draw [, /ERASE] [, /NOGRAPHICS], _EXTRA=_EXTRA
This method sets up the map projection space of the object.
cgMap::Erase [, COLOR=string]
This method erases the graphics window.
result = cgMap::Forward(lons, lats [, mapStruct] [, /NOFORWARDFIX])
This method transforms latitude and longitude values into projected XY Cartesian values.
result = cgMap::Is_Cylindrical()
This method returns a 1 if the map projection is a cylindrical projection and a 0 otherwise.
result = cgMap::GetMapStruct()
This method returns a map structure that is the result of calling Map_Proj_Init.
cgMap::GetProperty, BACKGROUND=BACKGROUND, BCOLOR=BCOLOR [, BOUNDARY=array], CENTER_LATITUDE=CENTER_LATITUDE, CENTER_LONGITUDE=CENTER_LONGITUDE, COLOR=COLOR, DATUM=DATUM, DRAW=DRAW, ELLIPSOID=ELLIPSOID, ERASE=ERASE, FALSE_EASTING=FALSE_EASTING, FALSE_NORTHING=FALSE_NORTHING, HIRES=HIRES [, LATLONBOX=array], LIMIT=LIMIT, MAP_PROJECTION=MAP_PROJECTION, NAME=NAME, NOBORDER=NOBORDER, NOFORWARDFIX=NOFORWARDFIX, ONIMAGE=ONIMAGE [, OVERLAYS=object], POSITION=POSITION, RADIANS=RADIANS, SEMIMAJOR_AXIS=SEMIMAJOR_AXIS, SEMIMINOR_AXIS=SEMIMINOR_AXIS, SPHERE_RADIUS=SPHERE_RADIUS, TITLE=TITLE, XRANGE=XRANGE, YRANGE=YRANGE, UVALUE=UVALUE, ZONE=ZONE, _REF_EXTRA=_REF_EXTRA
This method allows the user to get various properties of the object.
result = cgMap::Inverse(x, y)
This method transforms X and Y projected Cartesian map coordinates into longitude and latitude values.
cgMap::LatLonLabels, FORMAT=FORMAT, LATDELTA=LATDELTA, LATLAB=LATLAB, LATNAMES=LATNAMES, LATS=LATS, LONDELTA=LONDELTA, LONLAB=LONLAB, LONNAMES=LONNAMES, LONS=LONS, SUCCESS=SUCCESS
result = cgMap::MapInfo()
This method returns information about the current map projection in an IDL structure variable.
cgMap::SetProperty [, BACKGROUND=string] [, BCOLOR=string] [, /BOX_AXES] [, CCOLOR=string] [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, COLOR=string] [, /CONTINENTS] [, DATUM=string/integer] [, /DRAW] [, ELLIPSOID=string/integer] [, /ERASE] [, FALSE_EASTING=double] [, FALSE_NORTHING=double] [, GCOLOR=string] [, /GRID] [, /HIRES] [, /LATLON_RANGES] [, LCOLOR=string] [, LIMIT=FltArr(4)], MAP_PROJECTION=MAP_PROJECTION [, NAME=string] [, /NOBORDER] [, /NOFORWARDFIX] [, /ONIMAGE] [, POSITION=FltArr(4)] [, /RADIANS] [, SEMIMAJOR_AXIS=double] [, SEMIMINOR_AXIS=double] [, SPHERE_RADIUS=double] [, TITLE=string] [, XRANGE=various] [, YRANGE=various] [, UVALUE=any] [, ZONE=integer], _EXTRA=_EXTRA
This method allows the user to set various properties of the object.
result = cgMap::SetMapProjection(map_projection, LATLON_RANGES=LATLON_RANGES, POSITION=POSITION, XRANGE=XRANGE, YRANGE=YRANGE, CENTER_LATITUDE=CENTER_LATITUDE, CENTER_LONGITUDE=CENTER_LONGITUDE, DATUM=DATUM, FALSE_EASTING=FALSE_EASTING, FALSE_NORTHING=FALSE_NORTHING, ELLIPSOID=ELLIPSOID, LIMIT=LIMIT, RADIANS=RADIANS, SEMIMAJOR_AXIS=SEMIMAJOR_AXIS, SEMIMINOR_AXIS=SEMIMINOR_AXIS, SPHERE_RADIUS=SPHERE_RADIUS, ZONE=ZONE, _EXTRA=_EXTRA)
cgMap::CLEANUP
This is the clean-up routine for the object.
cgMap__Define [, class]
This is the class definition module.
Routine details
top cgMap::INIT
result = cgMap::INIT( [map_projection] [, /ADDCMD] [, ASPECT=float] [, BACKGROUND=string] [, BCOLOR=string] [, /BOX_AXES] [, CCOLOR=string] [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, COLOR=string] [, /CONTINENTS] [, DATUM=string/integer] [, /DRAW] [, ELLIPSOID=string/integer] [, /ERASE] [, FALSE_EASTING=double] [, FALSE_NORTHING=double] [, /FILL] [, GCOLOR=string] [, /GRID] [, /HIRES] [, /ISOTROPIC] [, LAND_COLOR=string] [, /LATLON_RANGES] [, LCOLOR=string] [, LIMIT=FltArr(4)] [, NAME=string] [, /NOBORDER] [, /NOFORWARDFIX] [, /ONIMAGE] [, POSITION=FltArr(4)] [, /RADIANS] [, SEMIMAJOR_AXIS=double] [, SEMIMINOR_AXIS=double] [, SPHERE_RADIUS=double] [, TITLE=string] [, /WINDOW] [, XRANGE=various] [, YRANGE=various] [, UVALUE=any] [, ZONE=integer] [, _EXTRA=_EXTRA])
The initialization method for the cgMap object.
Parameters
- map_projection in optional type=string/integer default=Equirectangular
The name or index number of the map projection desired. Passed directly to Map_Proj_Init as the map projection value. Only GCTP projections are allowed. If you wish to use projections normally set up with Map_Set, use the comparable cgMap_Set command.
Keywords
- ADDCMD in optional type=boolean default=0
If this keyword is set, the object is added to the resizeable graphics window, cgWindow. The DRAW method of the object is called in cgWindow.
- ASPECT in optional type=float default=none
Set this keyword to a floating point ratio that represents the aspect ratio (ysize/xsize) of the resulting map projection. Note that
Aspect
cannot be used when plotting with !P.MULTI. Consider using cgLayout instead for multiple plots.- BACKGROUND in optional type=string default=white
The name of the background color. Used only if the map object erases the display when it draws its contents.
- BCOLOR optional type=string default=opposite
The name of the color to draw box axes with. Requires BOX_AXES be set.
- BOX_AXES in optional type=boolean default=0
Set this keyword to draw a box-style grid axes around the map. Applies only if creating a mapGrid object.
- CCOLOR in optional type=string default=charcoal
The name of the drawing color for the MapContinents object if this is requested.
- CENTER_LATITUDE in optional type=float default=0.0
The center latitude of the map projection.
- CENTER_LONGITUDE in optional type=float default=0.0
The center longitude of the map projection.
- COLOR in optional type=string default=opposite
The name of the drawing color for the object. Passed along to the mapGrid and MapContinents object if these are requested.
- CONTINENTS in optional type=boolean default=0
Set this keyword if you wish to create an overlay object of continental outlines that will be rendered when the draw method is called.
- DATUM in optional type=string/integer default=Sphere
This keyword is being depreciated in favor of the keyword ELLIPSOID, corresponding to changes to Map_Proj_Init initiated in IDL 7.
- DRAW in optional type=boolean default=0
Set this keyword if you wish to immediately call the DRAW method after the object has been completely initialized.
- ELLIPSOID in optional type=string/integer
Set this to the name or index number of the ellopsoid or datum you wish to use for the map projection. The value is passed directly to Map_Proj_Init. The default is a sphere for those projections that only support a sphere, otherwise a Clark projection is used to conform to Map_Proj_Init defaults. Added the "Hughes" datum, which is used at NSIDC. Use "Hughes" or index number 25.
- ERASE in optional type=boolean default=0
Set this keyword if you wish to have the object erase the current graphics display before drawing its content in the DRAW method. The graphics display will be erased in the background color.
- FALSE_EASTING in optional type=double default=0.0
Set this keyword to the false easting value (in meters) to be added to each x coordinate for the forward transform, or subtracted from each x coordinate for the inverse transform.
- FALSE_NORTHING in optional type=double default=0.0
Set this keyword to the false northing value (in meters) to be added to each y coordinate for the forward transform, or subtracted from each y coordinate for the inverse transform.
- FILL in optional type=boolean default=0
Set this keyword to display filled continents, if the keyword CONTINENTS is set.
- GCOLOR in optional type=string default=gray
The name of the drawing color for the MapGrid object if this is requested.
- GRID in optional type=boolean default=0
Set this keyword if you wish to create an overlay object of map grid lines that will be rendered when the draw method is called.
- HIRES in optional type=boolean default=0
Set this keyword if you wish to use high resolution continental outlines. Passed to the MapContinents object if one is requested.
- ISOTROPIC in optional type=boolean default=0
Set this keyword to set the
Aspect
keyword to a value that correctly represents the same map unit length in both the X and Y directions. In other words, a map unit measured in the X direction is the same physical length as a map unit measured in the Y direction.- LAND_COLOR in optional type=string
The name of the drawing color for filled continents, if the keyword CONTINENTS is set. Passed directly to the cgMapContinents object.
- LATLON_RANGES in optional type=boolean default=0
Normally the XRANGE and YRANGE keywords are set in terms of projected meters. If this keyword is set, then the values of XRANGE and YRANGE are assumed to be in longitude and latitude values, respectively, and will be converted to projected meters prior to being stored in the object.
- LCOLOR in optional type=string
Set this to the name of the label color to use in labeling grid lines. By default, the same as COLOR, or if BOX_AXIS is set, then same as BCOLOR.
- LIMIT in optional type=FltArr(4) default=none
The normal LIMIT keyword to Map_Proj_Init, specifying the limit of the map projection in terms of latitude and longitude. Normally,
Limit
is used when using Map_Proj_Init. Most work is done by specifying the projected XY rectangular coordinate system with the keywords XRANGE and YRANGE.- NAME in optional type=string default=selected by cgContainer.
Use this keyword to name the object. Names are often used to select objects in program code.
- NOBORDER in optional type=boolean default=0
If this keyword is set, the customary border than surrounds the map projection is not drawn.
- NOFORWARDFIX in optional type=boolean default=0
There is, I believe, a bug in MAP_PROJ_FORWARD that renders longitude values incorrectly in projected meter space. This is evidenced by MAP_GRID not producing the correct longitude lines in map coordinate systems set up in projected XY meters. In the FORWARD method I correct for this. But, this correction is not always needed or wanted. This property of the object allows me to turn that correction on or off, as needed. Normally, the fix is provided, unless this keyword is set to 1.
- ONIMAGE in optional type=boolean default=0
If this keyword is set, the position of the map projection in the graphics window is obtained from the last image displayed with cgImage. This makes it extremely easy to display an image and immediately set up a map projection space that will allow you to annotate the image using map locations.
- POSITION in optional type=FltArr(4)
The normalized position of the map projection space in the graphics window. The default is [0.075, 0.075, 0.925, 0.925]
- RADIANS in optional type=boolean default=0
Set this keyword to indicate latitude and longitude values are in radians rather than degrees.
- SEMIMAJOR_AXIS in optional type=double default=varies
The length of the semimajor axis of the ellipsoid in meters. Normally calculated from the ELLIPSOID keyword values.
- SEMIMINOR_AXIS in optional type=double default=varies
The length of the semiminor axis of the ellipsoid in meters. Normally calculated from the ELLIPSOID keyword values.
- SPHERE_RADIUS in optional type=double default=varies
The length of the ellipsoidal sphere in meters. Normally calculated from the ELLIPSOID keyword values.
- TITLE in optional type=string
The title of the map projection display.
- WINDOW in optional type=boolean default=0
If this keyword is set, the object replaces any commands in a current cgWindow or it opens a new cgWindow and adds itself to it.
- XRANGE in optional type=various
Set this keyword to the X axis range desired in the data coordinate system. Normally expressed in XY projected meter space, unless the LATLON_RANGES keyword is set. The default is mapStruct.uv_box[[0,2]].
- YRANGE in optional type=various
Set this keyword to the X axis range desired in the data coordinate system. Normally expressed in XY projected meter space, unless the LATLON_RANGES keyword is set. The default is mapStruct.uv_box[[1,3]].
- UVALUE in optional type=any default=none
A storage space for storing any kind of IDL variable of importance to the user.
- ZONE in optional type=integer default=varies
The zone (normally in UTM projections) of the map projection. If not given and needed, calculated from the CENTER_LATITUDE and CENTER_LONGITUDE keyword values.
- _EXTRA in optional
Other keywords accepted by the MAP_PROJ_INIT command are allowed and are passed directly to the MAP_PROJ_INIT program.
top cgMap::AddCmd
cgMap::AddCmd [, /REPLACE] [, METHOD=string]
Adds the object as a command (the DRAW method is called) in a cgWindow resizeable graphics window. If there is no current cgWindow, one is created.
Keywords
- REPLACE in optional type=boolean default=0
If this keyword is set, object DRAW method replaces any commands in the current graphics window.
- METHOD in optional type=string
The object method to add to the cgWindow.
top cgMap::AddOverlay
cgMap::AddOverlay, overLayObject
Adds the an overlay object into the overlay container of the object. Overlay objects are drawn (by calling their DRAW methods) after the map coordinate space is set up in the DRAW method of the object. They are drawn in the order they appear in the object.
Parameters
- overLayObject required type=object
The object that will draw a graphic overlay in the map projection space created by this map object. Typically, overlay objects contain map grid lines (cgMapGrid object), continental outlines (cgMapContinents object), or other types of graphical overlays. The only requirement of an overlay object is that is have a DRAW method and that it draw into a map projection space. This may be an object array.
top cgMap::Advance
cgMap::Advance [, /DRAW]
Advances the map projection position to the next position of a multiple plot (using !P.MULTI). Does not need to be called directly, as the object will call this method as needed.
Keywords
- DRAW in optional type=boolean default=0
Set this keyword to immediately call the draw method after the position has been advanced.
top cgMap::Draw
cgMap::Draw [, /ERASE] [, /NOGRAPHICS], _EXTRA=_EXTRA
This method sets up the map projection space of the object. Also, if map borders or titles are required, they are drawn here. If the object contains any overlay objects, they are also drawn at this time.
Keywords
- ERASE in optional type=boolean default=0
Set this keyword to erase contents of the map window for one time only in this Draw method. It does NOT set the Erase parameter for the object.
- NOGRAPHICS in optional type=boolean default=0
If this keyword is set, no graphics are drawn, but the map data coordinate system is set up.
- _EXTRA
top cgMap::Erase
cgMap::Erase [, COLOR=string]
This method erases the graphics window.
Keywords
- COLOR in optional type=string default=white
The color used in the erasing of the display.
top cgMap::Forward
result = cgMap::Forward(lons, lats [, mapStruct] [, /NOFORWARDFIX])
This method transforms latitude and longitude values into projected XY Cartesian values. This is known as the forward map transformation.
Return value
The projected XY coordinates are returned in a 2xN array. The first column contains the projected X values and the second column contains the projected Y values.
Parameters
- lons in required
The longitude values to transform. May be a scalar or an array.
- lats in required
The latitude values to transform. May be a scalar or an array.
- mapStruct in optional type=structure
The map structure to use in doing the forward transformation. If not provided, the map structure is obtained from the object itself.
Keywords
- NOFORWARDFIX in optional type=boolean default=0
I may be wrong about the fix I put in when the longitude values are the same. If so, setting this keyword will avoid the fix. The default value is the default for the object.
top cgMap::Is_Cylindrical
result = cgMap::Is_Cylindrical()
This method returns a 1 if the map projection is a cylindrical projection and a 0 otherwise.
top cgMap::GetMapStruct
result = cgMap::GetMapStruct()
This method returns a map structure that is the result of calling Map_Proj_Init. It is important to get a fresh map structure because up until IDL 8, the map structure was ephemeral (http://www.idlcoyote.com/map_tips/ephemeral.php). Every time this function is called, a new map structure is created.
top cgMap::GetProperty
cgMap::GetProperty, BACKGROUND=BACKGROUND, BCOLOR=BCOLOR [, BOUNDARY=array], CENTER_LATITUDE=CENTER_LATITUDE, CENTER_LONGITUDE=CENTER_LONGITUDE, COLOR=COLOR, DATUM=DATUM, DRAW=DRAW, ELLIPSOID=ELLIPSOID, ERASE=ERASE, FALSE_EASTING=FALSE_EASTING, FALSE_NORTHING=FALSE_NORTHING, HIRES=HIRES [, LATLONBOX=array], LIMIT=LIMIT, MAP_PROJECTION=MAP_PROJECTION, NAME=NAME, NOBORDER=NOBORDER, NOFORWARDFIX=NOFORWARDFIX, ONIMAGE=ONIMAGE [, OVERLAYS=object], POSITION=POSITION, RADIANS=RADIANS, SEMIMAJOR_AXIS=SEMIMAJOR_AXIS, SEMIMINOR_AXIS=SEMIMINOR_AXIS, SPHERE_RADIUS=SPHERE_RADIUS, TITLE=TITLE, XRANGE=XRANGE, YRANGE=YRANGE, UVALUE=UVALUE, ZONE=ZONE, _REF_EXTRA=_REF_EXTRA
This method allows the user to get various properties of the object. In general, the same keywords that are used for the INIT method can be used here. Here are a few that are different.
Keywords
- BACKGROUND
- BCOLOR
- BOUNDARY out optional type=array
A four-element array giving the boundaries of the image in the form [x0,y0,x1,y1]. This is a more convenient way of expressing the range of the map space.
- CENTER_LATITUDE
- CENTER_LONGITUDE
- COLOR
- DATUM
- DRAW
- ELLIPSOID
- ERASE
- FALSE_EASTING
- FALSE_NORTHING
- HIRES
- LATLONBOX out optional type=array
A four-element array giving the boundaries of the map projection in the Google Map form of [north, south, east, west]. This is useful when you are creating image overlays to be added to Google Earth.
- LIMIT
- MAP_PROJECTION
- NAME
- NOBORDER
- NOFORWARDFIX
- ONIMAGE
- OVERLAYS out optional type=object
Set this keyword to a named variable that will return an object array containing the overlay objects in the map object.
- POSITION
- RADIANS
- SEMIMAJOR_AXIS
- SEMIMINOR_AXIS
- SPHERE_RADIUS
- TITLE
- XRANGE
- YRANGE
- UVALUE
- ZONE
- _REF_EXTRA
top cgMap::Inverse
This method transforms X and Y projected Cartesian map coordinates into longitude and latitude values. This is known as the inverse map transformation.
Return value
The projected lon/lat coordinates are returned in a 2xN array. The first column contains the longitude values and the second column contains the latitude values.
Parameters
- x in required
The projected X values to transform. May be a scalar or an array.
- y in required
The projected Y values to transform. May be a scalar or an array.
top cgMap::LatLonLabels
cgMap::LatLonLabels, FORMAT=FORMAT, LATDELTA=LATDELTA, LATLAB=LATLAB, LATNAMES=LATNAMES, LATS=LATS, LONDELTA=LONDELTA, LONLAB=LONLAB, LONNAMES=LONNAMES, LONS=LONS, SUCCESS=SUCCESS
Keywords
- FORMAT
- LATDELTA
- LATLAB
- LATNAMES
- LATS
- LONDELTA
- LONLAB
- LONNAMES
- LONS
- SUCCESS
top cgMap::MapInfo
result = cgMap::MapInfo()
This method returns information about the current map projection in an IDL structure variable. Fields of the structure will reflect values that are used in MAP_PROJ_INIT to create a map structure.
top cgMap::SetProperty
cgMap::SetProperty [, BACKGROUND=string] [, BCOLOR=string] [, /BOX_AXES] [, CCOLOR=string] [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, COLOR=string] [, /CONTINENTS] [, DATUM=string/integer] [, /DRAW] [, ELLIPSOID=string/integer] [, /ERASE] [, FALSE_EASTING=double] [, FALSE_NORTHING=double] [, GCOLOR=string] [, /GRID] [, /HIRES] [, /LATLON_RANGES] [, LCOLOR=string] [, LIMIT=FltArr(4)], MAP_PROJECTION=MAP_PROJECTION [, NAME=string] [, /NOBORDER] [, /NOFORWARDFIX] [, /ONIMAGE] [, POSITION=FltArr(4)] [, /RADIANS] [, SEMIMAJOR_AXIS=double] [, SEMIMINOR_AXIS=double] [, SPHERE_RADIUS=double] [, TITLE=string] [, XRANGE=various] [, YRANGE=various] [, UVALUE=any] [, ZONE=integer], _EXTRA=_EXTRA
This method allows the user to set various properties of the object. In general, the same keywords that are used for the INIT method can be used here.
Keywords
- BACKGROUND in optional type=string default=white
The name of the background color. Used only if the map object erases the display when it draws its contents.
- BCOLOR optional type=string default=opposite
The name of the color to draw box axes with. Requires BOX_AXES be set.
- BOX_AXES in optional type=boolean default=0
Set this keyword to draw a box-style grid axes around the map. Applies only if creating a mapGrid object.
- CCOLOR in optional type=string default=charcoal
The name of the drawing color for the MapContinents object if this is requested.
- CENTER_LATITUDE in optional type=float default=varies
The center latitude of the map projection.
- CENTER_LONGITUDE in optional type=float default=varies
The center longitude of the map projection.
- COLOR in optional type=string default=opposite
The name of the drawing color for the object. Passed along to the mapGrid and MapContinents object if these are requested.
- CONTINENTS in optional type=boolean default=0
Set this keyword if you wish to create an overlay object of continental outlines that will be rendered when the draw method is called.
- DATUM in optional type=string/integer default=Sphere
This keyword is being depreciated in favor of the keyword ELLIPSOID, corresponding to changes to Map_Proj_Init initiated in IDL 7.
- DRAW in optional type=boolean default=0
Set this keyword if you wish to immediately call the DRAW method after the object has been completely initialized.
- ELLIPSOID in optional type=string/integer default=Sphere
Set this to the name or index number of the ellopsoid or datum you wish to use for the map projection. The value is passed directly to Map_Proj_Init.
- ERASE in optional type=boolean default=0
Set this keyword if you wish to have the object erase the current graphics display before drawing its content in the DRAW method. The graphics display will be erased in the background color.
- FALSE_EASTING in optional type=double default=0.0
Set this keyword to the false easting value (in meters) to be added to each x coordinate for the forward transform, or subtracted from each x coordinate for the inverse transform.
- FALSE_NORTHING in optional type=double default=0.0
Set this keyword to the false northing value (in meters) to be added to each y coordinate for the forward transform, or subtracted from each y coordinate for the inverse transform.
- GCOLOR in optional type=string default=gray
The name of the drawing color for the MapGrid object if this is requested.
- GRID in optional type=boolean default=0
Set this keyword if you wish to create an overlay object of map grid lines that will be rendered when the draw method is called.
- HIRES in optional type=boolean default=0
Set this keyword if you wish to use high resolution continental outlines. Passed to the MapContinents object if one is requested.
- LATLON_RANGES in optional type=boolean default=0
Normally the XRANGE and YRANGE keywords are set in terms of projected meters. If this keyword is set, then the values of XRANGE and YRANGE are assumed to be in longitude and latitude values, respectively, and will be converted to projected meters prior to being stored in the object.
- LCOLOR in optional type=string
Set this to the name of the label color to use in labeling grid lines. By default, the same as COLOR, or if BOX_AXIS is set, then same as BCOLOR.
- LIMIT in optional type=FltArr(4) default=none
The normal LIMIT keyword to Map_Proj_Init, specifying the limit of the map projection in terms of latitude and longitude. Normally, little used when using Map_Proj_Init. Most work is done by specifying the projected XY rectangular coordinate system with the keywords XRANGE and YRANGE.
- MAP_PROJECTION
The name or index number of a GCTP map projection to use.
- NAME in optional type=string default=selected by cgContainer.
Use this keyword to name the object. Names are often used to select objects in program code.
- NOBORDER in optional type=boolean default=0
If this keyword is set, the customary border than surrounds the map projection is not drawn.
- NOFORWARDFIX in optional type=boolean default=0
There is, I believe, a bug in MAP_PROJ_FORWARD that renders longitude values incorrectly in projected meter space. This is evidenced by MAP_GRID not producing the correct longitude lines in map coordinate systems set up in projected XY meters. In the FORWARD method I correct for this. But, this correction is not always needed or wanted. This property of the object allows me to turn that correction on or off, as needed. Normally, the fix is provided, unless this keyword is set to 1.
- ONIMAGE in optional type=boolean default=0
If this keyword is set, the position of the map projection in the graphics window is obtained from the last image displayed with cgImage. This makes it extremely easy to display an image and immediately set up a map projection space that will allow you to annotate the image using map locations.
- POSITION in optional type=FltArr(4)
The normalized position of the map projection space in the graphics window. The default value is [0.075, 0.075, 0.925, 0.900].
- RADIANS in optional type=boolean default=0
Set this keyword to indicate latitude and longitude values are in radians rather than degrees.
- SEMIMAJOR_AXIS in optional type=double default=varies
The length of the semimajor axis of the ellipsoid in meters. Normally calculated from the ELLIPSOID keyword values.
- SEMIMINOR_AXIS in optional type=double default=varies
The length of the semiminor axis of the ellipsoid in meters. Normally calculated from the ELLIPSOID keyword values.
- SPHERE_RADIUS in optional type=double default=varies
The length of the ellipsoidal sphere in meters. Normally calculated from the ELLIPSOID keyword values.
- TITLE in optional type=string
The title of the map projection display.
- XRANGE in optional type=various
Set this keyword to the X axis range desired in the data coordinate system. Normally expressed in XY projected meter space, unless the LATLON_RANGES keyword is set. The default is mapStruct.uv_box[[0,2]].
- YRANGE in optional type=various
Set this keyword to the X axis range desired in the data coordinate system. Normally expressed in XY projected meter space, unless the LATLON_RANGES keyword is set. The default is mapStruct.uv_box[[1,3]]
- UVALUE in optional type=any default=none
A storage space for storing any kind of IDL variable of importance to the user.
- ZONE in optional type=integer default=varies
The zone (normally in UTM projections) of the map projection. If not given and needed, calculated from the CENTER_LATITUDE and CENTER_LONGITUDE keyword values.
- _EXTRA
top cgMap::SetMapProjectionprivate
result = cgMap::SetMapProjection(map_projection, LATLON_RANGES=LATLON_RANGES, POSITION=POSITION, XRANGE=XRANGE, YRANGE=YRANGE, CENTER_LATITUDE=CENTER_LATITUDE, CENTER_LONGITUDE=CENTER_LONGITUDE, DATUM=DATUM, FALSE_EASTING=FALSE_EASTING, FALSE_NORTHING=FALSE_NORTHING, ELLIPSOID=ELLIPSOID, LIMIT=LIMIT, RADIANS=RADIANS, SEMIMAJOR_AXIS=SEMIMAJOR_AXIS, SEMIMINOR_AXIS=SEMIMINOR_AXIS, SPHERE_RADIUS=SPHERE_RADIUS, ZONE=ZONE, _EXTRA=_EXTRA)
Parameters
- map_projection
Keywords
- LATLON_RANGES
- POSITION
- XRANGE
- YRANGE
- CENTER_LATITUDE
- CENTER_LONGITUDE
- DATUM
- FALSE_EASTING
- FALSE_NORTHING
- ELLIPSOID
- LIMIT
- RADIANS
- SEMIMAJOR_AXIS
- SEMIMINOR_AXIS
- SPHERE_RADIUS
- ZONE
- _EXTRA
top cgMap__Define
cgMap__Define [, class]
This is the class definition module. Structures used to manipulate map projectatum information are also created here.
Parameters
- class out optional type=structure
Occasionally, it is useful to have an object class definition as a structure variable. Using this output keyword will allow that.
File attributes
Modification date: | Fri Mar 27 11:07:39 2015 |
Lines: | 2,073 |
Docformat: | rst rst |