Changes between Initial Version and Version 1 of ParNCLDeveloperInfo/ParNCLFeatures/FunctionDocumentation/gc_inouts


Ignore:
Timestamp:
04/05/13 16:20:26 (6 years ago)
Author:
jayesh
Comment:

Adding documentation on gc_inouts

Legend:

Unmodified
Added
Removed
Modified
  • ParNCLDeveloperInfo/ParNCLFeatures/FunctionDocumentation/gc_inouts

    v1 v1  
     1{{{ 
     2#!html 
     3<h1>gc_inouts</h1> 
     4 
     5<p> 
     6Determines if a list of lat/lon specified points are inside or outside of 
     7spherical lat/lon polygon(s). 
     8</p> 
     9 
     10<a name="Prototype"></a> 
     11<h2>Prototype</h2> 
     12<pre> 
     13        function gc_inouts ( 
     14                plat  : numeric,   
     15                plon  : numeric,   
     16                lat   : numeric,   
     17                lon   : numeric    
     18        ) 
     19 
     20        <a href="http://www.ncl.ucar.edu/Document/Functions/return_val.shtml">return_val</a>  :  logical 
     21</pre> 
     22<a name="Arguments"></a> 
     23<h2>Arguments</h2> 
     24<em>plat</em> 
     25<br> 
     26<em>plon</em> 
     27<p class=indent>Latitude and longitude, in degrees, of points on the globe that you 
     28want to check whether they fall inside or outside of polygon(s) 
     29defined by <em>lat</em> and <em>lon</em>.  
     30</p> 
     31<p class=indent> 
     32 
     33The arrays are one-dimensional and must agree in dimension sizes. 
     34</p> 
     35<em>lat</em> 
     36<br> 
     37<em>lon</em> 
     38<p class=indent>Latitudes and longitudes, in degrees, of the vertices of one or more 
     39spherical polygons. 
     40</p> 
     41<p class=indent> 
     42 
     43If these are multi-dimensional arrays, then the rightmost dimension 
     44must contain the polygonal data. For multi-dimensional arrays the points 
     45specified by <em>plat</em> and <em>plon</em> must be and are evenly distributed 
     46across the polygons. 
     47</p> 
     48<p class=indent> 
     49 
     50It is assumed that the polygons do not cross themselves and that the 
     51vertices can be contained in a hemisphere. If the polygons are not 
     52closed (that is, if the first listed vertex doesn't equal the last), 
     53then this function will close the polygon for you. 
     54</p> 
     55<p class=indent> 
     56 
     57The arrays must agree in number of dimensions and dimension sizes. 
     58</p> 
     59<p class=indent> 
     60</p> 
     61<a name="Return"></a> 
     62<h2>Return value</h2> 
     63<p> 
     64The return value will be a logical array with the same 
     65dimensions as <em>plat</em> and <em>plon</em>. 
     66<p> 
     67 
     68True is returned if the specified point is inside the polygon and 
     69False otherwise. 
     70</p><a name="Description"></a> 
     71<h2>Description</h2> 
     72<p> 
     73This function determines if specified points are inside or outside of 
     74a list of spherical polygons. The polygons must be closed polygons; 
     75if the first listed vertex does not equal the last then the code will 
     76add an additional vertex to close the polygon.  A point is considered 
     77inside if it is strictly inside or on a boundary arc.  Given the 
     78discrete nature of floating point arithmetic, a point is considered to 
     79be on a boundary arc if it is within 1.e-10 degrees of it. 
     80<p> 
     81 
     82Missing values are not honored as such. 
     83 
     84 
     85</p><a name="See_also"></a> 
     86<h2>See Also</h2> 
     87<p> 
     88<a href="http://www.ncl.ucar.edu/Document/Functions/Built-in/gc_inout.shtml">gc_inout</a> 
     89</p><a name="Examples"></a> 
     90<h2>Examples</h2> 
     91<p> 
     92<B>Example 1</B><p> 
     93 
     94The following: 
     95 
     96<PRE> 
     97begin 
     98; 
     99;  Point at center of diamond. 
     100; 
     101  inout = gc_inouts(0.0, -2.0, (/ 0.0,  1.0,  0.0, -1.0,  0.0/), \ 
     102                              (/-3.0, -2.0, -1.0, -2.0, -3.0/) ) 
     103  print(inout) 
     104end 
     105 
     106</PRE> 
     107 
     108produces:<p> 
     109 
     110<PRE> 
     111Variable: inout 
     112Type: logical 
     113Total Size: 4 bytes 
     114            1 values 
     115Number of Dimensions: 1 
     116Dimensions and sizes:   [1] 
     117Coordinates:  
     118(0)     True 
     119</PRE> 
     120 
     121<B>Example 2</B><p> 
     122 
     123The following: 
     124 
     125<PRE> 
     126begin 
     127; 
     128;  Point on a boundary arc. 
     129; 
     130  plat = 20. 
     131  plon =  0. 
     132  qlat = (/0.0, 45.0, 45.0, 0.0/) 
     133  qlon = (/0.0, 45.0,  0.0, 0.0/) 
     134  inout = gc_inouts(plat, plon, qlat, qlon) 
     135  print(inout) 
     136end 
     137</PRE> 
     138 
     139produces:<p> 
     140 
     141<PRE> 
     142Variable: inout 
     143Type: logical 
     144Total Size: 4 bytes 
     145            1 values 
     146Number of Dimensions: 1 
     147Dimensions and sizes:   [1] 
     148Coordinates:  
     149(0)     True 
     150</PRE> 
     151 
     152<B>Example 3</B><p> 
     153 
     154The following: 
     155 
     156<PRE> 
     157begin 
     158  lat = (/  0.0,   0.0,  2.0,  0.0,  0.0,  1.0,  \ 
     159            0.0,   0.0,  2.0,  0.0,  0.0,  1.0,  \ 
     160            89.0,  89.0, 89.0, 0.0,  0.0, 80.0  \ 
     161         /) 
     162  lon = (/  0.0,   2.0,   1.0,  -1.0,   1.0, -1.0,  \ 
     163            0.0,   2.0,   1.0,  -1.0,   1.0, -1.0,  \ 
     164            0.0, 120.0, 240.0,   0.0,  90.0, 45.0   \ 
     165         /) 
     166 
     167  p0_lat = (/ (/ 1.0,  0.0/),  \ 
     168              (/ 1.0, -0.1/),  \ 
     169              (/90.0, 45.0/)   \ 
     170            /) 
     171  p0_lon = (/ (/ 1.0,  0.0/),  \ 
     172              (/ 0.0,  0.0/),  \ 
     173              (/ 0.0, 45.0/)   \ 
     174            /) 
     175 
     176  inout = gc_inouts(p0_lat, p0_lon, lat, lon) 
     177  print(inout) 
     178end 
     179</PRE> 
     180 
     181produces:<p> 
     182 
     183<PRE> 
     184Variable: inout 
     185Type: logical 
     186Total Size: 24 bytes 
     187            6 values 
     188Number of Dimensions: 2 
     189Dimensions and sizes:   [3] x [2] 
     190Coordinates:  
     191(0,0)   True 
     192(0,1)   True 
     193(1,0)   False 
     194(1,1)   False 
     195(2,0)   True 
     196(2,1)   True 
     197</PRE> 
     198</p> 
     199</div> 
     200 
     201<p>&nbsp;</p> 
     202 
     203}}}