>  Docs Center  >  Libraries  >  Motley  >  MGH_POLY_INSIDE

MGH_POLY_INSIDE

MGH_POLY_INSIDE

Name


  MGH_POLY_INSIDE

Purpose


  Determine whether a point or set of points is inside a polygon.

Calling Sequence


  result = mgh_poly_inside(x, y, xp, yp)
  result = mgh_poly_inside(x, y, xyp)

Positional Parameters


  x, y (input, numeric scalar or array
    X, Y position(s) defining the point(s) to be tested.
  xp, yp (input, numeric vector)
  xyp (input, numeric array)
    The polygons vertices as 2 separate vectors (xp, yp) OR a single
    [2,n] array.

Keyword Parameters


  EDGE (input, switch)
    Set this keyword to accept edge (& vertex) points as
    "inside". Default is to reject them.
  NAN (input, switch)
    Set this keyword to specify that all points for which X or Y is
    not finite (eg Nan, Inf) are to return 0. Default is to process
    non-finite points, which leads to floating point errors and an
    undefined result for that point.

Return Value


  The function returns an array of the same shape as X. Each element
  is 0 if the point is outside the polygon, 1 if it is inside the polygon.

Procedure


  This routine calculates the displacement vectors from each point
  to all the vertices of the polygon and then takes angles between
  each pair of successive vectors. The sum of the angles is zero for
  a point outside the polygon, and +/- 2*pi for a point inside. A
  point on an edge will have one such angle equal to +/- pi. Points
  on a vertex have a zero displacement vector.

References


  Note that the question of how to determine whether a point is
  inside or outside a polygon was discussed on comp.lang.idl-pvwave
  in October 1999. The following is quoted from a post by Randall
  Frank <randall-frank@computer.org>:
      I would suggest you read the Graphics FAQ on this issue and
      also check Graphics Gem (I think volume 1) for a more detailed
      explanation of this problem. The upshot is that there really
      are three core methods and many variants. In general, you can
      sum angles, sum signed areas or clip a line. There are good
      code examples of all these approaches on the net which can be
      coded into IDL very quickly. It also depends on how you
      intend to use the function. If, you are going to repeatedly
      test many points, you are better off using one of the sorted
      variants of the line clipping techniques. In general, the
      line clipping techniques are the fastest on the average, but
      have poor worst case performance without the sorting overhead.
      The angle sum is one of the slowest methods unless you can get
      creative and avoid the transcendentals (and you can). The
      area sum approach generally falls in between. In IDL code, I
      believe you can vectorize the latter with some setup overhead,
      making it the fastest for .pro code when testing multiple
      points with one point per call.

Further Resources


    - "Misc Notes - WR Franklin",
      http://www.ecse.rpi.edu/Homepages/wrf/misc.html: includes a
      reference (broken @ Jul 2001) to his point-in-polygon code.
    - Comp.graphics.algorithms FAQ,
      http://www.faqs.org/faqs/graphics/algorithms-faq/: See subject
      2.03

See Also


  MGH_PNPOLY, which implements a line-clipping technique and is much
  faster.

To Do


  Reduce copying of input data by segregating the calculations into a
  separate function.
###########################################################################
  Copyright (c) 1995-2015 NIWA:
  http://www.niwa.co.nz/
  Licensed under the MIT open source license:
  http://www.opensource.org/licenses/mit-license.php
###########################################################################

Modification History


  Mark Hadfield, 1995-06:
    Written based on ideas in MATLAB routine INSIDE.M in the WHOI
    Oceanography Toolbox v1.4 (R. Pawlowicz, 14 Mar 94,
    rich@boreas.whoi.edu).
  Mark Hadfield, 2000-12:
    Updated.
  Mark Hadfield, 2001-07:
    Changed argument order: polygon vertices are now before test
    position(s).
  Mark Hadfield, 2009-09:
    Changed argument order back. Polygon can now be entered as a
    [2,n] array.
  Mark Hadfield, 2015-02:
    Updated source code format.



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us