NCL Home > Documentation > Graphics > Graphical Interfaces

gsn_coordinates

Draws or attaches the data coordinate locations on the given plot as grid lines or markers.

Available in version 6.1.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"  ; This library is automatically loaded
                                                          ; from NCL V6.2.0 onward.
                                                          ; No need for user to explicitly load.

	procedure gsn_coordinates (
		wks  [1] : graphic,  
		plot [1] : graphic,  
		data     : numeric,  
		res      : logical   
	)

Arguments

wks

A Workstation identifier. The identifier is one returned either from calling gsn_open_wks or calling create to create a Workstation object.

plot

The plot identifier on which to draw the coordinates. It can be created by using one of the many gsn functions, or by calling create to create a View object.

data

The data array that contains the coordinates to be drawn, either as 1D coordinate arrays, as special "lat2d"/"lon2d" attributes, or, (as of NCL 6.2.0) as special "lat1d"/"lon1d" attributes. If there are no coordinates associated with the data, then see the special "gsnCoordsLat"/"gsnCoordsLon" and "gsnCoordsX"/"gsnCoordsY" attributes below.

res

A logical variable containing an optional list of resources for drawing the coordinates. Set to True if you want the attached attributes to be applied, and False if you either don't have any resources to set, or you don't want the resources applied.

Description

This function draws the given plot and the coordinate locations associated with data on the plot as either markers or lines. The data can be on a rectilinear grid, a curvilinear grid, or, as of NCL V6.6.0, on an unstructured mesh.

This procedure is especially useful for debugging purposes, if you want to see what your data structure looks like, or you need to see at which coordinate locations you have missing values.

If gsnCoordsAttach is set to True, then the lines or markers will be attached to plot, and nothing will get drawn until you draw the plot. This is mainly useful for if you need to draw the plot later, say in a panel plot.

The best way to understand how this procedure works is to visit the NCL examples page. See the examples section below for pointers.

The res variable can contain the following special attributes:

gsnCoordsLat / gsnCoordsLon (or gsnCoordsY / gsnCoordsX)
If your input data array doesn't have one-dimensional coordinate arrays or the special "lat2d"/"lon2d" or "lat1d"/"lon1d" attributes attached, then you can use either of these two attribute pairs to set the coordinates for the X and Y axis. These two arrays must both be the same dimensionality.

gsnCoordsNonMissingColor
If drawing the coordinates as markers, this attribute indicates a color to draw the locations of the non-missing data.

gsnCoordsMissingColor
If drawing the coordinates as markers, this attribute indicates a color to draw the locations of the missing data.

gsnCoordsAsLines
If set to True, the coordinates will be drawn as a lat/lon grid. The default is to draw the grid with markers (filled dots).

gsnCoordsAttach
By default, the markers or lines are drawn with gsn_polymarker or gsn_polyline and are not attached to the plot. If you need to attach the markers or lines (perhaps for paneling the plot later), then set this attribute to True.

The attributes below were added in NCL Version 6.6.0 to support the drawing of unstructured meshes.

The attributes below allow both the cell edges and the cell centers to be drawn, if desired. For examples of using these attributes, visit the "Drawing locations of data" examples page.

gsnCoordsMeshLatCenter / gsnCoordsMeshLonCenter - NCL V6.6.0
1D arrays containing the lat/lon locations of each mesh cell center. If set, then these will be drawn as markers.

gsnCoordsMeshLatBounds / gsnCoordsMeshLonBounds - NCL V6.6.0
Two-dimensional arrays containing the lat,lon values for the vertices of each mesh cell. This will be dimensioned NCELLS x NEDGES where NCELLS is the number of mesh cells, and NEDGES is the number of edges that define each cell. For example, for a triangular mesh, the dimensions would be NCELLS x 3.

If these two attributes are set, then none of the gsnCoordsMeshXXXVerticesXXX or gsnCoordsMeshNumEdgesOnCell should be set.

gsnCoordsMeshLatVertices / gsnCoordsMeshLonVertices / gsnCoordsMeshVerticesOnCell - NCL V6.6.0
The gsnCoordsMeshLat/LonVertices contains the lat/lon values for each vertex in a mesh, and the gsnCoordsVerticesOnCell (NCELLS x MAX_EDGES) contains the index values into these arrays for each mesh cell.

gsnCoordsMeshVerticesStartIndex (default=0) (only 0 or 1 allowed) - NCL V6.6.0
For gsnCoordsMeshLat/LonVerticesOnCell, do the vertex indexes start at 0 or 1? That is, do they go from 1 to NCELLS or 0 to NCELLS-1? If they start at 1, then set this attribute to 1.

gsnCoordsMeshNumEdgesOnCell - NCL V6.6.0
1D array of length NCELLS containing the number of edges for each mesh cell. Only recognized if gsnCoordsMeshLat/LonVertices is set.

gsnCoordsMeshClosePolygons (default=True) - NCL V6.6.0
If the mesh cell polygons are not closed, then set this to True to force them to be closed.

gsnCoordsMinLat / gsnCoordsMaxLat gsnCoordsMinLon / gsnCoordsMaxLon - NCL V6.6.0
Set the desired min/max of the lat/lon area where the grid or mesh edges are to be drawn. This can help save significant time in drawing. If not set, then it will either default to the min/max of cell edges, or if those are not set, then the input lat/lon.

gsnCoordsConvertRad2Deg (default=False) - NCL V6.6.0
This function assumes that any input lat/lon values are in degrees_north and degrees_east. If they are in radians, then set this attribute to True to force conversion to degrees. Note: this will apply only to the following attributes. It will not apply to the lat/lon attached to the input data array via coordinate arrays or lat2d/lon2d.

There are some "gs" resources (associated with markers and lines) that you can set to customize the markers or lines:

See Also

gsn_add_polymarker, gsn_add_polyline, gsn_polymarker, gsn_polyline

Examples

This example draws a lat/lon grid over a contour plot. 

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"  
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl"  

begin
;---Read netCDF file
  f = addfile("$NCARG_ROOT/lib/ncarg/data/cdf/uv300.nc","r")
  u = f->U(1,:,:)

;---Start the graphics.
  wks = gsn_open_wks("x11","mapgrid")

  res               = True                        ; plot mods desired
  res@gsnMaximize   = True                        ; maximize plot size
  res@gsnDraw       = False                       ; don't draw yet
  res@gsnFrame      = False                       ; don't advance frame

;---Create map (don't draw it yet)
  map = gsn_csm_contour_map(wks,res)

;---Call function to draw lat/lon lines.
  pres                   = True
  pres@gsnCoordsAsLines  = True        ; Default is points
  gsn_coordinates(wks,map,u,pres)
end

For more examples of using this procedure, see the following example pages: