What is the difference between Polygon.contains and Polygon.within?

Question

The Docstring says:

Polygon.contains Returns True if the geometry contains the other, else False

Polygon.within Returns True if geometry is within the other, else False

How are they different?

Solution

They are inverse relationships: A contains B, and B is within A.

   >>> A.contains(B)
   True
   >>> B.within(A)
   True

   +----------------------------------+
   |                                  |
   |         +----------+             |
   |         |          |             |
   |         |          |             |
   |         |          |             |
   |         |          |             |
   |         |          |             |
   |         |    B     |             |
   |         |          |             |
   |         +----------+             |
   |                                  |
   |                                  |
   |   A                              |
   |                                  |
   +----------------------------------+

Comments

[Sounak]

what happens if A overlaps B ? why there are two functions? isn't one enough?

[chepner]

I think neither would be true, since neither shape is wholly within the other. If you mean A and B are essentially the same shape, both would be false. From the manual for contains (emphasis mine): "Returns True if the object’s interior contains the boundary and interior of the other object and their boundaries do not touch at all."

[chepner]

One would be sufficient--you could define within(self, obj) as simply return obj.contains(self)--but it may be more readable to use one or the other, depending on the context.

[Sounak]

poly = Polygon(((0, 0), (0, 2), (2, 2), (2, 0))) po = Point((1,1)) print poly.contains(po) True print poly.within(po) False

[Sounak]

something is different here.

[chepner]

po.within(poly) should be true, though. You have to switch the caller and the argument.