Handling Distance-Units in the parsers

[hebersgit]

For us, the units for size-specifications such as line-widths or font-sizes are important in the process of converting QML to other formats (focus on SLD). Therefore, I plan to submit two larger pull requests that correctly take these into account for QML and SLD. Until now, this has not been implemented at all or only in isolated cases. Before doing so, I would of course like to hear the community's opinion on this!

Interpretation of “DistanceUnit”

In style.ts, enum DistanceUnit is defined and can take the values px and m. Some properties that deal with size also have a size-unit-property (e.g., strokeWidthUnit). This seems to be well modeled to me.
Open question: Does px mean that the size refers to a layout-size (fixed output size on the screen, e.g., always 5 pixels), whereas m defines a ground-unit (size that scales when zooming, e.g., covering a width of 500m on the earth's surface)?

If this assessment is correct, it would have the following consequences:

• In QML, an entry line_width_unit=RenderMetersInMapUnits (QGIS: Unit=Meters on Earth) is mapped to DistanceUnit = 'm'.
• All other units are mapped to px, whereby the value may need to be converted (more on this below).
• In SLD styles, there is the uom -attribute on the symbolizers. A DistanceUnit = 'm' would be mapped to uom="http://www.opengeospatial.org/se/units/metre" when writing; when reading, such an attribute leads to DistanceUnit = 'm' being set.

Mapbox only offers pixel sizes. Writing DistanceUnit = 'm' could only be achieved through tricks.

Conversion of units

The DistanceUnit only allows the above-mentioned values “m” and “px”. In my opinion, this means that values in other units (e.g., “pt,” “mm,” “inch,” ‘cm’) must be converted to pixels and the DistanceUnit must be set to 'px' (or omitted if this is the default value according to the documentation).
Open question: How should the units be converted? The conversion from pixels to mm normally depends on the resolution of the output device. This would be completely impractical for our purposes. W3.org always defines a pixel in terms of 96 DPI (W3C Length Units ), which results in 1 inch = 96 pixels = 25.4 mm = 72 pt. Unfortunately, to my knowledge, there is no more specific conversion for the GIS sector, so this should be used.

This would be a significant change, especially with regard to the QML parser, because size specifications often come into play in QML. There are tests that I believe are incorrect.
Example: “can read a QML FillSymbolizer with a PointPatternFill”: polygon_point_pattern_fill.qml contains

<Option name="outline_width" type="QString" value="0.2"/>
<Option name="outline_width_map_unit_scale" type="QString" value="3x:0,0,0,0,0,0"/>
<Option name="outline_width_unit" type="QString" value="MM"/>

which means that the symbol has an outline width of 0.2 mm. Currently, this is simply transferred unchanged. Together with the note in the documentation that the default unit is pixels, this results in 2 pixels. However, the correct value would be (according to the conversion suggested above) 0.2 mm * 3.78 (pixels/mm) = 3.756 px. Such tests should be adapted.

I am excited to hear your thoughts on this topic!

[jahow]

Hi, thank you for the interesting write-up!

We're currently working (or trying to work) on supporting OpenLayers flat style conversion.

For now we are excluding support for units but it could definitely be done using flat style expressions (and the 96 DPI value you mention). Do you see support for this in the OpenLayers parser as interesting? Would you be interested in helping?

[hebersgit]

Hello @jahow , thank you for your contribution! I am pleased to hear that this feature is also important to others. For us, the conversion QML->SLD and later QML->Mapbox or SLD->Mapbox is of utmost importance at the moment. The effort involved is considerable, so I will focus on this process first.
In my planned pull request, the conversion between metric units (pt, mm, inch, 96-dpi-pixel) is located in the QGIS parser. Since it is universal, it would be better placed in Geostyler/Util. Unfortunately, this makes the pull request very complicated, as in this case I would first have to wait for the code to be transferred to Geostyler before I could make the pull request for the QGIS parser. Perhaps this transfer can be done later.

[T-Lorent]

Hi, I was just asking on the discord server if there was a reason why the sld parser wasn't currently handling the units. The timing is perfect ! 😄

On my side, it is quite the same: basically, we're aiming at being able to display QGIS-styled maps in the browser, and so the real-world units are important for us too. I'm new to geostyler, and more a programmer than a GIS expert, but here is my answers to your open question @hebersgit:

First open question
I agree with your interpretation of px and m: pixels define a fixed output size on the screen, while m defines a real-world unit. This is how other libraries like Deck.gl define it too (Deck.gl doc).

Second open question
I'm not sure that converting "pt", "mm", "inch", and "cm" at read is the best way to go, as it would result in a loss of information. Maybe a better way would be to add those units to the DistanceUnit enum and let the different parsers do the conversion at write? But this is more work I think

[hebersgit]

Hello @T-Lorent , I would also prefer to allow more units for DistanceUnit enum for maintaining the input-unit as long as possible. The problem is, that changes at the base-classes like style.ts are complicated because you have to wait to until the first Pull-request at the base-classes is merged into master before you can continue with the functional Pull-request in the parser.

[jahow]

@T-Lorent I would advise against adding more units for the following reasons:

• more units means more complexity and code to maintain downstream; and as @hebersgit points out any model change has many consequences down the line
• allowing px and m essentially allows choosing between screen-space and world-space dimension, which are the only two options
• pt is an equivalent to px
• mm, cm etc. are simply 10-multiples of m so extremely easy to convert if encountered
• in, ft etc. can indeed result in precision losses, but I think this is acceptable as they are not international standards; besides, keep in mind that all these conversions might rely on an arbitrary DPI value so the precision in that case is not an exact concept.

[jansule]

This is definitely something that we want to support, so thanks for bringing this up @hebersgit!

I would also favor fewer supported units in geostyler-style, since this should facilitate maintenance in the long run.

The problem is, that changes at the base-classes like style.ts are complicated because you have to wait to until the first Pull-request at the base-classes is merged into master before you can continue with the functional Pull-request in the parser.

You can use npm link to circumvent this problem. Through this, you can already work on subsequent changes, even though the PR of a dependency was not yet merged. This is how we usually do it, when it comes to changes that span over multiple geostyler repos.

[T-Lorent]

Alright, I trust your experience guys. Thanks for your explanations, it's interesting to see the process of decision ;)