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,
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.

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

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),

```
Informational attributes are also returned.

## Description

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

The gc_inout function can be used to retain or exclude values within the radii. Some examples of using gc_inout for this purpose are at:

## Examples

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

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

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

nLoc = dimsizes(slat)                   ; # locations

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 ]

;*************************************************
; 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@gsnRightString = "dg: "
res@gsnLeftString  = res@gsnLeftString  + sprinti("%2.2i", srad(nr))+","
res@gsnRightString = res@gsnRightString + sprintf("%4.2f", circle_lat@radii_converted_values(nr) )+","
end do

;*****************************************************
;               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
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_input_values :	( 50, 150, 300, 500, 750 )
_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_values :	( 50, 150, 300, 500, 750 )
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
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_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 )