NCL Home > Documentation > Functions > Lat/Lon functions

gc_inout

Determines if a specified point is inside or outside of a spherical polygon.

Available in version 4.3.1 or later.

Prototype

	function gc_inout (
		plat  : numeric,  
		plon  : numeric,  
		lat   : numeric,  
		lon   : numeric   
	)

	return_val  :  logical

Arguments

plat
plon

Latitude and longitude, in degrees, of a point on the globe. These can be scalars or multi-dimensional arrays with the number of dimensions being one less than the number of dimensions of input arguments lat and lon (described below). If arrays, they must have the same dimension sizes as lat and lon up through the penultimate dimension of lat and lon.

lat
lon

Latitudes and longitudes, in degrees, of the vertices of a spherical polygon. These can be multi-dimensional arrays with the rightmost dimension containing the polygonal data. It is assumed that the polygons do not cross themselves and that the vertices can be contained in a hemisphere. The arrays must agree in number of dimensions and dimension sizes.

Return value

If the input arrays are singly dimensioned, then the return value will be either True or False - True if the specified point is inside the polygon and False otherwise. If the input arrays are multi-dimensional, then the returned array will have one less dimension than the number of dimensions of the input arrays and the dimension sizes of the returned array will agree with those of the input arrays up through their penultimate dimension. The return values will be True or False depending on whether the specified points are inside or outside of the polygons.

Description

This function determines if a specified point is inside or outside of a spherical polygon. A point is considered inside if it is strictly inside or on a boundary arc. Given the discrete nature of floating point arithmetic a point is considered to be on a boundary arc if it is within 1.e-10 degrees of it.

Missing values are not honored as such.

See Also

gc_onarc

Examples

Example 1

The following: 

begin
;
;  Point at center of diamond.
;
  inout = gc_inout(0.0, -2.0, (/ 0.0,  1.0,  0.0, -1.0,  0.0/), \
                              (/-3.0, -2.0, -1.0, -2.0, -3.0/) )
  print(inout)
end
produces:

Variable: inout
Type: logical
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
(0)     True
Example 2

The following: 

begin
;
;  Point on a boundary arc.
;
  plat = 20.
  plon =  0.
  qlat = (/0.0, 45.0, 45.0, 0.0/)
  qlon = (/0.0, 45.0,  0.0, 0.0/)
  inout = gc_inout(plat, plon, qlat, qlon)
  print(inout)
end
produces:

Variable: inout
Type: logical
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
(0)     True
Example 3

The following: 

begin
  lat = (/                                                       \
            (/ (/  0.0,   0.0,  2.0/), (/ 0.0,  0.0,  1.0/) /),  \
            (/ (/  0.0,   0.0,  2.0/), (/ 0.0,  0.0,  1.0/) /),  \
            (/ (/ 89.0,  89.0, 89.0/), (/ 0.0,  0.0, 80.0/) /)   \
         /)
  lon = (/                                                          \
            (/ (/ 0.0,    2.0,   1.0/), (/ -1.0,   1.0, -1.0/) /),  \
            (/ (/ 0.0,    2.0,   1.0/), (/ -1.0,   1.0, -1.0/) /),  \
            (/ (/ 0.0,  120.0, 240.0/), (/  0.0,  90.0, 45.0/) /)   \
         /)

  p0_lat = (/ (/ 1.0,  0.0/),  \
              (/ 1.0, -0.1/),  \
              (/90.0, 45.0/)   \
            /)
  p0_lon = (/ (/ 1.0,  0.0/),  \
              (/ 0.0,  0.0/),  \
              (/ 0.0, 45.0/)   \
            /)

  inout = gc_inout(p0_lat, p0_lon, lat, lon)
  print(inout)
end
produces:

Variable: inout
Type: logical
Total Size: 24 bytes
            6 values
Number of Dimensions: 2
Dimensions and sizes:   [3] x [2]
Coordinates: 
(0,0)   True
(0,1)   True
(1,0)   False
(1,1)   False
(2,0)   True
(2,1)   True