[QGIS-Developer] Unclear wording for QgsDistanceArea

[Johannes Kröger (WhereGroup)]

I would be able to improve the docs during the next two days if someone 
has some answers on these questions :)

Cheers, Hannes

Am 28.09.22 um 14:42 schrieb Johannes Kröger (WhereGroup) via 
QGIS-Developer:
> 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
>
>
> _______________________________________________
> QGIS-Developer mailing list
> QGIS-Developer at lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer

-- 
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/20221005/3b47f733/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/20221005/3b47f733/attachment.sig>