Coyote Graphics Routines

Date: Tue Jan 21 08:55:07 2014

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

.\

cgmap_grid.pro

Graphics, Map Projections


This program provides a significantly modified MAP_GRID command that can be used with other Coyote Graphics routines.

Description of known MAP_GRID problems:

http://www.idlcoyote.com/map_tips/noclip.html http://www.idlcoyote.com/map_tips/missinggrid.html http://www.idlcoyote.com/map_tips/extralines.php

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:

Written by David W. Fanning, 7 November 2011. Significant modification of the MAP_GRID command in IDL to fix known problems, especially when used in conjunction with map projection spaces set up with MAP_PROJ_INIT. David W. Fanning, 7 November 2011. Added an ERASE=0 to the /NOGRAPHICS keyword on the Draw method call to cgMap. 27 Dec 2011. Changed the default line thickness to !P.Thick to better support PostScript files. 28 Dec 2011. DWF. Fixed a problem with grid labeling when values were passed with LATS or LONS keyword. 6 April 2012. DWF. Modified slightly to allow a three-element byte array to be used as the COLOR. 18 April 2012. DWF. If a Map object is available, I make sure to call DRAW method before drawing graphics. 12 Sept 2012. DWF. Added cgGRID keyword to allow the cgMap object to create latitude and longitude grid in its LatLonLabels method. Previously used by default, but it doesn't work well with global map projections. It works best with small map areas in UTM projection space. 3 Jan 2013. DWF. Removed some old code that was used to correct latitude and longitude values. No longer needed, I hope, with the new cgGRID keyword. 3 Jan 2013. Corrected bug in variable spelling that affect LONDELTA and LATDELTA keywords. 6 Jan 2013. DWF. Lost a piece of code that allows longitude box axes. Added back in. 23 Jan 2013. DWF. T3D keyword was not being applied. Fixed. 11 February 2013. DWF. Added NOCLIP keyword. 15 February 2013. DWF. Sometimes a longitude line is draw incorrectly due to the fact that the longitude vector does not have a point in the XRANGE of the projection. A fix to that problem has failed to work in all circumstances, so I have done more work on that algorithm to see if I can solve the problem is a better way. Now usine Value_Locate to test for point. 19 February 2013. DWF. Now implementing label formatting when using CGGRID keyword. 27 November 2013. DWF.

Routines

result = cgMap_Grid_Incr(span)

Find the grid increment find defining the latitude and longitude delta values, if they are not currently defined.

result = cgMap_Grid_Solve(c0, c1, icoord, gwant [, MAP_STRUCTURE=structure])

Find the point on the line between points c0 and c1, expressed in DEVICE coordinates, where the longitude (Icoord = 0) or latitude (Icoord = 1) is equal to Gwant.

result = cgMap_Grid_Check_Range(xy [, FUZZY=float] [, /GCTP])

This routine fixes a bug in MAP_GRID that causes map labels to be written outside the map boundary when using hardware or true-type fonts.

cgMap_Grid [, /ADDCMD] [, BCOLOR=string] [, BLABEL=float] [, BTHICK=float] [, /BOX_AXES] [, /CGGRID] [, CHARSIZE=float] [, /CLIP_TEXT] [, COLOR=string] [, /FILL_HORIZON] [, FORMAT=string] [, FUZZY=float] [, GLINESTYLE=GLINESTYLE] [, GLINETHICK=GLINETHICK] [, /HORIZON] [, INCREMENT=integer] [, LABEL=integer] [, LATALIGN=float] [, LATDELTA=float] [, LATLABEL=float] [, LATNAMES=string] [, LATS=float] [, LCOLOR=string] [, LINESTYLE=integer] [, LONALIGN=float] [, LONDELTA=float] [, LONLABEL=float] [, LONNAMES=string] [, LONS=float] [, MAP_STRUCTURE=MAP_STRUCTURE] [, /NOCLIP] [, /NO_GRID] [, ORIENTATION=float] [, /T3D] [, THICK=integer] [, ZVALUE=float]

Provides a MAP_GRID command that can be used in conjunction with other Coyote Graphics programs and in resizeable graphics windows.

Routine details

top cgMap_Grid_Incr

result = cgMap_Grid_Incr(span)

Find the grid increment find defining the latitude and longitude delta values, if they are not currently defined.

Parameters

span in required type=float

The data range.

top cgMap_Grid_Solve

result = cgMap_Grid_Solve(c0, c1, icoord, gwant [, MAP_STRUCTURE=structure])

Find the point on the line between points c0 and c1, expressed in DEVICE coordinates, where the longitude (Icoord = 0) or latitude (Icoord = 1) is equal to Gwant. If the segment between c0 and c1 doesn't intersect the given meridan or parallel, or either endpoint is not mappable, return NaN. Otherwise, return the device coordinate, X if Icoord = 0, or Y if Icoord = 1, of the intersection.

Parameters

c0 in required type=integer

Input coordinate?

c1 in required type=integer

Input coordinate?

icoord in required type=integer

Index of input coordinate?

gwant in required type=integer

Global wrapping?

Keywords

MAP_STRUCTURE in optional type=structure

The map structure to covert XY projected meters to lat/lon space.

top cgMap_Grid_Check_Range

result = cgMap_Grid_Check_Range(xy [, FUZZY=float] [, /GCTP])

This routine fixes a bug in MAP_GRID that causes map labels to be written outside the map boundary when using hardware or true-type fonts. It checks to be sure the label is inside the map boundary before it is written. Users can control how "exact" the boundary is when using GCTP map projections by setting the FUZZY keyword to a multiplication factor that is multiplied times the calculated data range of the map projection.

If a point is determined to be outside the map boundary, a single data value is returned by the function. This is a signal that this data point should not be drawn.

Parameters

xy in required type=float

The input label point. Normally, a two element array.

Keywords

FUZZY in optional type=float default=0.0

This keyword applies only if the GCTP keyword is set. Set the keyword to a value that is a percentage of the current data range. This percentage of the range is added to or subtracted from the values used to determine if the label is "inside" the boundary. It allows you to be a little less exact when selecting inside points. There are occasional aesthetic reasons for allowing fuzzy boundaries. A reasonable value for fuzziness might be 0.0125.

GCTP in optional type=boolean default=0

Set this keyword to calculate boundaries in terms of the the current calculated data range variables !X.CRange and !Y.CRange. Otherwise, the boundaries are taken from !Map.LL_BOX.

top cgMap_Grid

cgMap_Grid [, /ADDCMD] [, BCOLOR=string] [, BLABEL=float] [, BTHICK=float] [, /BOX_AXES] [, /CGGRID] [, CHARSIZE=float] [, /CLIP_TEXT] [, COLOR=string] [, /FILL_HORIZON] [, FORMAT=string] [, FUZZY=float] [, GLINESTYLE=GLINESTYLE] [, GLINETHICK=GLINETHICK] [, /HORIZON] [, INCREMENT=integer] [, LABEL=integer] [, LATALIGN=float] [, LATDELTA=float] [, LATLABEL=float] [, LATNAMES=string] [, LATS=float] [, LCOLOR=string] [, LINESTYLE=integer] [, LONALIGN=float] [, LONDELTA=float] [, LONLABEL=float] [, LONNAMES=string] [, LONS=float] [, MAP_STRUCTURE=MAP_STRUCTURE] [, /NOCLIP] [, /NO_GRID] [, ORIENTATION=float] [, /T3D] [, THICK=integer] [, ZVALUE=float]

Provides a MAP_GRID command that can be used in conjunction with other Coyote Graphics programs and in resizeable graphics windows. Any keyword appropriate for the MAP_GRID command in IDL can be used.

Keywords

ADDCMD in optional type=boolean default=0

If this keyword is set, the object is added to the resizeable graphics window, cgWindow. Note that a map projection command must be added to the window before this command is added to be effective.

BCOLOR in optional type=string default=opposite

The name of the color to draw box axes with.

BLABEL in optional type=float default=0

Set this keyword to 0 to label all four of the box axes. Set this keyword to 1 to label the left and bottom box axes only. Set this keyword to 2 to label the top and right box axes only.

BTHICK in optional type=float

The thickness of the box axes in device units.

BOX_AXES in optional type=boolean default=0

Set this keyword to draw box axes on the map projection.

CGGRID in optional type=boolean default=0

Set this keyword to allow the latitude and longitude values to be set by the LatLon_Labels method in the cgMap object. Previously this was used by default, but it caused a lot of problems with global or near global map projections. This really should be used ONLY if you are mapping a very small region of the Earth, and maybe if you are using a UTM map projection. Othersize, it is probably not needed, so I have made it an optional choice.

CHARSIZE in optional type=float

The character size for the labels. Default is cgDefCharSize()*0.75.

CLIP_TEXT in optional type=boolean default=1

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 in optional type=string default=opposite

The name of the drawing color for the program.

FILL_HORIZON in optional type=boolean default=0
FORMAT in optional type=string

Set this keyword to a format for the grid labels.

FUZZY in optional type=float default=0.0

This keyword applies only if the MAP_STRUCTURE keyword is used. Set the keyword to a value that is a percentage of the current data range. This percentage of the range is added to or subtracted from the values used to determine if the label is "inside" the boundary. It allows you to be a little less exact when selecting inside points. There are occasional aesthetic reasons for allowing fuzzy boundaries. A reasonable value for fuzziness might be 0.0125.

GLINESTYLE in optional

Not used. Use Linestyle instead.

GLINETHICK in optional

Not used. Use Thick instead.

HORIZON in optional type=boolean default=0

Set this keyword to draw the current map horizon.

INCREMENT in optional type=integer default=4

Determines the smoothness of graticle lines by setting the spacing between them. A low number is a smooth number.

LABEL in optional type=integer default=0

An number that tells how to label the grid line. A 0 means no grid lines are labelled. A 1 means all grid lines are labelled. A 2 means label every 2nd grid line is labelled. A 3 means every 3rd grid line is labelled, and so on.

LATALIGN in optional type=float default=0.0

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.

LATDELTA in optional type=float

Set this keyword to the spacing in degrees between parallels of latitude in the grid. If this keyword is not set, a suitable value is determined from the current map projection.

LATLABEL in optional type=float

The longitude at which to place latitude labels. The default is the center longitude on the map if using Map_Set, and a longitude line on the left of the plot if using Map_Proj_Init. This keyword is ignored if the Box_Axes keyword is set.

LATNAMES in optional type=string

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. The number of elements in the two arrays need not be equal. If there are more elements in the LATNAMES array than in the LATS array, the extra LATNAMES are ignored. If there are more elements in the LATS array than in the LATNAMES array, labels in degrees will be automatically provided for the missing latitude labels. The LATNAMES keyword can be also used when the LATS keyword is set to a single value. It this case, the first label supplied will be used at the specified latitude; subsequent names will be placed at the next latitude line to the north, wrapping around the globe if appropriate. Caution should be used when using LATNAMES in conjunction with a single LATS value, since the number of visible latitude gridlines is dependent on many factors.

LATS in optional type=float

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). Automatically generated latitudes have values that extend over the map. If LATS is a single value, that value is taken to be the starting point for labelling (See the LABEL keyword).

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.

LINESTYLE in optional type=integer default=1

This keyword is the same as the GLineStyle keyword, but is a more natural way of setting the value.

LONALIGN in optional type=float default=0.0

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.

LONDELTA in optional type=float

Set this keyword to the spacing in degrees between parallels of longitude in the grid. If this keyword is not set, a suitable value is determined from the current map projection.

LONLABEL in optional type=float

The latitude at which to place longitude labels. The default is the center longitude on the map if using Map_Set, and a longitude line on the left of the plot if using Map_Proj_Init. This keyword is ignored if the Box_Axes keyword is set.

LONNAMES in optional type=string

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 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. The number of elements in the two arrays need not be equal. If there are more elements in the LATNAMES array than in the LATS array, the extra LATNAMES are ignored. If there are more elements in the LATS array than in the LATNAMES array, labels in degrees will be automatically provided for the missing longitude labels. The LATNAMES keyword can be also used when the LATS keyword is set to a single value. It this case, the first label supplied will be used at the specified longitude; subsequent names will be placed at the next longitude line to the north, wrapping around the globe if appropriate. Caution should be used when using LATNAMES in conjunction with a single LATS value, since the number of visible longitude gridlines is dependent on many factors.

LONS in optional type=float

Set this keyword equal to a one or more element vector of longitudes for which lines will be drawn (and optionally labeled). If LATS is omitted, appropriate longitudes will be generated based on the value of the (optional) LATDEL keyword. If LATS is set to a single value, that longitude and a series of automatically generated longitudes will be drawn (and optionally labeled). Automatically generated longitudes have values that extend over the map. If LATS is a single value, that value is taken to be the starting point for labelling (See the LABEL keyword).

MAP_STRUCTURE in optional

This keyword is normally used to pass in a map structure of the type created by Map_Proj_Init. In this version of the program, it can also be used to pass in a cgMap object, from which the map structure and other pertinent information for creating map grid lines can be obtained.

NOCLIP in optional type=boolean default=0

Normally, output is clipped to the map projection boundaries. Set this keyword to be able to draw outside the map boundaries.

NO_GRID in optional type=boolean default=0

Set this keyword if you only want labels but not grid lines.

ORIENTATION in optional type=float default=0.0

Set this keyword equal to an angle in degrees from horizontal (in the clockwise direction) to rotate the labels. This keyword is ignored if the Box_Axes keyword is set.

T3D in optional type=boolean default=0

Set this keyword if you are labeling in 3D space.

THICK in optional type=integer default=!P.Thick

Sets the thickness of the grid lines.

ZVALUE in optional type=float

Draw the grid lines at this Z-value. Implies the use of T3D.

File attributes

Modification date: Tue Jan 21 08:53:33 2014
Lines: 1,135
Docformat: rst rst