C-API: Add relative offset change

[CarawaySeed42]

Since the C-API reads the channel offset XYZ beginning with version 2.0.1, there should be an API function that lets the caller change the offsets relatively.
This means, the CRG does NOT move and is NOT shifted but the offsets are changed and the difference is added to xbeg plus data and xend, ybeg plus data and yend and zbeg and zend.

Why is this helpful:
If you want to simulate using multiple CRGs or combine them with OpenDRIVE they might not share the same offset.
After referencing all CRGs to the same offset they all share the same "local" coordinate system and evaluation becomes trivial. Reminder, evaluate xy2z, uv2xy, ... all need and return "local" coordinates.

Very simple example using channel X:

• CRG 1 xoff = 100, xbeg = 0, xend = 100
• CRG 2 xoff = 200, xbeg = 0, xend = 100

These 100 units long CRGs connect at "global" X coordinate 200 where CRG 2 begins after CRG 1 ends.
A user evaluates using CRG 1's local system and evaluates from x 0 to 100.
At x = 100.001 evaluation continues on CRG 2 because CRG 1 ended. So the user does that but whoops, now you evaluate behind the end of CRG 2 instead of at the start.
The user would need to factor in, that CRG 2 has a different offset.

With a function letting the user set the same offset for all CRGs, this is solved.
Alternatively, if the user does not want the channel data to be manipulated, there should be an additional function that lets the user transform xyz values from one CRG to another.

Summary: Make it easier for users to evaluate with multiple CRG files.
-> Create two functions: Change offset relatively, transform coordinates to another CRG

[jorauh]

I don't yet understand the background to the question. If both CRG files are described in the same rectangular xy coordinate system, you don't need offsets or other aids to achieve consistent behavior at the transition from file 1 to file 2.

[CarawaySeed42]

When creating CRG roads from survey data they usually don't have the same xyz coordinate system and not the same origin.
I try to explain it in part visually.And I will change the example a bit.

Imagine you have a circular road. For this road you got a (OpenDRIVE) map and a CRG. Both are from different suppliers. Both CRG road and map have a specified offset because both suppliers can choose whatever they seem fit. Why they have this offset is explained later.

The offset basically determines the origin of the coordinate system of map and CRG road. Again, offsets do not go into the evaluation of coordinates or heights in the CRG API.

The offset of the map was set in the middle of the circular road. The CRGs offset was set at the road start in the south.
Now a user picks a query point where they want to know what height the road is at. This value is
x=500, y=0 (upper arrow in picture)
in the maps coordinate system. Offsets are ignored like the CRG API does.

Now they plug this number into the CRG APIs evaluation function xy2z. But they don't get the height at the coordinate they wanted.
In the CRGs system x=500, y=0 is not to the right of the middle of the circle but to the right at the south end (lower arrow)
Why does that happen? Because the evaluation does not account for the offset and thus, map and CRG don't share the same coordinate system.
-> When two CRGs or maps or whatever do not have the same offset, they never share the same coordinate system where the evaluation happens

But why have the offsets in the first place?
In the example case, both map and CRG could have been produced with offset zero, no problem.
But when you work with real world survey data, "world coordinates" are used e.g. projected coordinates in UTM.
These coordinates are huge and in the hundred thousands and millions.

Simulation or rendering software usually use single precision floating point coordinates. UTM coordinates are way to big to represent them. If you plugged UTM coordinates of CRG or map into these system, everything would break.
That is why you need an offset that is somewhere in the range of the CRG or map coordinates and that is why it is good that the offset is not part of the evaluation functions. This way, you can evaluate and simulate with smaller and reduced coordinates.
If you write the offset into the map/CRG header or just subtract them, it still leads to the same problem. Offsets need to be equal.

Then why not produce map and CRG with the same offset in mind? Well, that is possible for one project done by one supplier.
But if you have multiple suppliers, how would they know which offset the other supplier used?
And even one supplier might just set the CRG offsets on a per road basis, since it is not the suppliers responsibility that the simulation handles the coordinates properly/switch properly between coordinate systems. All the information is already there, the softwares just have to use it.

-> With the proposed changes, users of the API have an easy way to remedy the above stated issue and no CRG road or map supplier has to care about, what offsets they choose.
-> Workflow for this example: Get map offset -> reference map offset in CRG -> Both are now in the same evaluation system

I hope that made it more clear. It is hard to explain but we have encountered this issue a few times with customers.
Note: Same goes for the z-offset. If they are not shared, you get jumps between roads.