MAP_GRID__DEFINE Name
MAP_GRID__DEFINE
Purpose
This object is a wrapper for the MAP_GRID routine in IDL. It provides a simple
way to allow map grids on images which use a MAPCOORD object to set up the map
projection space. A map coordinate space must be in effect at the time the
Draw method of this object is used.
Author
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
Category
Graphics Calling Sequence
mapCoord = Obj_New('MapCoord', 111, CENTER_LON=0, CENTER_LAT=90)
gridObject = Obj_New('Map_Grid', MAP_OBJECT=mapCoord)
gridObject -> Draw
Obj_Destroy, mapCoord, gridObject
Auguments
parent: The parent object. Optional.
mapCoordObj: A map coordinate object which can return a map structure for converting coordinates
to/from XY coordinates to lon/lat coordinates. Typically, a MAPCOORD object. An
alternative way of specifying a map coordinate object is to use the MAP_OBJECT
keyword. But don't do both. Note, this object is *not* destroyed when the MAP_GRID
object is destroyed. You are responsible for destroying the map coordinate object.
A map coordinate object is REQUIRED. So, if you don't specify a parent, use the
MAP_OBJECT keyword to pass this object into the program.
Keywords
All of the following INIT keywords can be set and obtained using the SETPROPERTY and GETPROPERTY methods.
AUTODRAWGRID: If this keyword is set, the grid latitude and longitude values
are automatically calculated from the Map_Object ranges and drawn
appropriately. Most keywords are ignored when auto drawing the grid.
BOX_AXES: Set this keyword to draw a box-style axes around the map.
CHARSIZE: Set this keyword to the size of characters used for the labels. Default is 1.0.
CLIP_TEXT: Set this keyword to a zero value to turn off clipping of text labels.
By default, text labels are clipped. This keyword is ignored if the
BOX_AXES keyword is set.
COLOR: The name of the color to draw the grid lines in. Default: "charcoal".
FILL_HORIZON: Set this keyword to fill the current map horizon.
FIXED_MAP_GRID: The MAP_GRID command supplied with IDL does not always draw the grids
correctly. This can sometimes be fixed by using a modified version of
MAP_GRID, named FIXED_MAP_GRID. Unfortunately, the FIXED_MAP_GRID command
caused other problem with other applications. Thus, if you are having
map grid problems, this is something to try. The FIXED_MAP_GRID program
is in the Coyote Library.
FORMAT: Set this keyword to a particular string format for formatting
the grid labels.
HORIZON: Set this keyword to draw the current map horizon.
INCREMENT: Set this keyword to the spacing between the graticle points.
LABEL: Set this keyword to an integer, n, that labels every n parallels and meridians.
For example, LABEL=3 will label every 3rd line. Default is 1.
LATALIGN: This keyword controls the alignment of the text baseline for latitude
labels. A value of 0.0 left justifies the label, 1.0 right justifies
it, and 0.5 centers it. This keyword is ignored if the BOX_AXES keyword is set.
LATDEL: Set this keyword equal to the spacing (in degrees) between parallels of
latitude in the grid. If this keyword is not set, a default value of 5 is used.
LATLAB: The longitude at which to place latitude labels. The default is the center
longitude on the map. This keyword is ignored if the BOX_AXES keyword is set.
LATNAMES: Set this keyword equal to an array specifying the names to be used for the
latitude labels. By default, this array is automatically generated in units
of degrees. The LATNAMES array can be either type string or any single numeric
type, but should not be of mixed type.When LATNAMES is specified, the LATS
keyword must also be specified.
LATS: Set this keyword equal to a one or more element vector of latitudes for which
lines will be drawn (and optionally labeled). If LATS is omitted, appropriate
latitudes will be generated based on the value of the (optional) LATDEL keyword.
If LATS is set to a single value, that latitude and a series of automatically
generated latitudes will be drawn (and optionally labeled).
LINESTYLE: Set this keyword to the type of linestyle desired. See Graphics Keywords in
the on-line help for additional information.
LONALIGN: This keyword controls the alignment of the text baseline for longitude
labels. A value of 0.0 left justifies the label, 1.0 right justifies
it, and 0.5 centers it. This keyword is ignored if the BOX_AXES keyword is set.
LONDEL: Set this keyword equal to the spacing (in degrees) between parallels of
longitude in the grid. If this keyword is not set, a default value of 10 is used.
LONTLAB: The latitude at which to place longitude labels. The default is the center
latitude on the map. This keyword is ignored if the BOX_AXES keyword is set.
LONNAMES: Set this keyword equal to an array specifying the names to be used for the
longitude labels. By default, this array is automatically generated in units
of degrees. The LONNAMES array can be either type string or any single numeric
type, but should not be of mixed type.When LONNAMES is specified, the LONS
keyword must also be specified.
LONS: Set this keyword equal to a one or more element vector of longitudes for which
lines will be drawn (and optionally labeled). If LONS is omitted, appropriate
longitudes will be generated based on the value of the (optional) LONDEL keyword.
If LONS is set to a single value, that longitudes and a series of automatically
generated longitudes will be drawn (and optionally labeled).
MAP_OBJECT: A MAPCOORD object or equivalent which had the ability to provide a map
structure with a GetMapStructure method. Don't use this keyword if you have
passed a map coordinate object as a positional parameter. This keyword should
be used ONLY if you are not specifying a parent parameter.
Dependencies
The following programs (at least) are required from the Coyote Library:
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/cgColor.pro
Modification History
Written by David W. Fanning, 3 January 2009.
Added MAP_OBJECT keyword and depreciated MAP_STRUCTURE keyword. 30 May 2009. DWF.
Fixed a problem in setting MAP_OBJECT in SetProperty method. 12 June 2009. DWF.
Circular parent references when passed a MAP_OBJECT was fixed, preventing memory
leakage. 30 August 2009. DWF.
Removed the MAP_STRUCTURE keyword, which caused MASSIVE problems and added a mapCoordObj
parameter. 9 November 2009. DWF.
Changed the default LATDEL keyword to 5 and the LONDEL keyword to 10. 13 December 2009. DWF.
Changed GetProperty keywords LATS and LONS to return data, not pointers to data. 16 December 2009. DWF.
I had to incorporate a "fixed" version of the IDL-supplied routine MAP_GRID to work
around a bug with MAP_PROJ_FORWARD (IDL version 7.1.2) in which some grid points are
simply dropped. The fixed version allows me to draw accurate grid lines. 16 December 2009. DWF.
Removed the "fixed" version of the IDL-supplied routine MAP_GRID from this code and
made it a separate file named FIXED_MAP_GRID. Unfortunately, the "fixed" program
was causing me other problems some map gridding applications. This will now allow
the user to choose whether to use the "fixed" (and I really mean that to be in quotes!)
or non-fixed version of the software, depending upon how it works for you. 20 Feb 2010. DWF.
Added AUTODRAWGRID keyword. 11 March 2010. DWF.
Changed default CHARSIZE to 0.75 for Windows machines. 11 March 2010. DWF.
Changed calls to IDL's MAP_GRID routine to my MODIFIED_MAP_GRID routine, which
has been modified to fix a problem in which hardware fonts are not clipped
to the plot region. 25 March 2010. DWF.
I've rearranged the code that does the AUTODRAWGRID mode, and I've tweaked the algorithms
to respond to several weird cases I've run into lately. Now the AUTODRAWGRID mode sets
the LATS, LONS, LATNAMES, LONNAMES, LATLABEL and LONLABEL properties of the object.
All drawing is done in the DRAW method. 21 June 2010. DWF.
More tweaking of the AUTODRAWGRID algorithm. 5 July 2010. DWF.
Added a FORMAT keyword to format the grid labels, which required modifications
to Catalyst utility routines Fixed_Map_Grid and Modfied_Map_Grid. 5 July 2010. DWF.