# libpysal.cg.PolygonLocator

class libpysal.cg.PolygonLocator(polygons)

  An abstract representation of a polygon indexing data structure.

  __init__(polygons)

    Returns a polygon locator object.

    __init__(Polygon list) -> PolygonLocator

    Parameters:
      polygons `a` `python:list` `of` `polygons` `to` `index`

    Examples

        >>> p1 = Polygon([Point((0, 1)), Point((4, 5)), Point((5, 1))])
        >>> p2 = Polygon([Point((3, 9)), Point((6, 7)), Point((1, 1))])
        >>> pl = PolygonLocator([p1, p2])
        >>> isinstance(pl, PolygonLocator)
        True

  Methods

  `__init__`(polygons) | Returns a polygon locator object.
  `contains_point`(point) | Returns polygons that contain point
  `inside`(query_rectangle) | Returns polygons that are inside query_rectangle
  `nearest`(query_point[, rule]) | Returns the nearest polygon indexed to a query point based on various rules.
  `overlapping`(query_rectangle) | Returns list of polygons that overlap query_rectangle
  `proximity`(origin, r[, rule]) | Returns the indexed polygons located within some distance of an origin point based on various rules.
  `region`(region_rect) | Returns the indexed polygons located inside a rectangular query region.

  contains_point(point)

    Returns polygons that contain point

    Parameters:
      point: point (x,y)
    Returns:
      `python:list` `of` `polygons` `containing` `point`

    Examples

        >>> p1 = Polygon([Point((0,0)), Point((6,0)), Point((4,4))])
        >>> p2 = Polygon([Point((1,2)), Point((4,0)), Point((4,4))])
        >>> p1.contains_point((2,2))
        1
        >>> p2.contains_point((2,2))
        1
        >>> pl = PolygonLocator([p1, p2])
        >>> len(pl.contains_point((2,2)))
        2
        >>> p2.contains_point((1,1))
        0
        >>> p1.contains_point((1,1))
        1
        >>> len(pl.contains_point((1,1)))
        1
        >>> p1.centroid
        (3.3333333333333335, 1.3333333333333333)
        >>> pl.contains_point((1,1))[0].centroid
        (3.3333333333333335, 1.3333333333333333)

  inside(query_rectangle)

    Returns polygons that are inside query_rectangle

    Notes

    inside means the intersection of the query rectangle and a polygon is not empty and is equal to the area of the polygon

    Examples

        >>> p1 = Polygon([Point((0, 1)), Point((4, 5)), Point((5, 1))])
        >>> p2 = Polygon([Point((3, 9)), Point((6, 7)), Point((1, 1))])
        >>> p3 = Polygon([Point((7, 1)), Point((8, 7)), Point((9, 1))])
        >>> pl = PolygonLocator([p1, p2, p3])
        >>> qr = Rectangle(0, 0, 5, 5)
        >>> res = pl.inside( qr )
        >>> len(res)
        1
        >>> qr = Rectangle(3, 7, 5, 8)
        >>> res = pl.inside( qr )
        >>> len(res)
        0
        >>> qr = Rectangle(10, 10, 12, 12)
        >>> res = pl.inside( qr )
        >>> len(res)
        0
        >>> qr = Rectangle(0, 0, 12, 12)
        >>> res = pl.inside( qr )
        >>> len(res)
        3

  nearest(query_point, rule='vertex')

    Returns the nearest polygon indexed to a query point based on various rules.

    nearest(Polygon) -> Polygon

    Parameters:
      query_point `a` `point` `to` `find` `the` `nearest` `indexed` `polygon` `to`
      rule `representative` `point` `for` `polygon` `in` `nearest` query.

        vertex – measures distance between vertices and query_point centroid – measures distance between centroid and query_point edge – measures the distance between edges and query_point

    Examples

        >>> p1 = Polygon([Point((0, 1)), Point((4, 5)), Point((5, 1))])
        >>> p2 = Polygon([Point((3, 9)), Point((6, 7)), Point((1, 1))])
        >>> pl = PolygonLocator([p1, p2])
        >>> try: n = pl.nearest(Point((-1, 1)))
        ... except NotImplementedError: print("future test: str(min(n.vertices())) == (0.0, 1.0)")
        future test: str(min(n.vertices())) == (0.0, 1.0)

  overlapping(query_rectangle)

    Returns list of polygons that overlap query_rectangle

    Notes

    overlapping means the intersection of the query rectangle and a polygon is not empty and is no larger than the area of the polygon

    Examples

        >>> p1 = Polygon([Point((0, 1)), Point((4, 5)), Point((5, 1))])
        >>> p2 = Polygon([Point((3, 9)), Point((6, 7)), Point((1, 1))])
        >>> p3 = Polygon([Point((7, 1)), Point((8, 7)), Point((9, 1))])
        >>> pl = PolygonLocator([p1, p2, p3])
        >>> qr = Rectangle(0, 0, 5, 5)
        >>> res = pl.overlapping( qr )
        >>> len(res)
        2
        >>> qr = Rectangle(3, 7, 5, 8)
        >>> res = pl.overlapping( qr )
        >>> len(res)
        1
        >>> qr = Rectangle(10, 10, 12, 12)
        >>> res = pl.overlapping( qr )
        >>> len(res)
        0
        >>> qr = Rectangle(0, 0, 12, 12)
        >>> res = pl.overlapping( qr )
        >>> len(res)
        3
        >>> qr = Rectangle(8, 3, 9, 4)
        >>> p1 = Polygon([Point((2, 1)), Point((2, 3)), Point((4, 3)), Point((4,1))])
        >>> p2 = Polygon([Point((7, 1)), Point((7, 5)), Point((10, 5)), Point((10, 1))])
        >>> pl = PolygonLocator([p1, p2])
        >>> res = pl.overlapping(qr)
        >>> len(res)
        1

  proximity(origin, r, rule='vertex')

    Returns the indexed polygons located within some distance of an origin point based on various rules.

    proximity(Polygon, number) -> Polygon list

    Parameters:
      origin `the` `point` `to` `find` `indexed` `polygons` `near`
      r `the` `maximum` `distance` `to` `find` `indexed` `polygon` `from` `the` `origin` `point`
      rule `representative` `point` `for` `polygon` `in` `nearest` query.

        vertex – measures distance between vertices and query_point centroid – measures distance between centroid and query_point edge – measures the distance between edges and query_point

    Examples

        >>> p1 = Polygon([Point((0, 1)), Point((4, 5)), Point((5, 1))])
        >>> p2 = Polygon([Point((3, 9)), Point((6, 7)), Point((1, 1))])
        >>> pl = PolygonLocator([p1, p2])
        >>> try:
        ...     len(pl.proximity(Point((0, 0)), 2))
        ... except NotImplementedError:
        ...     print("future test: len(pl.proximity(Point((0, 0)), 2)) == 2")
        future test: len(pl.proximity(Point((0, 0)), 2)) == 2

  region(region_rect)

    Returns the indexed polygons located inside a rectangular query region.

    region(Rectangle) -> Polygon list

    Parameters:
      region_rect `the` `rectangular` `range` `to` `find` `indexed` `polygons` `in`

    Examples

        >>> p1 = Polygon([Point((0, 1)), Point((4, 5)), Point((5, 1))])
        >>> p2 = Polygon([Point((3, 9)), Point((6, 7)), Point((1, 1))])
        >>> pl = PolygonLocator([p1, p2])
        >>> n = pl.region(Rectangle(0, 0, 4, 10))
        >>> len(n)
        2