terra-route 0.0.2 → 0.0.4

package/src/terra-route.ts

@@ -11,30 +11,21 @@ import { createCheapRuler } from "./distance/cheap-ruler";
  * then applies A* algorithm to compute the shortest route.
  */
 class TerraRoute {
-    private network: FeatureCollection<LineString>;
+    private network: FeatureCollection<LineString> | undefined;
     private distanceMeasurement: (positionA: Position, positionB: Position) => number;
-    private adjacencyList: Map<number, Array<{ node: number; distance: number }>>;
-    private coords: Position[];
-    private coordMap: Map<number, Map<number, number>>;
+    private adjacencyList: Map<number, Array<{ node: number; distance: number }>> = new Map();
+    private coords: Position[] = []
+    private coordMap: Map<number, Map<number, number>> = new Map();
 
     /**
      * Creates a new instance of TerraRoute.
      * 
-     * @param network - A GeoJSON FeatureCollection of LineStrings representing the route network.
      * @param distanceMeasurement - Optional custom distance measurement function (defaults to haversine distance).
      */
     constructor(
-        network: FeatureCollection<LineString>,
         distanceMeasurement?: (positionA: Position, positionB: Position) => number
     ) {
-        this.network = network;
-        this.adjacencyList = new Map();
-        this.coords = [];
-        this.coordMap = new Map();
         this.distanceMeasurement = distanceMeasurement ? distanceMeasurement : haversineDistance;
-
-        // 
-        this.buildNetworkGraph();
     }
 
     /**
@@ -63,9 +54,17 @@ 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.
-     * Assumes that the network is a connected graph of LineStrings with shared coordinates.
+     * 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.
      */
-    private buildNetworkGraph(): void {
+    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++) {
@@ -88,11 +87,21 @@ class TerraRoute {
     * @param start - A GeoJSON Point Feature representing the start location.
     * @param end - A GeoJSON Point Feature representing the end location.
     * @returns A GeoJSON LineString Feature representing the shortest path, or null if no path is found.
+    * 
+    * @throws Error if the network has not been built yet with buildRouteGraph(network).
     */
     public getRoute(start: Feature<Point>, end: Feature<Point>): Feature<LineString> | null {
+        if (!this.network) {
+            throw new Error("Network not built. Please call buildNetworkGraph(network) first.");
+        }
+
         const startIdx = this.coordinateIndex(start.geometry.coordinates);
         const endIdx = this.coordinateIndex(end.geometry.coordinates);
 
+        if (startIdx === endIdx) {
+            return null;
+        }
+
         const openSet = new MinHeap();
         openSet.insert(0, startIdx);
         const cameFrom = new Map<number, number>();
@@ -115,7 +124,9 @@ class TerraRoute {
                 };
             }
 
-            for (const neighbor of this.adjacencyList.get(current) || []) {
+            const neighbors = this.adjacencyList.get(current) || [];
+
+            for (const neighbor of neighbors) {
                 const tentativeGScore = (gScore.get(current) ?? Infinity) + neighbor.distance;
                 if (tentativeGScore < (gScore.get(neighbor.node) ?? Infinity)) {
                     cameFrom.set(neighbor.node, current);

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

@@ -22,3 +22,372 @@ export const createLineStringFeature = (coordinates: Position[]): Feature<LineSt
     },
     properties: {},
 });
+
+export function generateGridWithDiagonals(n: number, spacing: number): FeatureCollection<LineString> {
+    const features: Feature<LineString>[] = [];
+
+    const coord = (x: number, y: number): Position => [x * spacing, y * spacing];
+
+    for (let y = 0; y < n; y++) {
+        for (let x = 0; x < n; x++) {
+            // Horizontal edge (to the right)
+            if (x < n - 1) {
+                features.push({
+                    type: "Feature",
+                    geometry: {
+                        type: "LineString",
+                        coordinates: [
+                            coord(x, y),
+                            coord(x + 1, y)
+                        ]
+                    },
+                    properties: {}
+                });
+            }
+
+            // Vertical edge (upward)
+            if (y < n - 1) {
+                features.push({
+                    type: "Feature",
+                    geometry: {
+                        type: "LineString",
+                        coordinates: [
+                            coord(x, y),
+                            coord(x, y + 1)
+                        ]
+                    },
+                    properties: {}
+                });
+            }
+
+            // Diagonal bottom-left to top-right
+            if (x < n - 1 && y < n - 1) {
+                features.push({
+                    type: "Feature",
+                    geometry: {
+                        type: "LineString",
+                        coordinates: [
+                            coord(x, y),
+                            coord(x + 1, y + 1)
+                        ]
+                    },
+                    properties: {}
+                });
+            }
+
+            // Diagonal bottom-right to top-left
+            if (x > 0 && y < n - 1) {
+                features.push({
+                    type: "Feature",
+                    geometry: {
+                        type: "LineString",
+                        coordinates: [
+                            coord(x, y),
+                            coord(x - 1, y + 1)
+                        ]
+                    },
+                    properties: {}
+                });
+            }
+        }
+    }
+
+    return {
+        type: "FeatureCollection",
+        features
+    };
+}
+
+/**
+ * Generate a star-like polygon with n vertices.
+ * If connectAll is true, connects every vertex to every other (complete graph).
+ * If false, connects only the outer ring to form a polygon perimeter.
+ *
+ * @param n - Number of vertices (>= 3)
+ * @param radius - Radius in degrees for placing vertices in a circle
+ * @param center - Center of the polygon [lng, lat]
+ * @param connectAll - If true, connects every pair of vertices. If false, only connects the outer ring.
+ * @returns FeatureCollection of LineStrings
+ */
+export function generateStarPolygon(
+    n: number,
+    radius: number = 0.01,
+    center: Position = [0, 0],
+    connectAll: boolean = true
+): FeatureCollection<LineString> {
+    if (n < 3) {
+        throw new Error("Star polygon requires at least 3 vertices.");
+    }
+
+    const angleStep = (2 * Math.PI) / n;
+    const vertices: Position[] = [];
+
+    // Generate points in a circle
+    for (let i = 0; i < n; i++) {
+        const angle = i * angleStep;
+        const x = center[0] + radius * Math.cos(angle);
+        const y = center[1] + radius * Math.sin(angle);
+        vertices.push([x, y]);
+    }
+
+    const features: Feature<LineString>[] = [];
+
+    if (connectAll) {
+        // Connect every vertex to every other vertex
+        for (let i = 0; i < n; i++) {
+            for (let j = i + 1; j < n; j++) {
+                features.push({
+                    type: "Feature",
+                    geometry: {
+                        type: "LineString",
+                        coordinates: [vertices[i], vertices[j]],
+                    },
+                    properties: {},
+                });
+            }
+        }
+    } else {
+        // Connect outer ring only
+        for (let i = 0; i < n; i++) {
+            const next = (i + 1) % n;
+            features.push({
+                type: "Feature",
+                geometry: {
+                    type: "LineString",
+                    coordinates: [vertices[i], vertices[next]],
+                },
+                properties: {},
+            });
+        }
+    }
+
+    return {
+        type: "FeatureCollection",
+        features,
+    };
+}
+
+
+/**
+ * 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>.
+ *
+ * @param depth - Number of depth levels (>= 1)
+ * @param branchingFactor - Number of children per node
+ * @param root - Root position [lng, lat]
+ * @param length - Distance between each parent and child
+ * @returns FeatureCollection of LineStrings representing the tree
+ */
+export function generateTreeFeatureCollection(
+    depth: number,
+    branchingFactor: number,
+    root: Position = [0, 0],
+    length: number = 0.01
+): FeatureCollection<LineString> {
+    if (depth < 1) {
+        throw new Error("Tree must have at least depth 1.");
+    }
+
+    const features: Feature<LineString>[] = [];
+
+    interface TreeNode {
+        position: Position;
+        level: number;
+    }
+
+    const nodes: TreeNode[] = [{ position: root, level: 0 }];
+
+    const RAD = Math.PI / 180;
+
+    for (let level = 0; level < depth; level++) {
+        const newNodes: TreeNode[] = [];
+
+        for (const node of nodes.filter(n => n.level === level)) {
+            const angleStart = -90 - ((branchingFactor - 1) * 20) / 2;
+
+            for (let i = 0; i < branchingFactor; i++) {
+                const angle = angleStart + i * 20; // spread branches 20 degrees apart
+                const radians = angle * RAD;
+
+                const dx = length * Math.cos(radians);
+                const dy = length * Math.sin(radians);
+
+                const child: Position = [node.position[0] + dx, node.position[1] + dy];
+
+                features.push({
+                    type: "Feature",
+                    geometry: {
+                        type: "LineString",
+                        coordinates: [node.position, child],
+                    },
+                    properties: {},
+                });
+
+                newNodes.push({ position: child, level: level + 1 });
+            }
+        }
+
+        nodes.push(...newNodes);
+    }
+
+    return {
+        type: "FeatureCollection",
+        features,
+    };
+}
+
+/**
+* Generates a connected graph of concentric rings, each ring fully connected
+* around itself and connected radially to the next ring.
+*
+* @param numRings - Number of concentric rings
+* @param pointsPerRing - How many points (nodes) on each ring
+* @param spacing - Distance between consecutive rings
+* @param center - [lng, lat] center of the rings
+* @returns A FeatureCollection of LineStrings for the rings + radial connections
+*/
+export function generateConcentricRings(
+    numRings: number,
+    pointsPerRing: number,
+    spacing: number,
+    center: Position = [0, 0]
+): FeatureCollection<LineString> {
+    // Holds all the ring coordinates: ringPoints[i][j] => coordinate
+    const ringPoints: Position[][] = [];
+
+    // Create ring points
+    for (let i = 0; i < numRings; i++) {
+        const ringRadius = (i + 1) * spacing;
+        const ring: Position[] = [];
+
+        for (let j = 0; j < pointsPerRing; j++) {
+            const angle = (2 * Math.PI * j) / pointsPerRing;
+            const x = center[0] + ringRadius * Math.cos(angle);
+            const y = center[1] + ringRadius * Math.sin(angle);
+            ring.push([x, y]);
+        }
+
+        ringPoints.push(ring);
+    }
+
+    // Build the graph as a collection of LineStrings
+    const features: Feature<LineString>[] = [];
+
+    // 1. Add each ring as a closed loop
+    for (let i = 0; i < numRings; i++) {
+        const coords = ringPoints[i];
+        // Close the ring by appending the first point again
+        const ringWithClosure = [...coords, coords[0]];
+
+        features.push({
+            type: "Feature",
+            properties: {},
+            geometry: {
+                type: "LineString",
+                coordinates: ringWithClosure,
+            },
+        });
+    }
+
+    // 2. Connect rings radially
+    // (i.e., ring i node j to ring i+1 node j)
+    for (let i = 0; i < numRings - 1; i++) {
+        for (let j = 0; j < pointsPerRing; j++) {
+            const start = ringPoints[i][j];
+            const end = ringPoints[i + 1][j];
+
+            features.push({
+                type: "Feature",
+                properties: {},
+                geometry: {
+                    type: "LineString",
+                    coordinates: [start, end],
+                },
+            });
+        }
+    }
+
+    return {
+        type: "FeatureCollection",
+        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})`;
+    }
+
+    // 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';
+        }
+    }
+}