terra-route 0.0.6 → 0.0.7

package/src/terra-route.ts

@@ -1,7 +1,8 @@
 import { FeatureCollection, LineString, Point, Feature, Position } from "geojson";
-import { FibonacciHeap } from "./fibonacci-heap";
 import { haversineDistance } from "./distance/haversine";
 import { createCheapRuler } from "./distance/cheap-ruler";
+import { MinHeap } from "./heap/min-heap";
+import { HeapConstructor } from "./heap/heap";
 
 /**
  * TerraRoute is a routing utility for finding the shortest path
@@ -16,16 +17,19 @@ class TerraRoute {
     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;
 
     /**
      * Creates a new instance of TerraRoute.
      * 
      * @param distanceMeasurement - Optional custom distance measurement function (defaults to haversine distance).
      */
-    constructor(
-        distanceMeasurement?: (positionA: Position, positionB: Position) => number
-    ) {
-        this.distanceMeasurement = distanceMeasurement ? distanceMeasurement : haversineDistance;
+    constructor(options?: {
+        distanceMeasurement?: (positionA: Position, positionB: Position) => number,
+        heap?: HeapConstructor
+    }) {
+        this.heap = options?.heap ? options.heap : MinHeap
+        this.distanceMeasurement = options?.distanceMeasurement ? options.distanceMeasurement : haversineDistance;
     }
 
     /**
@@ -53,7 +57,7 @@ class TerraRoute {
 
     /**
      * Builds the internal graph representation (adjacency list) from the input network.
-     * Each LineString segment is translated into bidirectional graph edges with associated distances.
+     * 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.
      * 
@@ -82,7 +86,7 @@ class TerraRoute {
     }
 
     /**
-    * Computes the shortest route between two points in the network using bidirectional A* algorithm.
+    * Computes the shortest route between two points in the network using the A* algorithm.
     * 
     * @param start - A GeoJSON Point Feature representing the start location.
     * @param end - A GeoJSON Point Feature representing the end location.
@@ -90,7 +94,10 @@ class TerraRoute {
     * 
     * @throws Error if the network has not been built yet with buildRouteGraph(network).
     */
-    public getRoute(start: Feature<Point>, end: Feature<Point>): Feature<LineString> | null {
+    public getRoute(
+        start: Feature<Point>,
+        end: Feature<Point>
+    ): Feature<LineString> | null {
         if (!this.network) {
             throw new Error("Network not built. Please call buildRouteGraph(network) first.");
         }
@@ -102,87 +109,65 @@ class TerraRoute {
             return null;
         }
 
-        const openSetForward = new FibonacciHeap();
-        const openSetBackward = new FibonacciHeap();
-        openSetForward.insert(0, startIndex);
-        openSetBackward.insert(0, endIndex);
+        const openSet = new this.heap();
+        openSet.insert(0, startIndex);
 
-        const cameFromForward = new Map<number, number>();
-        const cameFromBackward = new Map<number, number>();
-        const gScoreForward = new Map<number, number>([[startIndex, 0]]);
-        const gScoreBackward = new Map<number, number>([[endIndex, 0]]);
+        const cameFrom = new Map<number, number>();
+        const gScore = new Map<number, number>([[startIndex, 0]]);
+        const visited = new Set<number>();
 
-        const visitedForward = new Set<number>();
-        const visitedBackward = new Set<number>();
+        while (openSet.size() > 0) {
+            // Extract the node with the smallest fScore
+            const current = openSet.extractMin()!;
 
-        let meetingNode: number | null = null;
-
-        while (openSetForward.size() > 0 && openSetBackward.size() > 0) {
-            const currentForward = openSetForward.extractMin()!;
-            visitedForward.add(currentForward);
-
-            if (visitedBackward.has(currentForward)) {
-                meetingNode = currentForward;
+            // If we've reached the end node, we're done
+            if (current === endIndex) {
                 break;
             }
 
-            for (const neighbor of this.adjacencyList.get(currentForward) || []) {
-                const tentativeG = (gScoreForward.get(currentForward) ?? Infinity) + neighbor.distance;
-                if (tentativeG < (gScoreForward.get(neighbor.node) ?? Infinity)) {
-                    cameFromForward.set(neighbor.node, currentForward);
-                    gScoreForward.set(neighbor.node, tentativeG);
-                    const fScore = tentativeG + this.distanceMeasurement(this.coords[neighbor.node], this.coords[endIndex]);
-                    openSetForward.insert(fScore, neighbor.node);
-                }
-            }
+            visited.add(current);
 
-            const currentBackward = openSetBackward.extractMin()!;
-            visitedBackward.add(currentBackward);
+            // 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 (visitedForward.has(currentBackward)) {
-                meetingNode = currentBackward;
-                break;
-            }
+                // 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);
 
-            for (const neighbor of this.adjacencyList.get(currentBackward) || []) {
-                const tentativeG = (gScoreBackward.get(currentBackward) ?? Infinity) + neighbor.distance;
-                if (tentativeG < (gScoreBackward.get(neighbor.node) ?? Infinity)) {
-                    cameFromBackward.set(neighbor.node, currentBackward);
-                    gScoreBackward.set(neighbor.node, tentativeG);
-                    const fScore = tentativeG + this.distanceMeasurement(this.coords[neighbor.node], this.coords[startIndex]);
-                    openSetBackward.insert(fScore, neighbor.node);
+                    // 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);
                 }
             }
         }
 
-        if (meetingNode === null) {
+        // If we never set a path to the end node, there's no route
+        if (!cameFrom.has(endIndex)) {
             return null;
         }
 
-        // Reconstruct forward path
-        const pathForward: Position[] = [];
-        let node = meetingNode;
-        while (node !== undefined) {
-            pathForward.unshift(this.coords[node]);
-            node = cameFromForward.get(node)!;
-        }
+        // Reconstruct the path from end node to start node
+        const path: Position[] = [];
+        let node = endIndex;
 
-        // Reconstruct backward path (omit meeting node to avoid duplication)
-        const pathBackward: Position[] = [];
-        node = cameFromBackward.get(meetingNode)!;
         while (node !== undefined) {
-            pathBackward.push(this.coords[node]);
-            node = cameFromBackward.get(node)!;
+            path.unshift(this.coords[node]);
+            node = cameFrom.get(node)!;
         }
 
-        const fullPath = [...pathForward, ...pathBackward];
-
         return {
             type: "Feature",
-            geometry: { type: "LineString", coordinates: fullPath },
+            geometry: { type: "LineString", coordinates: path },
             properties: {},
         };
     }
+
 }
 
 export { TerraRoute, createCheapRuler, haversineDistance }

package/src/test-utils/test-utils.ts

@@ -1,4 +1,5 @@
 import { Position, Feature, Point, LineString, FeatureCollection } from "geojson";
+import { haversineDistance } from "../terra-route";
 
 export const createPointFeature = (coord: Position): Feature<Point> => ({
     type: "Feature",
@@ -23,6 +24,20 @@ export const createLineStringFeature = (coordinates: Position[]): Feature<LineSt
     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
+}
+
 export function generateGridWithDiagonals(n: number, spacing: number): FeatureCollection<LineString> {
     const features: Feature<LineString>[] = [];
 
@@ -111,9 +126,9 @@ export function generateGridWithDiagonals(n: number, spacing: number): FeatureCo
  */
 export function generateStarPolygon(
     n: number,
-    radius: number = 0.01,
+    radius = 0.01,
     center: Position = [0, 0],
-    connectAll: boolean = true
+    connectAll = true
 ): FeatureCollection<LineString> {
     if (n < 3) {
         throw new Error("Star polygon requires at least 3 vertices.");
@@ -212,7 +227,7 @@ export function generateTreeFeatureCollection(
     depth: number,
     branchingFactor: number,
     root: Position = [0, 0],
-    length: number = 0.01
+    length = 0.01
 ): FeatureCollection<LineString> {
     if (depth < 1) {
         throw new Error("Tree must have at least depth 1.");
@@ -400,3 +415,62 @@ export function getReasonIfLineStringInvalid(
         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
+}

package/src/fibonacci-heap.spec.ts

@@ -1,55 +0,0 @@
-import { FibonacciHeap } from './fibonacci-heap';
-
-describe('FibonacciHeap', () => {
-    let heap: FibonacciHeap;
-
-    beforeEach(() => {
-        heap = new FibonacciHeap();
-    });
-
-    test('insert() and size()', () => {
-        expect(heap.size()).toBe(0);
-        heap.insert(10, 1);
-        expect(heap.size()).toBe(1);
-        heap.insert(5, 2);
-        expect(heap.size()).toBe(2);
-    });
-
-    test('extractMin() returns the correct value', () => {
-        heap.insert(20, 101);
-        heap.insert(5, 102);
-        heap.insert(15, 103);
-
-        expect(heap.extractMin()).toBe(102); // key 5
-        expect(heap.size()).toBe(2);
-        expect(heap.extractMin()).toBe(103); // key 15
-        expect(heap.extractMin()).toBe(101); // key 20
-        expect(heap.extractMin()).toBeNull();
-    });
-
-    test('extractMin() on empty heap returns null', () => {
-        expect(heap.extractMin()).toBeNull();
-    });
-
-    test('insert() handles duplicate keys', () => {
-        heap.insert(10, 201);
-        heap.insert(10, 202);
-        heap.insert(10, 203);
-
-        const values = [heap.extractMin(), heap.extractMin(), heap.extractMin()];
-        expect(values).toContain(201);
-        expect(values).toContain(202);
-        expect(values).toContain(203);
-        expect(heap.size()).toBe(0);
-    });
-
-    test('interleaved insert and extractMin()', () => {
-        heap.insert(30, 301);
-        heap.insert(10, 302);
-        expect(heap.extractMin()).toBe(302);
-        heap.insert(20, 303);
-        expect(heap.extractMin()).toBe(303);
-        expect(heap.extractMin()).toBe(301);
-        expect(heap.extractMin()).toBeNull();
-    });
-});

package/src/fibonacci-heap.ts

@@ -1,131 +0,0 @@
-type FibNode = {
-    key: number;
-    value: number;
-    degree: number;
-    mark: boolean;
-    parent: FibNode | null;
-    child: FibNode | null;
-    left: FibNode;
-    right: FibNode;
-};
-
-export class FibonacciHeap {
-    private nodeCount = 0;
-    private minNode: FibNode | null = null;
-
-    insert(key: number, value: number): void {
-        const node: FibNode = {
-            key,
-            value,
-            degree: 0,
-            mark: false,
-            parent: null,
-            child: null,
-            left: null as any,
-            right: null as any,
-        };
-        node.left = node;
-        node.right = node;
-
-        this.minNode = this.mergeLists(this.minNode, node);
-        this.nodeCount++;
-    }
-
-    extractMin(): number | null {
-        const z = this.minNode;
-        if (!z) return null;
-
-        // Add children to root list
-        if (z.child) {
-            let child = z.child;
-            do {
-                child.parent = null;
-                child = child.right!;
-            } while (child !== z.child);
-            this.minNode = this.mergeLists(this.minNode, z.child);
-        }
-
-        this.removeFromList(z);
-
-        if (z === z.right) {
-            this.minNode = null;
-        } else {
-            this.minNode = z.right;
-            this.consolidate();
-        }
-
-        this.nodeCount--;
-        return z.value;
-    }
-
-    size(): number {
-        return this.nodeCount;
-    }
-
-    // ========== Internal Methods ==========
-
-    private consolidate(): void {
-        const maxDegree = Math.floor(Math.log2(this.nodeCount)) + 1;
-        const A = new Array<FibNode | null>(maxDegree).fill(null);
-
-        const rootList: FibNode[] = [];
-        let curr = this.minNode!;
-        do {
-            rootList.push(curr);
-            curr = curr.right!;
-        } while (curr !== this.minNode);
-
-        for (const w of rootList) {
-            let x = w;
-            let d = x.degree;
-            while (A[d]) {
-                let y = A[d]!;
-                if (x.key > y.key) {
-                    const temp = x;
-                    x = y;
-                    y = temp;
-                }
-                this.link(y, x);
-                A[d] = null;
-                d++;
-            }
-            A[d] = x;
-        }
-
-        this.minNode = null;
-        for (const node of A) {
-            if (node) {
-                this.minNode = this.mergeLists(this.minNode, node);
-            }
-        }
-    }
-
-    private link(y: FibNode, x: FibNode): void {
-        this.removeFromList(y);
-        y.left = y.right = y;
-        x.child = this.mergeLists(x.child, y);
-        y.parent = x;
-        x.degree++;
-        y.mark = false;
-    }
-
-    private mergeLists(a: FibNode | null, b: FibNode | null): FibNode {
-        if (!a) return b!;
-        if (!b) return a;
-
-        const aRight = a.right!;
-        const bRight = b.right!;
-
-        a.right = bRight;
-        bRight.left = a;
-        b.right = aRight;
-        aRight.left = b;
-
-        return a.key < b.key ? a : b;
-    }
-
-    private removeFromList(node: FibNode): void {
-        node.left.right = node.right;
-        node.right.left = node.left;
-    }
-}