fix(routing): fixed waytype encoding and addressed further cleanups a…

…fter review

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/CandidateRoute.java

@@ -29,12 +29,12 @@ public class CandidateRoute {
     private final List<String> connectionIds;
 
     /**
-     * The length of this route.
+     * The length in meters of this route.
      */
     private final double length;
 
     /**
-     * The approximated driving time on this route.
+     * The approximated driving time in seconds on this route.
      */
     private final double time;
 
@@ -50,11 +50,25 @@ public class CandidateRoute {
      */
     private final double offsetToTarget;
 
-
+    /**
+     * @param connectionIds the list of connection id this route persists of.
+     * @param length the length in m of this route.
+     * @param time the approximate travel time in seconds of this route.
+     */
     public CandidateRoute(List<String> connectionIds, double length, double time) {
         this(connectionIds, length, time, 0, 0);
     }
 
+    /**
+     *
+     * @param connectionIds the list of connection id this route persists of.
+     * @param length the length in m of this route.
+     * @param time the approximate travel time in seconds of this route.
+     * @param offsetFromSource the distance in meters from the start node of the first connection in the connectionIds list, to
+     *                         the point the source query was issued.
+     * @param offsetToTarget the distance in meters from the point the target query was issued, until the end node of the
+     *                       final connection in the connectionIds list.
+     */
     public CandidateRoute(List<String> connectionIds, double length, double time, double offsetFromSource, double offsetToTarget) {
         this.connectionIds = connectionIds;
         this.length = length;
@@ -63,22 +77,39 @@ public CandidateRoute(List<String> connectionIds, double length, double time, do
         this.offsetToTarget = offsetToTarget;
     }
 
+    /**
+     * @return the list of connection ids forming this route.
+     */
     public List<String> getConnectionIds() {
         return connectionIds;
     }
 
+    /**
+     * @return the length in meters of this route.
+     */
     public double getLength() {
         return length;
     }
 
+    /**
+     * @return the approximated driving time in seconds on this route.
+     */
     public double getTime() {
         return time;
     }
 
+    /**
+     * @return the distance in meters from the start node of the first connection in the connectionIds list, to
+     * the point the source query was issued.
+     */
     public double getOffsetFromSource() {
         return offsetFromSource;
     }
 
+    /**
+     * @return the distance in meters from the point the target query was issued, until
+     * the end node of the final connection in the connectionIds list.
+     */
     public double getOffsetToTarget() {
         return offsetToTarget;
     }

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/database/DatabaseRouting.java

@@ -215,7 +215,7 @@ public CandidateRoute approximateCostsForCandidateRoute(CandidateRoute route, St
             length += con.getLength();
             time += con.getLength() / con.getMaxSpeedInMs();
         }
-        return new CandidateRoute(route.getConnectionIds(), length, time, 0, Double.POSITIVE_INFINITY);
+        return new CandidateRoute(route.getConnectionIds(), length, time);
     }
 
     private Edge findClosestEdge(GeoPoint location) {

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/graphhopper/GraphHopperRouting.java

@@ -31,7 +31,7 @@
 import org.eclipse.mosaic.lib.routing.graphhopper.algorithm.RoutingAlgorithmFactory;
 import org.eclipse.mosaic.lib.routing.graphhopper.util.DatabaseGraphLoader;
 import org.eclipse.mosaic.lib.routing.graphhopper.util.GraphhopperToDatabaseMapper;
-import org.eclipse.mosaic.lib.routing.graphhopper.util.TurnCostsProvider;
+import org.eclipse.mosaic.lib.routing.graphhopper.util.OptionalTurnCostProvider;
 import org.eclipse.mosaic.lib.routing.graphhopper.util.VehicleEncoding;
 import org.eclipse.mosaic.lib.routing.graphhopper.util.VehicleEncodingManager;
 
@@ -262,7 +262,7 @@ && checkForDuplicate(route, duplicateSet)
 
     private Weighting createWeighting(Profile profile, RoutingCostFunction costFunction, boolean withTurnCosts) {
         final VehicleEncoding vehicleEncoding = encoding.getVehicleEncoding(profile.getVehicle());
-        final TurnCostsProvider turnCostProvider = new TurnCostsProvider(vehicleEncoding, graph.getTurnCostStorage());
+        final OptionalTurnCostProvider turnCostProvider = new OptionalTurnCostProvider(vehicleEncoding, graph.getTurnCostStorage());
         if (!withTurnCosts) {
             turnCostProvider.disableTurnCosts();
         }

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/graphhopper/algorithm/BellmanFordRouting.java

@@ -62,8 +62,7 @@ public BellmanFordRouting(Graph graph, Weighting weighting, PMap hints) {
     public Path calcPath(int from, int to) {
         edgeEntries.clear();
         nodeEntries.clear();
-
-
+
         determineAllEdges();
         createStartCondition(from);
 

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/graphhopper/util/TurnCostsProvider.java → lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/graphhopper/util/OptionalTurnCostProvider.java

@@ -21,15 +21,15 @@
 import com.graphhopper.storage.TurnCostStorage;
 import com.graphhopper.util.EdgeIterator;
 
-public class TurnCostsProvider implements TurnCostProvider {
+public class OptionalTurnCostProvider implements TurnCostProvider {
 
     private final BooleanEncodedValue turnRestrictionsEnc;
     private final DecimalEncodedValue turnCostsEnc;
     private final TurnCostStorage turnCostStorage;
 
     private boolean turnCostsEnabled = true;
 
-    public TurnCostsProvider(VehicleEncoding encoding, TurnCostStorage turnCostStorage) {
+    public OptionalTurnCostProvider(VehicleEncoding encoding, TurnCostStorage turnCostStorage) {
         if (turnCostStorage == null) {
             throw new IllegalArgumentException("No storage set to calculate turn weight");
         }
@@ -38,6 +38,9 @@ public TurnCostsProvider(VehicleEncoding encoding, TurnCostStorage turnCostStora
         this.turnCostStorage = turnCostStorage;
     }
 
+    /**
+     * Disables consideration of turn costs. Only turn restrictions are checked.
+     */
     public TurnCostProvider disableTurnCosts() {
         this.turnCostsEnabled = false;
         return this;

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/graphhopper/util/VehicleEncoding.java

@@ -25,6 +25,16 @@
 import com.graphhopper.routing.util.VehicleEncodedValues;
 import com.graphhopper.util.PMap;
 
+/**
+ * Collection of all {@link com.graphhopper.routing.ev.EncodedValue} implementations
+ * required for a vehicle to function within the GraphHopper context. This includes:
+ * - "access" - If a vehicle can drive on an edge.<br>
+ * - "speed" - The speed limit for the vehicle on the edge.<br>
+ * - "priority" - Encode how to prioritize a road type to another.<br>
+ * - "subnetwork" - Encode if an edge belongs to a subnetwork<br>
+ * - "turnRestriction" / "turnCost" - encoding of costs for a turn from on edge to another.<br>
+ * These encoders take care of storing and reading properties on edges.
+ */
 public class VehicleEncoding {
 
     private final BooleanEncodedValue accessEnc;

lib/mosaic-routing/src/main/java/org/eclipse/mosaic/lib/routing/graphhopper/util/WayTypeEncoder.java

@@ -25,6 +25,11 @@
 
 import java.util.Set;
 
+/**
+ * Stores additional properties on an edge to describe the way-type of an edge.
+ * It does so by encoding the way-type, and some boolean flags based on this
+ * way-type, within one integer field by using bit-masking.
+ */
 public class WayTypeEncoder extends IntEncodedValueImpl {
 
     public final static String KEY = "waytype";
@@ -54,7 +59,12 @@ public class WayTypeEncoder extends IntEncodedValueImpl {
     private static final int ONE_LANE = 1 << 10;
     private static final int MAIN_ROAD = 1 << 9;
     private static final int CYCLEWAY = 1 << 8;
-    private static final int TYPE_MASK = 0x03FFFFFF;
+
+    /*
+     * Store the type as integer in the first 1 byte (max value = 255)
+     * The rest of the integer bits is used to store the property flags, e.g. HIGHWAY, RESIDENTIAL.
+     */
+    private static final int TYPE_MASK = 0x00FF;
 
     static {
         // autobahn
@@ -79,6 +89,8 @@ public class WayTypeEncoder extends IntEncodedValueImpl {
         wayTypeIntMap.put("service", 27);
         wayTypeIntMap.put("road", 26);
         wayTypeIntMap.put("track", 25);
+        // any other roads
+        wayTypeIntMap.put("cycleway", 10);
     }
 
     private WayTypeEncoder() {

lib/mosaic-routing/src/test/java/org/eclipse/mosaic/lib/routing/CharlottenburgRoutingTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020 Fraunhofer FOKUS and others. All rights reserved.
+ * Copyright (c) 2024 Fraunhofer FOKUS and others. All rights reserved.
  *
  * See the NOTICE file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -36,6 +36,9 @@
 import java.io.IOException;
 import java.util.List;
 
+/**
+ * Test routing with a real world map (Charlottenburg extract from BeST scenario).
+ */
 public class CharlottenburgRoutingTest {
 
     @Rule

lib/mosaic-routing/src/test/java/org/eclipse/mosaic/lib/routing/graphhopper/GraphHopperWeightingTest.java

@@ -19,7 +19,7 @@
 
 import org.eclipse.mosaic.lib.routing.RoutingCostFunction;
 import org.eclipse.mosaic.lib.routing.graphhopper.junit.TestGraphRule;
-import org.eclipse.mosaic.lib.routing.graphhopper.util.TurnCostsProvider;
+import org.eclipse.mosaic.lib.routing.graphhopper.util.OptionalTurnCostProvider;
 import org.eclipse.mosaic.lib.routing.graphhopper.util.VehicleEncoding;
 
 import com.graphhopper.routing.weighting.Weighting;
@@ -37,7 +37,7 @@ public class GraphHopperWeightingTest {
     public void fastest_noTurnCosts() {
         VehicleEncoding enc = testGraph.getEncodingManager().getVehicleEncoding("car");
 
-        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new TurnCostsProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
+        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new OptionalTurnCostProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
                 .setRoutingCostFunction(RoutingCostFunction.Fastest);
 
         EdgeExplorer expl = testGraph.getGraph().createEdgeExplorer();
@@ -56,7 +56,7 @@ public void fastest_noTurnCosts() {
     public void shortest_noTurnCosts() {
         VehicleEncoding enc = testGraph.getEncodingManager().getVehicleEncoding("car");
 
-        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new TurnCostsProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
+        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new OptionalTurnCostProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
                 .setRoutingCostFunction(RoutingCostFunction.Shortest);
 
         EdgeExplorer expl = testGraph.getGraph().createEdgeExplorer();
@@ -78,7 +78,7 @@ public void shortest_turnCosts() {
 
         testGraph.getGraph().getTurnCostStorage().set(enc.turnCost(), 1, 0, 0, 10.0);
 
-        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new TurnCostsProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
+        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new OptionalTurnCostProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
                 .setRoutingCostFunction(RoutingCostFunction.Shortest);
 
         EdgeExplorer expl = testGraph.getGraph().createEdgeExplorer();
@@ -99,7 +99,7 @@ public void fastest_turnCosts() {
 
         testGraph.getGraph().getTurnCostStorage().set(enc.turnCost(), 1, 0, 0, 10.0);
 
-        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new TurnCostsProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
+        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new OptionalTurnCostProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
                 .setRoutingCostFunction(RoutingCostFunction.Fastest);
 
         EdgeExplorer expl = testGraph.getGraph().createEdgeExplorer();
@@ -120,7 +120,7 @@ public void shortest_turnRestriction() {
 
         testGraph.getGraph().getTurnCostStorage().set(enc.turnRestriction(), 1, 0, 0, true);
 
-        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new TurnCostsProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
+        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new OptionalTurnCostProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
                 .setRoutingCostFunction(RoutingCostFunction.Shortest);
 
         EdgeExplorer expl = testGraph.getGraph().createEdgeExplorer();
@@ -141,7 +141,7 @@ public void fastest_turnRestriction() {
 
         testGraph.getGraph().getTurnCostStorage().set(enc.turnRestriction(), 1, 0, 0, true);
 
-        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new TurnCostsProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
+        Weighting w = new GraphHopperWeighting(enc, testGraph.getEncodingManager().wayType(), new OptionalTurnCostProvider(enc, testGraph.getGraph().getTurnCostStorage()), null)
                 .setRoutingCostFunction(RoutingCostFunction.Fastest);
 
         EdgeExplorer expl = testGraph.getGraph().createEdgeExplorer();