Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015

single page | use frames     summary     class     fields     routine details     file attributes

.\

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

Properties in cgContainer

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

Fields in cgContainer

Fields in IDL_OBJECT

Fields in IDL_CONTAINER

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

result = cgMap::Inverse(x, y)

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::CLEANUP

cgMap::CLEANUP

This is the clean-up routine for the object.

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