[QGIS-Developer] Unclear wording for QgsDistanceArea

[Johannes Kröger (WhereGroup)]

Hi!

I am in QGIS 3.22 in an empty project set to EPSG:3035.

Considering the following Python code run via the script editor:

 >>> point_a = QgsPointXY(7.824, 48)
 >>> point_b = QgsPointXY(7.829, 47.98)
 >>> da = QgsDistanceArea()
 >>> print(da.willUseEllipsoid())
False
 >>> print(da.ellipsoid())
NONE
 >>> measure = da.measureLine(point_a, point_b)
 >>> print(measure)
0.02061552812809131
 >>> meters = da.convertLengthMeasurement(measure, 
QgsUnitTypes.DistanceMeters)
 >>> print(meters)
2294.910093653533

I was wondering how it was able to turn the seemingly unit-less 
0.0206... into a distance in meters and checked the docs. The 
documentation 
https://qgis.org/pyqgis/master/core/QgsDistanceArea.html#qgis.core.QgsDistanceArea.lengthUnits 
says:

 > Usually, the measurements returned by QgsDistanceArea are in meters. 
If no valid ellipsoid is set, then the units may not be meters. The 
units can be retrieved by calling lengthUnits() and areaUnits().

As it said "usually" and I didn't do anything special on purpose, I 
expected this to return a distance measurement in meters but instead I 
apparently got a distance in degrees (well, some cartesian measure 
between my points as a float) which I could *convert* to meters. I have 
no valid ellipsoid set so as the docs say, this could have happened 
("may not be meters").

Checking the .lengthUnits() as suggested confirms that my 
QgsDistanceArea somehow decided to consider my coordinate values, and 
thus the measurement, to be in degrees:

 >>> da.lengthUnits() == QgsUnitTypes.DistanceDegrees
True

But why? I find the language very unclear and confusing there.
Do "usually" and "may" mean that this is undefined, random behaviour 
unless one explicitly sets an ellipsoid?
If so, should the docs strongly suggest to always use an ellipsoid so 
that there is no "may"?
Do those words express the doc writer's vision of how the class what 
usually be used?
If so, should the docs suggest a specific setup of the class?
Why did it consider my point coordinates to be in degrees?
How did it convert the degrees to meters if it supposedly does not use 
an ellipsoid?
8)

Cheers, Hannes

-- 
Johannes Kröger / GIS-Entwickler/-Berater

---------------------------------------------
Schon gewusst?
In unserem Blog geben wir Tipps & Tricks zu Open-Source-GIS-Software
und berichten aus unserem Experten-Alltag:
https://wheregroup.com/blog/
---------------------------------------------

WhereGroup GmbH
Grevenweg 89
20537 Hamburg
Germany

Tel: +49 (0)228 / 90 90 38 - 36
Fax: +49 (0)228 / 90 90 38 - 11

johannes.kroeger at wheregroup.com
www.wheregroup.com
Geschäftsführer:
Olaf Knopp, Peter Stamm
Amtsgericht Bonn, HRB 9885
-------------------------------

-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_0x840A4B843789797F.asc
Type: application/pgp-keys
Size: 2472 bytes
Desc: OpenPGP public key
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20220928/95e48606/attachment.key>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_signature
Type: application/pgp-signature
Size: 665 bytes
Desc: OpenPGP digital signature
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20220928/95e48606/attachment.sig>