comments and imports relating to cost fields

Author: abyrd

src/main/java/com/conveyal/r5/rastercost/CostField.java

@@ -1,19 +1,19 @@
 package com.conveyal.r5.rastercost;
 
-import com.conveyal.r5.profile.ProfileRequest;
-import com.conveyal.r5.profile.StreetMode;
 import com.conveyal.r5.streets.EdgeStore;
 import com.conveyal.r5.streets.StreetLayer;
-import com.conveyal.r5.streets.TraversalTimeCalculator;
-import com.conveyal.r5.streets.VertexStore;
-import gnu.trove.list.TFloatList;
-import gnu.trove.list.TShortList;
-
-import java.io.File;
-import java.util.List;
 
 /**
- * Subclasses or plugin functions will provide costs for hills, sun, noise, pollution etc.
+ * This models a field of traversal costs, in the sense of a cost that varies over geographic space having different
+ * effects on different edges. Subclasses serve as plugins that provide costs for hills, sun, noise, pollution etc.
+ *
+ * CostFields could in principle apply costs to any mode of travel, and might yield different costs for different modes,
+ * but currently they are not mode-aware. No existing implementations apply to cars, so for now CostFields are simply
+ * ignored for car routing. Ideally CostFields would know which modes they applied to, and the list of CostFields would
+ * be filtered before the street search happens. The logic currently in the StreetRouter constructor could be factored
+ * into a mode-aware factory method that would yield the correct TraversalTimeCalculator. StreetRouter is explicitly
+ * single-use with a single StreetMode. That mode could be specified up front and the TraversalTimeCalculator
+ * chosen accordingly (avoiding the MultistageTraversalTimeCalculator construct entirely when no CostFields apply).
  *
  * Interface-wise, a CostField is like a TraversalTimeCalculator with no turn costs, which transforms an existing
  * traversal time rather than starting from scratch. So TraversalTimeCalculator is like a special case of CostField

src/main/java/com/conveyal/r5/rastercost/SunCostField.java

@@ -29,7 +29,7 @@ public class SunCostField implements CostField, Serializable {
 
     /**
      * Number in the range 0...1 representing the proportion of each edge pair that is in the shade.
-     * Floating point numbers are densest in this range, so 32 bits are more than sufficent.
+     * Floating point numbers are densest in this range, so 32 bits are more than sufficient.
      * These could probably be made 2-4x smaller by storing them in shorts or bytes; we should measure this.
      */
     TFloatList sunProportions = new TFloatArrayList();

src/main/java/com/conveyal/r5/streets/MultistageTraversalTimeCalculator.java

@@ -1,14 +1,8 @@
 package com.conveyal.r5.streets;
 
-import com.conveyal.r5.common.GeometryUtils;
 import com.conveyal.r5.profile.ProfileRequest;
 import com.conveyal.r5.profile.StreetMode;
 import com.conveyal.r5.rastercost.CostField;
-import com.conveyal.r5.rastercost.SunLoader;
-import org.apache.commons.math3.util.FastMath;
-import org.locationtech.jts.algorithm.Angle;
-import org.locationtech.jts.geom.Coordinate;
-import org.locationtech.jts.geom.LineString;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

src/main/java/com/conveyal/r5/streets/StreetRouter.java

@@ -295,10 +295,12 @@ public TIntObjectMap<State> getReachedVertices (VertexStore.VertexFlag flag) {
 
     public StreetRouter (StreetLayer streetLayer) {
         this.streetLayer = streetLayer;
+        // The street layer of the network may contain per-edge traversal times, e.g. from observed traffic data.
         this.timeCalculator = streetLayer.edgeStore.edgeTraversalTimes;
-        // If no per-edge timings were supplied in the network, fall back on simple default timings
+        // If the network has no per-edge timings, fall back on default timings, using OSM speed limits for cars.
         if (this.timeCalculator == null) {
-            // TODO either: 1) don't hardwire drive-on-right, or 2) global https://en.wikipedia.org/wiki/Dagen_H
+            // Constructor call is currently hard-coded to specify drive-on-right turn costs. We should
+            // either a) make this configurable or b) global https://en.wikipedia.org/wiki/Dagen_H
             this.timeCalculator = new BasicTraversalTimeCalculator(streetLayer, true);
         }
         // If any additional costs such as hills or sun are defined, add them on to the base traversal times.