heremaps
What is the meaning of the 3rd dim flag states?
In your documentation, you purely list the possible states for this flag but make no distinction on what it means, the units, and the difference in handling. Digging through the code, I saw that you basically take this enumeration and use it as a logical value to determine whether there will be a third component on the coordinates. So if it's any state other than 0 it's all the same. I understand you might want placeholder states for later, but at least provide documentation on your intent for the ones you've actually assigned already.
You are correct. I will check with the different API teams using the encoding if they actually have a shared understanding of the units, or if this is up to the service/API/data format using the encoding to define.
It looks like there are various usecases which require different definitions of the 3rd dimension e.g. there are various choices for how to represent elevation, amongst them:
- meters delta to WGS84
- meters delta to EMG96
This means that the users of the flexible-polyline format should document the meaning of what they can return in their API, but we should most likely not limit it in the format.
That distinction sounds reasonable and the users of the format should indeed specify what reference frame they refer to. I believe that the information you just provided should be a part of your documentation so that users know their responsibility to mention the reference frame and also what is expected of them when it comes to units for using these functions.
That makes sense @Alegom . Do you want to open a pull request for that, or do you want to wait for somebody else to do so?
As a developer myself, I think it's good for developers to get the habit of documenting their code so I'll leave this to the creators as a good chance to practice. ;)