shapely.within

within(a, b, **kwargs)

Return True if geometry A is completely inside geometry B.

A is within B if no points of A lie in the exterior of B and at least one point of the interior of A lies in the interior of B.

For example, POINT (1 1) is within LINESTRING (0 0, 1 1, 2 2). However, POINT (0 0) is not because it only intersects the boundary of the LineString and not the interior. Intersecting with the boundary of the other is allowed though, LINESTRING (0 0, 1 1) is within LINESTRING (0 0, 1 1, 2 2) because it’s interior does intersect the other’s interior and none of it intersects the other’s exterior.

See also covered_by() for a similar but slightly more inclusive relation.

If you need to test multiple geometries against the same geometry A, you can improve performance by preparing A in advance using prepare().

Parameters:

a, bGeometry or array_like

Geometry or geometries to check.

**kwargs

See NumPy ufunc docs for other keyword arguments.

See also

contains

within(A, B) == contains(B, A).

covered_by

Return True if no point in geometry A is outside geometry B.

prepare

Improve performance by preparing a (the first argument).

Examples

>>> import shapely
>>> from shapely import LineString, Point, Polygon
>>> line = LineString([(0, 0), (1, 1)])
>>> shapely.within(Point(0, 0), line)
False
>>> shapely.within(Point(0.5, 0.5), line)
True
>>> area = Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)])
>>> shapely.within(Point(0, 0), area)
False
>>> shapely.within(line, area)
True
>>> shapely.within(LineString([(0, 0), (2, 2)]), area)
False
>>> polygon_with_hole = Polygon(
...     [(0, 0), (0, 10), (10, 10), (10, 0), (0, 0)],
...     holes=[[(2, 2), (2, 4), (4, 4), (4, 2), (2, 2)]]
... )
>>> shapely.within(Point(1, 1), polygon_with_hole)
True
>>> shapely.within(Point(2, 2), polygon_with_hole)
False
>>> shapely.within(LineString([(1, 1), (5, 5)]), polygon_with_hole)
False
>>> shapely.within(area, area)
True
>>> shapely.within(None, area)
False