The instructions contain important information about thins like a ferry crossing or using private roads. This data is stored in the instruction annotation. We already translate this data, which makes it easy for api consumers to use it. However, if you want to use your own translations or maybe show a ferry symbol next to ferry crossing, you need to check the translated string.
I would like to propose that we pass some easily readable key in addition to the translated string (or even instead but that would be a breaking change). WDYT?
We already have a similar approach for instructions via sign so it could make sense to introduce e.g. an array annotation_signs? (Currently the Java object is limited to one annotation but IMO it shouldn’t as one instruction can contain e.g. toll and ferry or border crossing and toll etc?)
While we are at it: maybe we can remove the getExtraInfoJSON in Java and convert the used data into Java variables? (double header, only FinishInstruction: double last_header, only RoundaboutInstruction: int exit_number, boolean exited, double turn_angle)
Yes annotation_signs sounds good to me. Not sure if we should also code it into integers like we do for sign or should we just add readable string keys?
Sure, you mean to extract these variables into each of the sub-classes? That’s certainly something we could do .
Yes annotation_signs sounds good to me. Not sure if we should also code it into integers like we do for sign or should we just add readable string keys?
Would a number be more consistent with the instruction sign (?)
Sure, you mean to extract these variables into each of the sub-classes? That’s certainly something we could do .
Yes that would make it more consistent. But I am not sure if it’s worth the overhead, as this makes handling for clients and debugging more complicated? For example for PathDetails we also use a string.
Using the path details is already possible. But then it might be cleaner to remove the annotations from the instructions and ask clients to use the PathDetails instead?
I think this should be possible. But how do you want to visualize this?
If we try to match the path details to the instructions and to show content from the path details in the instructions, then I think we should rather improve the instructions, also since we generate forced instructions if the annotations change on the server.
If we want to show this information independently from the instructions, using PathDetails would be better.
Including this in the instructions should be rather simple? (path details => check if first index of e.g. ferry is in instruction interval => add text to instruction)
We could also show this globally only and later decide to include it in the instructions or similar, but this client side stuff should not influence our decision on the server-side. I find it cleaner to have instructions separated from path details and to have these two concepts only.
For ferries this would probably work quite well. For other things like bike pushing sections probably not. It might be that in one instructions we have several changes of bike pushing sections.
The same goes for fords. There are roads that have multiple fords but no turns.
Right now for the instructions we create a new instruction on the server side if the annotation changes.
If would prefer to do this with PathDetails as well .
Let’s assume these instructions: start [0, 10], turn right [10, 20] and finish [20, 20].
And if there is a ford at [8, 9] and another one at [12, 13] you could display them (e.g. as a subinstruction for “start” and one for “turn right” or globally) and you know when to announce them. Or when would there be a problem?
What is a subinstruction? Do you mean like adding a string or marker to the existing instruction? Or do you mean splitting the instruction in two instructions on the client? Splitting instructions can be a bit tricky because you need to recalculate the distance and ETA. Just adding a string/marker to an existing instruction is easy.
My thought was that adding a string/marker might be problematic if we have multiple “annotation” per instruction, if you have a pushing section from 3-7. Right now, This would result in instructions:
start [0, 3], get off bike [3, 7], get on bike [7, 19], turn right [10, 20] and finish [20, 20].
or if you have a ford and a ferry, like:
start [0, 3], ford [3, 4], continue [4, 7], ferry [7, 8], continue [8, 10], turn right [10, 20] and finish [20, 20].
But probably that’s not such a big issue, as “get on bike” and “get off bike” could be easily merged to “contains a section where you have to get off your bike” or something like this.
If we think it’s ok that clients create their own instructions for these cases using PathDetails or if we think that it’s not necessary to have instructions for these cases, then there is no problem and we should remove the annotations from the instructions. Then every client is responsible to handle these cases in a way that works well for the application.
Hmmh, probably I do not understand your use case properly. I see two use cases:
one is to just display the instructions of a route like for GraphHopper Maps and then you can display all instructions and insert more information as you like on the client side.
if you use it for navigation then you know when to announce that a ford or ferry is coming - you can do this separate from the instructions and IMO there is no need to recalculate distances or times or split instructions although you can still do this on the client side.
If we think it’s ok that clients create their own instructions for these cases using PathDetails
We announce private or ferry roads or “get off the bike” but why these and not some of the other details like a bridge or a tunnel? (a tunnel warning could make sense for a truck driver or announcement of some max_speed changes or similar).
Your change request triggered the thinking in me that the instruction annotations are no longer necessary since we have the path details, that are more powerful and better customizable already and we do not need a third thing. (We could even think about moving the instructions into one or more path details )
I understand that this might make things more complicated on the client side but IMO not too much.
This is my use case and I am perfectly fine with using PathDetails removing annotations. The reason I started this discussion was that I wanted to show an info to a route like “This route contains ferries”. When looking at the code, I saw that we use translated strings, which I found not ideal for my use case.
but that would be a breaking change). WDYT?
.
)