NCL Website header
NCL Home > Documentation > Functions > General applied math, Graphics routines

geolocation_circle

Create latitudes and longitudes that define concentric circles at user specified distances from a central location.

Available in version 6.5.0 and later.

Prototype

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

	function geolocation_circle (
		clat [*] : numeric,  
		clon [*] : numeric,  
		crad [*] : numeric,  
		urad [1] : integer,  
		N    [1] : integer,  
		opt  [1] : logical   
	)

	return_val  :  float or double

Arguments

clat
clon

Scalars or one-dimensional arrays containing the 'center' location latitudes or latitudes. If these are arrays,they must be the same length. Missing values are not allowed.

Most commonly, these might be station or grid point locations or a time series of (say) low-pressure center locations.

crad

Scalar or one-dimensional array containing the radial distances for each circle. The units can be degrees (great circle degrees) or kilometers (km).

urad

An integer which specifies the units of crad: =0 means degrees (dg); =1 mean kilometers (km)

opt

Currently, not used. Set to False.

Return value

A variable of type list containing two variables (say, Rlat and Rlon) which contain the geolocated latitudes and longitudes for each specified location pair at each radius.

       Rlat(dimsizes(clat),dimsizes(crad),N), 
       Rlon(dimsizes(clat),dimsizes(crad),N)).

Informational attributes are also returned.

Description

geolocation_circle computes N latitude and longitudes at each specified crad. The nggcog is used for the computations.

See Also

nggcog, gc_inout

Examples

Example 1: The plot created by the following script is here.


; *********************************
; Draw circles
;**********************************

;---One station with multiple radii

    slat      =   30.192                     ; lat: station or storm
    slon      =  280.477                     ; lon: station or storm
    srad      = (/ 50, 150, 300, 500, 750/)  ; station radii (km)
    srad_unit = 1                            ; km
    N         = 180                          ; # of points; more points nicer 'circle'
    opt       = False
;---End input

    nLoc = dimsizes(slat)                   ; # locations
    nRad = dimsizes(srad)                   ; # radii

    circle    = geolocation_circle(slat, slon, srad, srad_unit, N, opt) ; circle is type list

;---Extract variables from 'list'
    printVarSummary(circle)
    circle_lat = circle[0]                   ; clarity: explicitly extract list variables
    circle_lon = circle[1]

;---Print and examine returned variables
    printVarSummary(circle_lat)
    print("------------------")
    printVarSummary(circle_lon)
    print("------------------")
 
;---Print the lat/lon for the last radius [ for fun ] 
    print(circle_lat(nRad-1,:)+"  "+circle_lon(nRad-1,:))
     
;*************************************************
; Plot
;*************************************************

    pltType          = "png" 
    pltDir           = "./" 
    pltName          = "geolocation_circle" 
    pltPath          = pltDir + pltName

;---Resources for background map
    res              = True   
    res@gsnDraw      = False                  
    res@gsnFrame     = False    
    res@gsnMaximize  = True    

   ;res@mpProjection = "CylindricalEquidistant"            ; choose map projection
   ;res@mpLimitMode  = "LatLon"
    res@mpOutlineBoundarySets  = "GeophysicalAndUSStates"   ; add state boundaries
    res@mpGeophysicalLineColor = "Gray"
    res@mpUSStateLineColor     = "LightGray"
    res@mpMinLatF    = slat - 7.5                          ; add 'buffer' around central location
    res@mpMaxLatF    = slat + 7.5
    res@mpMinLonF    = slon - 10
    res@mpMaxLonF    = slon + 10
    res@mpCenterLonF = (res@mpMinLonF  + res@mpMaxLonF )*0.5 
    res@mpGeophysicalLineThicknessF  = 1.5
    res@mpFillOn                     = False          

;--Text for map
    res@tiMainString   = "Center: ("+sprintf("%5.1f", slat)+","+sprintf("%5.1f", slon)+")"

    res@gsnStringFontHeightF = 0.0125 
    res@gsnLeftString  = "Radii: km: "
    res@gsnRightString = "dg: "
    do nr=0,nRad-2
       res@gsnLeftString  = res@gsnLeftString  + sprinti("%2.2i", srad(nr))+","
       res@gsnRightString = res@gsnRightString + sprintf("%4.2f", circle_lat@radii_converted_values(nr) )+","
    end do
    res@gsnLeftString  = res@gsnLeftString  + sprinti("%2.2i", srad(nRad-1))
    res@gsnRightString = res@gsnRightString + sprintf("%4.2f", circle_lat@radii_converted_values(nRad-1) )

;*****************************************************
;               Plot
;*****************************************************

    wks  = gsn_open_wks(pltType, pltPath)
    plot = gsn_csm_map(wks,res)       ; draw background map

    plres  = True
    plres@gsMarkerIndex = 2           ; Plus sign ( + )
   ;plres@gsMarkerIndex = 15          ; Circle with x
   ;plres@gsMarkerIndex = 16          ; Filled Circle
    plres@gsMarkerSizeF = 10.       
    plres@gsMarkerColor = "black"  
    plot@$"marker"$     = gsn_add_polymarker(wks, plot, slon, slat, plres) ; "marker" is arbitrary

    colors = (/ "magenta", "orange", "red", "DarkGreen", "blue"  /)
    thick  = (/    1     ,  1.5    ,  2.0 ,   3.0      ,   4.0   /) 

    do nl=0,nLoc-1
      do nr=0,nRad-1
         plres@gsLineColor      = colors(nr)
         plres@gsLineThicknessF = thick(nr)
         circ_id = "radii_"+nl+"_"+nr           ; any unique name
         plot@$circ_id$ = gsn_add_polyline(wks, plot, circle_lon(nl,nr,:), circle_lat(nl,nr,:), plres)
      end do       ; nr
    end do         ; nl

    draw(plot)
    frame(wks)

-------------------------------------------------------------------------
The (edited) output follows:

          Variable: circle
          Type: list  
          Total items: 2            
          
          
          Variable: circle_lat
          Type: float
          Total Size: 3600 bytes
                      900 values
          Number of Dimensions: 2
          Dimensions and sizes:	[location | 1] x [radii | 5] x [circle | 180]
          Coordinates: 
          Number Of Attributes: 7
            units :	degrees_north
            long_name :	circle latitudes
            radii_converted_values :	( 0.4522022, 1.356607, 2.713213, 4.522022, 6.783033 )
            radii_converted_units :	great_circle_degrees
            radii_input_values :	( 50, 150, 300, 500, 750 )
            radii_input_units :	km
            _FillValue :	9.96921e+36

          ------------------
          
          Variable: circle_lon
          Type: float
          Total Size: 3600 bytes
                      900 values
          Number of Dimensions: 2
          Dimensions and sizes:	[location | 1] x [radii | 5] x [circle | 180]
          Coordinates: 
          Number Of Attributes: 7
            units :	degrees_east
            long_name :	circle longitudes
            radii_input_units :	km
            radii_input_values :	( 50, 150, 300, 500, 750 )
            radii_converted_units :	great_circle_degrees
            radii_converted_values :	( 0.4522022, 1.356607, 2.713213, 4.522022, 6.783033 )
            _FillValue :	9.96921e+36

        ------------------

          (0)	23.409   -79.523
          (1)	23.4129  -79.2642
          (2)	23.4247  -79.0057
          (3)	23.4443  -78.7477
          (4)	23.4717  -78.4905
          (5)	23.5069  -78.2344
          (6)	23.5499  -77.9796
          (7)	23.6005  -77.7264
          (8)	23.6589  -77.475
          [SNIP]
          (86)	36.9199  -78.4856
          (87)	36.9469  -78.7809
          (88)	36.9649  -79.0773
          (89)	36.9739  -79.3744
          (90)	36.9739  -79.6717
          (91)	36.9649  -79.9688
          (92)	36.9469  -80.2651
          (93)	36.9199  -80.5604
          (94)	36.8839  -80.854
          [SNIP]
          (172)	23.6005  -81.3196
          (173)	23.5499  -81.0665
          (174)	23.5069  -80.8117
          (175)	23.4717  -80.5555
          (176)	23.4443  -80.2983
          (177)	23.4247  -80.0403
          (178)	23.4129  -79.7818
          (179)	23.409   -79.523

Example 2: The following illustrates multiple locations and radii. The full script is 
here. The created plot is here.

;---Multiple locations (eg: time series of locations) and radii

  slat      = (/ 27.0, 31.5, 34.7 /)       ; lat: stations or storm centers
  slon      = (/273.5,280.0,284.3/)        ; lon: stations or storm centers
  srad      = (/ 1, 3 /)                   ; radii (great circle degrees)
  srad_unit = 0                            ; 0=degrees
  N         = 90                           ; # of points; more points nicer 'circle'
  opt       = False
[SNIP]
The (edited) output follows:

          Variable: circle_lat
          Type: float
          Total Size: 2160 bytes
                      540 values
          Number of Dimensions: 3
          Dimensions and sizes:	[location | 3] x [radii | 2] x [circle | 90]
          Coordinates: 
          Number Of Attributes: 5
            _FillValue :	9.96921e+36
            radii_units_input :	great_circle_degrees
            radii_input_values :	(  1,  3 )
            long_name :	circle latitudes
            units :	degrees_north

         ------------------
          
          Variable: circle_lon
          Type: float
          Total Size: 2160 bytes
                      540 values
          Number of Dimensions: 3
          Dimensions and sizes:	[location | 3] x [radii | 2] x [circle | 90]
          Coordinates: 
          Number Of Attributes: 5
            _FillValue :	9.96921e+36
            radii_input_values :	(  1,  3 )
            radii_units_input :	great_circle_degrees
            long_name :	circle longitudes
            units :	degrees_east