at.ac.ait.ariadne.routeformat.instruction

Class RoadInstruction

java.lang.Object

at.ac.ait.ariadne.routeformat.instruction.Instruction<RoadInstruction>

at.ac.ait.ariadne.routeformat.instruction.RoadInstruction

All Implemented Interfaces:

Validatable

public class RoadInstruction
extends Instruction<RoadInstruction>

A RoadInstruction contains episodes with classic-style turn navigations for street-based modes of transport such as walking, cycling and driving (keep straight, turn left/right, make a u-turn).

In its minimal form it consists of a position, a getSubType() and at least one of getOntoStreetName() and getOntoFormOfWay().

Exemplary EBNF of how this instruction can be transformed into human-readable text and what's mandatory / optional. Elements ending with STRING are terminal (not defined any further).

UNTIL_LANDMARK_STRING must be retrieved from the next Instruction, it can be a classic landmark or also the type of the next instruction, e.g. roundabout.

 
 ROAD_INSTRUCTION = ROUTE_START | ROUTE_START_UNMENTIONED | ROUTE_END | STRAIGHT | TURN | U_TURN | SWITCH_SIDE_OF_ROAD;
 
 ROUTE_START = "Start", [LANDMARK_PART], "on", NAME_TYPE, [HEADING], [CONTINUE];
 ROUTE_START_UNMENTIONED = [LANDMARK_PART], "on", NAME_TYPE, [HEADING], [CONTINUE];
 STRAIGHT = [LANDMARK_PART], "Go straight", [CROSSING_PART], "on", NAME_TYPE, [HEADING], [CONTINUE];
 TURN = [LANDMARK_PART], "Turn", ["slight"], DIRECTION, [CROSSING_PART], "on", NAME_TYPE, [HEADING], [CONTINUE];
 U_TURN = [LANDMARK_PART], "Make a u-turn", [CROSSING_PART], "on", NAME_TYPE, [HEADING], [CONTINUE];
 SWITCH_SIDE_OF_ROAD = [LANDMARK_PART], "Switch to the", DIRECTION, "side of", NAME_TYPE, [CROSSING_PART], [HEADING], [CONTINUE];
 ROUTE_END = "You reached your destination", [LANDMARK_PART], "on", NAME_TYPE;
 
 NAME_TYPE = [STREET_NAME_STRING], [FORM_OF_WAY_STRING], [onto the bridge], [into the TUNNEL_STRING];
 CROSSING_PART = "over the intersection" | "at the traffic light" | ...
 HEADING = "heading", COMPASS_STRING;

 CONTINUE = "and continue", [ROAD_SIDE], ["for", UNIT], [CONFIRMATION_LANDMARK_PART], [UNTIL]; (* at least one of the options *)
 ROAD_SIDE = "on the", "left" | "right", "side of the road;
 UNIT = [DISTANCE_STRING], [TIME_STRING]; (* at least one of the two *)
 UNTIL = "until", [INTERSECTING_ROAD_STRING], [UNTIL_LANDMARK_PART]; 
 
 LANDMARK_PART = PREPOSITION, LANDMARK_STRING;
 CONFIRMATION_LANDMARK_PART = CONFIRMATION_PREPOSITION, CONFIRMATION_LANDMARK_STRING;
 UNTIL_LANDMARK_PART = PREPOSITION, UNTIL_LANDMARK_STRING;
 
 PREPOSITION = "before" | "at" | "after";
 CONFIRMATION_PREPOSITION = "towards" | "through" | "along" | "past";
 
 DIRECTION = "left" | "right";
 
 

Author:

AIT Austrian Institute of Technology GmbH

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RoadInstruction.SubType

Constructor Summary

Constructors

Constructor and Description
RoadInstruction()

Method Summary

Modifier and Type	Method and Description
static RoadInstruction	createMinimalOnRoute(GeoJSONCoordinate position, Constants.TurnDirection turnDirection, Optional<String> ontoStreetName, Optional<Constants.FormOfWay> ontoFormOfWay) either street name or form of way must be present
static RoadInstruction	createMinimalRouteEnd(GeoJSONCoordinate position, Optional<String> onStreetName, Optional<Constants.FormOfWay> onFormOfWay) either street name or form of way (of the destination) must be present
static RoadInstruction	createMinimalRouteStart(GeoJSONCoordinate position, Optional<String> ontoStreetName, Optional<Constants.FormOfWay> ontoFormOfWay) either street name or form of way must be present
boolean	equals(Object obj)
Optional<Constants.CompassDirection>	getCompassDirection()
Optional<Landmark>	getConfirmationLandmark()
Optional<Integer>	getContinueMeters()
Optional<Integer>	getContinueSeconds()
Optional<String>	getContinueUntilIntersectingStreetName()
Optional<Constants.RoadCrossing>	getCrossing()
Optional<Boolean>	getEnterBridge()
Optional<Constants.Tunnel>	getEnterTunnel()
Optional<Landmark>	getLandmark()
Optional<Constants.GeneralizedModeOfTransportType>	getModeOfTransport()
Optional<Constants.FormOfWay>	getOntoFormOfWay()
Optional<Boolean>	getOntoRightSideOfRoad() Defines the side of the road where the route continues.
Optional<String>	getOntoStreetName()
Optional<Boolean>	getRoadChange()
RoadInstruction.SubType	getSubType()
Optional<Constants.TurnDirection>	getTurnDirection()
int	hashCode()
RoadInstruction	setCompassDirection(Constants.CompassDirection compassDirection)
RoadInstruction	setConfirmationLandmark(Landmark confirmationLandmark)
RoadInstruction	setContinueMeters(Integer continueMeters)
RoadInstruction	setContinueSeconds(Integer continueSeconds)
RoadInstruction	setContinueUntilIntersectingStreetName(String continueUntilIntersectingStreetName)
RoadInstruction	setCrossing(Constants.RoadCrossing crossing)
RoadInstruction	setEnterBridge(Boolean enterBridge)
RoadInstruction	setEnterTunnel(Constants.Tunnel enterTunnel)
RoadInstruction	setLandmark(Landmark landmark)
RoadInstruction	setModeOfTransport(Constants.GeneralizedModeOfTransportType modeOfTransport)
RoadInstruction	setOntoFormOfWay(Constants.FormOfWay ontoFormOfWay)
RoadInstruction	setOntoRightSideOfRoad(Boolean ontoRightSideOfRoad)
RoadInstruction	setOntoStreetName(String ontoStreetName)
RoadInstruction	setRoadChange(Boolean roadChange)
RoadInstruction	setSubType(RoadInstruction.SubType subType)
RoadInstruction	setTurnDirection(Constants.TurnDirection turnDirection)
String	toString()
void	validate() Checks if the instance is in a valid / useful state.

Methods inherited from class at.ac.ait.ariadne.routeformat.instruction.Instruction

getAdditionalInfo, getConfirmationTriggerPosition, getPosition, getPreviewTriggerPosition, getText, setAdditionalInfo, setConfirmationTriggerPosition, setConfirmationTriggerPosition, setPosition, setPosition, setPreviewTriggerPosition, setPreviewTriggerPosition, setText

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RoadInstruction

public RoadInstruction()

Method Detail

getSubType

public RoadInstruction.SubType getSubType()

getModeOfTransport

public Optional<Constants.GeneralizedModeOfTransportType> getModeOfTransport()

Returns:

the mode of transport for the turn (walk left, cycle left,..)

getTurnDirection

public Optional<Constants.TurnDirection> getTurnDirection()

Returns:

the turn direction relative to the direction until this point

getCompassDirection

public Optional<Constants.CompassDirection> getCompassDirection()

Returns:

the heading after this point

getRoadChange

public Optional<Boolean> getRoadChange()

Returns:

true if the road name or type has changed

getOntoStreetName

public Optional<String> getOntoStreetName()

getOntoFormOfWay

public Optional<Constants.FormOfWay> getOntoFormOfWay()

getEnterBridge

public Optional<Boolean> getEnterBridge()

Returns:

information if this instruction marks the entrance to a bridge

getEnterTunnel

public Optional<Constants.Tunnel> getEnterTunnel()

Returns:

information if this instruction marks the entrance to a tunnal (and which kind of tunnel)

getOntoRightSideOfRoad

public Optional<Boolean> getOntoRightSideOfRoad()

Defines the side of the road where the route continues. This is mostly relevant for pedestrians and maybe also for cyclists (e.g. when bidirectional cycle paths run along a road on both sides). For other modes of transport an empty Optional shall be returned.

Returns:

true for the right side, false for the left side of the road (in moving direction), empty if unknown or not relevant

getCrossing

public Optional<Constants.RoadCrossing> getCrossing()

Returns:

a Constants.RoadCrossing in case the instruction starts with a road crossing

getContinueMeters

public Optional<Integer> getContinueMeters()

getContinueSeconds

public Optional<Integer> getContinueSeconds()

getContinueUntilIntersectingStreetName

public Optional<String> getContinueUntilIntersectingStreetName()

Returns:

the name of an intersecting road at the end of the current instruction, i.e. the place where the next instruction is

getLandmark

public Optional<Landmark> getLandmark()

Returns:

the landmark at begin of the instruction, i.e. at the turn, or at the begin (for RoadInstruction.SubType.ROUTE_START) or at the end (for RoadInstruction.SubType.ROUTE_END) of the route. At the same time this landmark is the continue-landmark for the previous instruction, i.e. the landmark after getContinueMeters().

getConfirmationLandmark

public Optional<Landmark> getConfirmationLandmark()

Returns:

a landmark between this and the next instruction (or a global landmark in the general direction after this instruction) that helps users to stay on track

setSubType

public RoadInstruction setSubType(RoadInstruction.SubType subType)

setModeOfTransport

public RoadInstruction setModeOfTransport(Constants.GeneralizedModeOfTransportType modeOfTransport)

setTurnDirection

public RoadInstruction setTurnDirection(Constants.TurnDirection turnDirection)

setCompassDirection

public RoadInstruction setCompassDirection(Constants.CompassDirection compassDirection)

setRoadChange

public RoadInstruction setRoadChange(Boolean roadChange)

setOntoStreetName

public RoadInstruction setOntoStreetName(String ontoStreetName)

setOntoFormOfWay

public RoadInstruction setOntoFormOfWay(Constants.FormOfWay ontoFormOfWay)

setEnterBridge

public RoadInstruction setEnterBridge(Boolean enterBridge)

setEnterTunnel

public RoadInstruction setEnterTunnel(Constants.Tunnel enterTunnel)

setOntoRightSideOfRoad

public RoadInstruction setOntoRightSideOfRoad(Boolean ontoRightSideOfRoad)

setCrossing

public RoadInstruction setCrossing(Constants.RoadCrossing crossing)

setContinueMeters

public RoadInstruction setContinueMeters(Integer continueMeters)

setContinueSeconds

public RoadInstruction setContinueSeconds(Integer continueSeconds)

setContinueUntilIntersectingStreetName

public RoadInstruction setContinueUntilIntersectingStreetName(String continueUntilIntersectingStreetName)

setLandmark

public RoadInstruction setLandmark(Landmark landmark)

Parameters:

landmark - the landmark at the start point, end point, or decision point

setConfirmationLandmark

public RoadInstruction setConfirmationLandmark(Landmark confirmationLandmark)

createMinimalRouteStart

public static RoadInstruction createMinimalRouteStart(GeoJSONCoordinate position,
                                                      Optional<String> ontoStreetName,
                                                      Optional<Constants.FormOfWay> ontoFormOfWay)

either street name or form of way must be present

createMinimalOnRoute

public static RoadInstruction createMinimalOnRoute(GeoJSONCoordinate position,
                                                   Constants.TurnDirection turnDirection,
                                                   Optional<String> ontoStreetName,
                                                   Optional<Constants.FormOfWay> ontoFormOfWay)

either street name or form of way must be present

createMinimalRouteEnd

public static RoadInstruction createMinimalRouteEnd(GeoJSONCoordinate position,
                                                    Optional<String> onStreetName,
                                                    Optional<Constants.FormOfWay> onFormOfWay)

either street name or form of way (of the destination) must be present

validate

public void validate()

Description copied from interface: Validatable

Checks if the instance is in a valid / useful state. If this is not the case an IllegalArgumentException including a description of the invalid state is thrown.

Specified by:

validate in interface Validatable

Overrides:

validate in class Instruction<RoadInstruction>

hashCode

public int hashCode()

Overrides:

hashCode in class Instruction<RoadInstruction>

equals

public boolean equals(Object obj)

Overrides:

equals in class Instruction<RoadInstruction>

toString

public String toString()

Overrides:

toString in class Instruction<RoadInstruction>