terra-route 0.0.7 → 0.0.9

package/src/terra-route.ts

@@ -3,33 +3,29 @@ import { haversineDistance } from "./distance/haversine";
 import { createCheapRuler } from "./distance/cheap-ruler";
 import { MinHeap } from "./heap/min-heap";
 import { HeapConstructor } from "./heap/heap";
+import { LineStringGraph } from "./graph/graph";
 
-/**
- * TerraRoute is a routing utility for finding the shortest path
- * between two geographic points over a given GeoJSON LineString network.
- *
- * The class builds an internal graph structure based on the provided network,
- * then applies A* algorithm to compute the shortest route.
- */
-class TerraRoute {
-    private network: FeatureCollection<LineString> | undefined;
-    private distanceMeasurement: (positionA: Position, positionB: Position) => number;
-    private adjacencyList: Map<number, Array<{ node: number; distance: number }>> = new Map();
-    private coords: Position[] = []
-    private coordMap: Map<number, Map<number, number>> = new Map();
-    private heap: HeapConstructor;
+interface Router {
+    buildRouteGraph(network: FeatureCollection<LineString>): void;
+    getRoute(start: Feature<Point>, end: Feature<Point>): Feature<LineString> | null;
+}
+
+class TerraRoute implements Router {
+    private network: FeatureCollection<LineString> | null = null;
+    private distanceMeasurement: (a: Position, b: Position) => number;
+    private heapConstructor: HeapConstructor;
+
+    // Map from longitude → (map from latitude → index)
+    private coordinateIndexMap: Map<number, Map<number, number>> = new Map();
+    private coordinates: Position[] = [];
+    private adjacencyList: Array<Array<{ node: number; distance: number }>> = [];
 
-    /**
-     * Creates a new instance of TerraRoute.
-     * 
-     * @param distanceMeasurement - Optional custom distance measurement function (defaults to haversine distance).
-     */
     constructor(options?: {
-        distanceMeasurement?: (positionA: Position, positionB: Position) => number,
-        heap?: HeapConstructor
+        distanceMeasurement?: (a: Position, b: Position) => number;
+        heap?: HeapConstructor;
     }) {
-        this.heap = options?.heap ? options.heap : MinHeap
-        this.distanceMeasurement = options?.distanceMeasurement ? options.distanceMeasurement : haversineDistance;
+        this.distanceMeasurement = options?.distanceMeasurement ?? haversineDistance;
+        this.heapConstructor = options?.heap ?? MinHeap;
     }
 
     /**
@@ -39,48 +35,59 @@ class TerraRoute {
      * @param coord - A GeoJSON Position array representing [longitude, latitude].
      * @returns A unique numeric index for the coordinate.
      */
-    private coordinateIndex(coord: Position): number {
-        const [lng, lat] = coord;
-        if (!this.coordMap.has(lng)) this.coordMap.set(lng, new Map());
-
-        const latMap = this.coordMap.get(lng)!;
-        if (latMap.has(lat)) {
-            return latMap.get(lat)!;
-        }
+    public buildRouteGraph(network: FeatureCollection<LineString>): void {
+        this.network = network;
 
-        const index = this.coords.length;
-        this.coords.push(coord);
-        latMap.set(lat, index);
+        // Reset everything
+        this.coordinateIndexMap = new Map();
+        this.coordinates = [];
+        this.adjacencyList = [];
+
+        // Hoist to locals for speed
+        const coordIndexMapLocal = this.coordinateIndexMap;
+        const coordsLocal = this.coordinates;
+        const adjListLocal = this.adjacencyList;
+        const measureDistance = this.distanceMeasurement;
+
+        for (const feature of network.features) {
+            const lineCoords = feature.geometry.coordinates;
+
+            for (let i = 0; i < lineCoords.length - 1; i++) {
+                const [lngA, latA] = lineCoords[i];
+                const [lngB, latB] = lineCoords[i + 1];
+
+                // get or assign index for A 
+                let latMapA = coordIndexMapLocal.get(lngA);
+                if (!latMapA) {
+                    latMapA = new Map<number, number>();
+                    coordIndexMapLocal.set(lngA, latMapA);
+                }
+                let indexA = latMapA.get(latA);
+                if (indexA === undefined) {
+                    indexA = coordsLocal.length;
+                    coordsLocal.push(lineCoords[i]);
+                    latMapA.set(latA, indexA);
+                    adjListLocal[indexA] = [];
+                }
 
-        return index;
-    }
+                // get or assign index for B 
+                let latMapB = coordIndexMapLocal.get(lngB);
+                if (!latMapB) {
+                    latMapB = new Map<number, number>();
+                    coordIndexMapLocal.set(lngB, latMapB);
+                }
+                let indexB = latMapB.get(latB);
+                if (indexB === undefined) {
+                    indexB = coordsLocal.length;
+                    coordsLocal.push(lineCoords[i + 1]);
+                    latMapB.set(latB, indexB);
+                    adjListLocal[indexB] = [];
+                }
 
-    /**
-     * Builds the internal graph representation (adjacency list) from the input network.
-     * Each LineString segment is translated into graph edges with associated distances.
-     * Assumes that the network is a connected graph of LineStrings with shared coordinates. Calling this 
-     * method with a new network overwrite any existing network and reset all internal data structures.
-     * 
-     * @param network - A GeoJSON FeatureCollection of LineStrings representing the road network.
-     */
-    public buildRouteGraph(network: FeatureCollection<LineString>): void {
-        this.network = network;
-        this.adjacencyList = new Map();
-        this.coords = [];
-        this.coordMap = new Map();
-
-        for (const feature of this.network.features) {
-            const coords = feature.geometry.coordinates;
-            for (let i = 0; i < coords.length - 1; i++) {
-                const aIndex = this.coordinateIndex(coords[i]);
-                const bIndex = this.coordinateIndex(coords[i + 1]);
-                const distance = this.distanceMeasurement(coords[i], coords[i + 1]);
-
-                if (!this.adjacencyList.has(aIndex)) this.adjacencyList.set(aIndex, []);
-                if (!this.adjacencyList.has(bIndex)) this.adjacencyList.set(bIndex, []);
-
-                this.adjacencyList.get(aIndex)!.push({ node: bIndex, distance });
-                this.adjacencyList.get(bIndex)!.push({ node: aIndex, distance });
+                // record the bidirectional edge 
+                const segmentDistance = measureDistance(lineCoords[i], lineCoords[i + 1]);
+                adjListLocal[indexA].push({ node: indexB, distance: segmentDistance });
+                adjListLocal[indexB].push({ node: indexA, distance: segmentDistance });
             }
         }
     }
@@ -102,64 +109,60 @@ class TerraRoute {
             throw new Error("Network not built. Please call buildRouteGraph(network) first.");
         }
 
-        const startIndex = this.coordinateIndex(start.geometry.coordinates);
-        const endIndex = this.coordinateIndex(end.geometry.coordinates);
+        // ensure start/end are in the index maps
+        const startIndex = this.getOrCreateIndex(start.geometry.coordinates);
+        const endIndex = this.getOrCreateIndex(end.geometry.coordinates);
 
         if (startIndex === endIndex) {
             return null;
         }
 
-        const openSet = new this.heap();
+        const openSet = new this.heapConstructor();
         openSet.insert(0, startIndex);
 
-        const cameFrom = new Map<number, number>();
-        const gScore = new Map<number, number>([[startIndex, 0]]);
-        const visited = new Set<number>();
+        const nodeCount = this.coordinates.length;
+        const gScore = new Array<number>(nodeCount).fill(Infinity);
+        const cameFrom = new Array<number>(nodeCount).fill(-1);
+        const visited = new Array<boolean>(nodeCount).fill(false);
+
+        gScore[startIndex] = 0;
 
         while (openSet.size() > 0) {
-            // Extract the node with the smallest fScore
             const current = openSet.extractMin()!;
-
-            // If we've reached the end node, we're done
+            if (visited[current]) {
+                continue;
+            }
             if (current === endIndex) {
                 break;
             }
-
-            visited.add(current);
-
-            // Explore neighbors
-            for (const neighbor of this.adjacencyList.get(current) || []) {
-                // Tentative cost from start to this neighbor
-                const tentativeG = (gScore.get(current) ?? Infinity) + neighbor.distance;
-
-                // If this path to neighbor is better, record it
-                if (tentativeG < (gScore.get(neighbor.node) ?? Infinity)) {
-                    cameFrom.set(neighbor.node, current);
-                    gScore.set(neighbor.node, tentativeG);
-
-                    // Calculate fScore: gScore + heuristic distance to the end
-                    const fScore =
-                        tentativeG +
-                        this.distanceMeasurement(this.coords[neighbor.node], this.coords[endIndex]);
-
-                    openSet.insert(fScore, neighbor.node);
+            visited[current] = true;
+
+            for (const neighbor of this.adjacencyList[current] || []) {
+                const tentativeG = gScore[current] + neighbor.distance;
+                if (tentativeG < gScore[neighbor.node]) {
+                    gScore[neighbor.node] = tentativeG;
+                    cameFrom[neighbor.node] = current;
+                    const heuristic = this.distanceMeasurement(
+                        this.coordinates[neighbor.node],
+                        this.coordinates[endIndex]
+                    );
+                    openSet.insert(tentativeG + heuristic, neighbor.node);
                 }
             }
         }
 
-        // If we never set a path to the end node, there's no route
-        if (!cameFrom.has(endIndex)) {
+        if (cameFrom[endIndex] < 0) {
             return null;
         }
 
-        // Reconstruct the path from end node to start node
+        // Reconstruct path
         const path: Position[] = [];
-        let node = endIndex;
-
-        while (node !== undefined) {
-            path.unshift(this.coords[node]);
-            node = cameFrom.get(node)!;
+        let current = endIndex;
+        while (current !== startIndex) {
+            path.unshift(this.coordinates[current]);
+            current = cameFrom[current];
         }
+        path.unshift(this.coordinates[startIndex]);
 
         return {
             type: "Feature",
@@ -168,6 +171,26 @@ class TerraRoute {
         };
     }
 
+    /**
+     * Helper to index start/end in getRoute.
+     */
+    private getOrCreateIndex(coord: Position): number {
+        const [lng, lat] = coord;
+        let latMap = this.coordinateIndexMap.get(lng);
+        if (!latMap) {
+            latMap = new Map<number, number>();
+            this.coordinateIndexMap.set(lng, latMap);
+        }
+        let index = latMap.get(lat);
+        if (index === undefined) {
+            index = this.coordinates.length;
+            this.coordinates.push(coord);
+            latMap.set(lat, index);
+            // ensure adjacencyList covers this new node
+            this.adjacencyList[index] = [];
+        }
+        return index;
+    }
 }
 
-export { TerraRoute, createCheapRuler, haversineDistance }
+export { TerraRoute, createCheapRuler, haversineDistance, LineStringGraph }

package/src/test-utils/create.ts

@@ -0,0 +1,39 @@
+import { Position, Feature, Point, LineString, FeatureCollection } from "geojson";
+
+/**
+ * Creates a GeoJSON Point feature from a coordinate.
+ * @param coord - A coordinate in the form of [longitude, latitude]
+ * @returns A GeoJSON Feature<Point> object
+ */
+export const createPointFeature = (coord: Position): Feature<Point> => ({
+    type: "Feature",
+    geometry: {
+        type: "Point",
+        coordinates: coord,
+    },
+    properties: {},
+});
+
+/**
+ * Creates a GeoJSON LineString feature from an array of coordinates.
+ * @param coordinates - An array of coordinates in the form of [longitude, latitude]
+ * @returns A GeoJSON Feature<LineString> object
+ */
+export const createLineStringFeature = (coordinates: Position[]): Feature<LineString> => ({
+    type: "Feature",
+    geometry: {
+        type: "LineString",
+        coordinates,
+    },
+    properties: {},
+});
+
+/**
+ * Creates a GeoJSON FeatureCollection from an array of features.
+ * @param features - An array of GeoJSON Feature<LineString> objects
+ * @returns A GeoJSON FeatureCollection object
+ */
+export const createFeatureCollection = (features: Feature<LineString>[]): FeatureCollection<LineString> => ({
+    type: "FeatureCollection",
+    features,
+});

package/src/test-utils/{test-utils.ts → generate-network.ts}

@@ -1,43 +1,13 @@
-import { Position, Feature, Point, LineString, FeatureCollection } from "geojson";
-import { haversineDistance } from "../terra-route";
-
-export const createPointFeature = (coord: Position): Feature<Point> => ({
-    type: "Feature",
-    geometry: {
-        type: "Point",
-        coordinates: coord,
-    },
-    properties: {},
-});
-
-export const createFeatureCollection = (features: Feature<LineString>[]): FeatureCollection<LineString> => ({
-    type: "FeatureCollection",
-    features,
-});
-
-export const createLineStringFeature = (coordinates: Position[]): Feature<LineString> => ({
-    type: "Feature",
-    geometry: {
-        type: "LineString",
-        coordinates,
-    },
-    properties: {},
-});
-
-export function routeLength(
-    line: Feature<LineString>,
-
-) {
-    const lineCoords = line.geometry.coordinates;
-
-    // Calculate the total route distance
-    let routeDistance = 0;
-    for (let i = 0; i < lineCoords.length - 1; i++) {
-        routeDistance += haversineDistance(lineCoords[i], lineCoords[i + 1]);
-    }
-    return routeDistance
-}
+import { FeatureCollection, LineString, Feature, Position } from "geojson";
 
+/**
+ * Generates a grid of LineStrings with n x n nodes, spaced by the given spacing.
+ * Each node is connected to its right and upward neighbors, and diagonals are included.
+ *
+ * @param n - Number of nodes in each dimension (n x n grid)
+ * @param spacing - Distance between consecutive nodes
+ * @returns FeatureCollection of LineStrings representing the grid
+ */
 export function generateGridWithDiagonals(n: number, spacing: number): FeatureCollection<LineString> {
     const features: Feature<LineString>[] = [];
 
@@ -182,38 +152,6 @@ export function generateStarPolygon(
     };
 }
 
-
-/**
- * Extracts unique coordinates from a FeatureCollection of LineStrings.
- *
- * @param collection - A GeoJSON FeatureCollection of LineStrings
- * @returns An array of unique Position coordinates
- */
-export function getUniqueCoordinatesFromLineStrings(
-    collection: FeatureCollection<LineString>
-): Position[] {
-    const seen = new Set<string>();
-    const unique: Position[] = [];
-
-    for (const feature of collection.features) {
-        if (feature.geometry.type !== "LineString") {
-            continue;
-        }
-
-        for (const coord of feature.geometry.coordinates) {
-            const key = `${coord[0]},${coord[1]}`;
-
-            if (!seen.has(key)) {
-                seen.add(key);
-                unique.push(coord);
-            }
-        }
-    }
-
-    return unique;
-}
-
-
 /**
  * Generate a spatial n-depth tree as a FeatureCollection<LineString>.
  *
@@ -357,120 +295,3 @@ export function generateConcentricRings(
         features,
     };
 }
-
-
-/**
- * Validates a GeoJSON Feature<LineString> route.
- *
- * @param route - The GeoJSON feature to validate
- * @returns A boolean indicating if it is a valid LineString route
- */
-export function getReasonIfLineStringInvalid(
-    route: Feature<LineString> | null | undefined
-): string | undefined {
-    // 1. Must exist
-    if (!route) {
-        return 'No feature';
-    }
-
-    // 2. Must be a Feature
-    if (route.type !== "Feature") {
-        return 'Not a Feature';
-    }
-
-    // 3. Must have a geometry of type LineString
-    if (!route.geometry || route.geometry.type !== "LineString") {
-        return 'Not a LineString';
-    }
-
-    // 4. Coordinates must be an array with length >= 2
-    const coords = route.geometry.coordinates;
-    if (!Array.isArray(coords) || coords.length < 2) {
-        return `Not enough coordinates: ${coords.length} (${coords})`;
-    }
-
-    const seen = new Set<string>();
-
-    // 5. Validate each coordinate is a valid Position
-    //    (At minimum, [number, number] or [number, number, number])
-    for (const position of coords) {
-        if (!Array.isArray(position)) {
-            return 'Not a Position; not an array';
-        }
-
-        // Check numeric values, ignoring optional altitude
-        if (
-            position.length < 2 ||
-            typeof position[0] !== "number" ||
-            typeof position[1] !== "number"
-        ) {
-            return 'Not a Position; elements are not a numbers';
-        }
-
-        // 6. Check for duplicates
-        const key = `${position[0]},${position[1]}`;
-        if (seen.has(key)) {
-            return `Duplicate coordinate: ${key}`;
-        }
-        seen.add(key);
-    }
-}
-
-/**
- * Checks if the start and end coordinates of a LineString match the given start and end points.
- * 
- * @param line - The LineString feature to check
- * @param start - The start point feature
- * @param end - The end point feature
- * @return True if the start and end coordinates match, false otherwise
- * */
-export function startAndEndAreCorrect(line: Feature<LineString>, start: Feature<Point>, end: Feature<Point>) {
-    const lineCoords = line.geometry.coordinates;
-    const startCoords = start.geometry.coordinates;
-    const endCoords = end.geometry.coordinates;
-
-    // Check if the first coordinate of the LineString matches the start point
-    const startMatches = lineCoords[0][0] === startCoords[0] && lineCoords[0][1] === startCoords[1];
-
-    // Check if the last coordinate of the LineString matches the end point
-    const endMatches = lineCoords[lineCoords.length - 1][0] === endCoords[0] && lineCoords[lineCoords.length - 1][1] === endCoords[1];
-
-    return startMatches && endMatches;
-}
-
-export function routeIsLongerThanDirectPath(line: Feature<LineString>, start: Feature<Point>, end: Feature<Point>) {
-    const lineCoords = line.geometry.coordinates;
-    const startCoords = start.geometry.coordinates;
-    const endCoords = end.geometry.coordinates;
-
-    if (lineCoords.length <= 2) {
-        return true;
-    }
-
-    // Calculate the direct distance between the start and end points
-    const directDistance = haversineDistance(startCoords, endCoords);
-
-    // Calculate the route distance
-    let routeDistance = 0;
-    for (let i = 0; i < lineCoords.length - 1; i++) {
-        routeDistance += haversineDistance(lineCoords[i], lineCoords[i + 1]);
-    }
-
-    // If the route distance is 0, it means the start and end points are the same
-    if (routeDistance === 0) {
-        return true;
-    }
-
-    if (routeDistance < directDistance) {
-
-        // Check if the route distance is very close to the direct distance
-        const absoluteDifference = Math.abs(routeDistance - directDistance);
-        if (absoluteDifference < 0.000000000001) {
-            return true;
-        }
-
-        return false;
-    }
-
-    return true
-}