Incorrect Documentation for OGRGeometry::Within and Contains

[danhomerick]

Tested with version 1.4.0.

The website documentation for Within and Contains is reverse of the actual behavior. ​http://www.gdal.org/ogr/classOGRGeometry.html

test code:

/* a square (closed) */
double x[] = {0, 1, 0, 1, 0};
double y[] = {1, 1, 0, 0, 1};
OGRLineString ring;
ring.setPoints(5, x, y);

OGRPoint middle;
middle.setX(0.5);
middle.setY(0.5);

std::cout << "" << std::endl;
std::cout << "middle.Contains(&ring): " << middle.Contains (&ring) << std::endl;
std::cout << "middle.Within(&ring): " << middle.Within(&ring) << std::endl;
std::cout << "ring.Contains(&middle): " << ring.Contains(&middle) << std::endl;
std::cout << "ring.Within(&middle): " << ring.Within(&middle) << std::endl;

Output:

middle.Contains(&ring): 0
middle.Within(&ring): 1
ring.Contains(&middle): 1
ring.Within(&middle): 0


Additionally, if changes to the docs are going to be made, it could be noted that an geometry is considered to be within/contained with itself (that is, points "on the line" count as in).

[danhomerick]

Whoops, some misleading naming slipped in. Note that "ring" is an OGRLineString -- it doesn't work at all if you use a OGRLinearRing.

[Mateusz Łoskot]

Dan, could you check and confirm that you have the GEOS support built into OGR?

[danhomerick]

Yes, GEOS support is built in. OGRGeometryFactory::haveGEOS() returns true, and the within/contains functions will return true -- just not when the documentation says they will.

[danhomerick]

Oops. The documentation was backwards, but the code snippet provided is in error. Instead of being a closed square, it's a figure-eight. Done properly, the OGRLineString has no concept of "area enclosed" and returns false unless the point is lying on it (which was the case in the flawed example).

Here's a proper code snippet to test against:

/* a square (closed) */ double x[] = {0, 1, 1, 0, 0}; double y[] = {1, 1, 0, 0, 1}; OGRLinearRing ring; ring.setPoints(5, x, y);

OGRPolygon loop; loop.addRing(&ring);

OGRPoint middle; middle.setX(0.5); middle.setY(0.5);

std::cout << "" << std::endl; std::cout << "OGRGeometryFactory::haveGEOS(): " <<OGRGeometryFactory::haveGEOS() << std::endl; std::cout << "middle.Contains(&loop): " << middle.Contains(&loop) << std::endl; std::cout << "middle.Within(&loop): " << middle.Within(&loop) << std::endl; std::cout << "loop.Contains(&middle): " << loop.Contains(&middle) << std::endl; std::cout << "loop.Within(&middle): " << loop.Within(&middle) << std::endl;

Results: OGRGeometryFactory::haveGEOS(): 1 middle.Contains(&loop): 0 middle.Within(&loop): 1 loop.Contains(&middle): 1 loop.Within(&middle): 0

[Mateusz Łoskot]

Test presenting difference between actual/target geometry in Withing/Contains and other OGC predicates

[Mateusz Łoskot]

Fixed in trunk (r13128).