PostGIS Distance lookups use ST_Distance_Sphere() and not ST_Distance()

[Bibhas C Debnath]

Currently ​the doc says that PostGIS uses ST_Distance() for distance lookups like distance_gte etc. But actually ST_Distance_Sphere() is used. We need to fix that on the doc.

The doc also says in the beginning -

... an optional third element, 'spheroid', may be included to tell GeoDjango to use the more accurate spheroid distance calculation functions on fields with a geodetic coordinate system (e.g., ST_Distance_Spheroid would be used instead of ST_Distance_Sphere).

But then ST_Distance_Sphere is not mentioned anywhere else.

Here is what currently is happening -

current_localities = Locality.objects.filter(centroid__distance_lte=(pnt, 1000))

results in -

(0.005) SELECT "map_locality"."id", "map_locality"."name", "map_locality"."slug", "map_locality"."centroid", "map_locality"."radius" FROM "map_locality" WHERE ST_Distance_Sphere("map_locality"."centroid", ST_GeomFromEWKB('\x0101000020e6100000865ad3bce3685340e9b7af03e7ec2940'::bytea)) <= 1000 LIMIT 21; args=(<django.contrib.gis.db.backends.postgis.adapter.PostGISAdapter object at 0x7fdcc9d320d0>, 1000)

Attaching a patch with the issue. I can send a PR.

[Bibhas C Debnath]

patch to rename st_distance to st_distance_sphere

[Claude Paroz]

You are right in that the documentation is not up-to-date. However, it's a bit more complicated than that. The real function used depends on the type of the geometry field in the database. You can see the logic here: ​https://github.com/django/django/blob/master/django/contrib/gis/db/backends/postgis/operations.py#L39

If the field is geodetic (latitude/longitude), ST_Distance_Sphere is used by default (with spheroid as an option). If the field has projected coordinates, ST_Distance is used by default.

[Bibhas C Debnath]

Replying to claudep:

If the field is geodetic (latitude/longitude), ST_Distance_Sphere is used by default (with spheroid as an option). If the field has projected coordinates, ST_Distance is used by default.

By geodetic do you mean a Point type geometry field using SRID 4326? In my example above, centroid is of type geometry(Point,4326).

Just trying to get a clear idea about it.

[Claude Paroz]

Yes, 4326 is geodetic in the sense that coordinates (latitude/longitude) are measured in angles based on an ellispoid representation of the earth. On the other hand, projected systems are measured in meters or miles based on a projected plane of the earth (generally only accurate on limited areas).

[Bibhas C Debnath]

So maybe we can say something like -

PostGIS: ST_Distance_Sphere(poly, geom) <= 5 when SRID 4326 is used
PostGIS: ST_Distance(poly, geom) <= 5 when any other projected projected coordinates are used

in 2 different rows. Or use a single row to say both of them.

[Claude Paroz]

What about that ?
​https://github.com/django/django/pull/5418

[Claude Paroz <claude@…>]

In 617b1a2:

Fixed #25498 -- Documented ST_Distance/ST_Distance_Sphere difference

Thanks Bibhas Debnath for the report and Tim Graham for the review.

[Claude Paroz <claude@…>]

In 66319cc5:

[1.9.x] Fixed #25498 -- Documented ST_Distance/ST_Distance_Sphere difference

Thanks Bibhas Debnath for the report and Tim Graham for the review.
Backport of 617b1a21f from master.