@tmlmobilidade/go-utils-geo 20260828.1636.54

package/dist/geohash/geohash-decode.d.ts

@@ -0,0 +1,2 @@
+import geohash from 'ngeohash';
+export declare const geohashDecode: (...args: Parameters<typeof geohash.decode>) => geohash.GeographicPoint;

package/dist/geohash/geohash-decode.js

@@ -0,0 +1,4 @@
+/* * */
+import geohash from 'ngeohash';
+/* * */
+export const geohashDecode = (...args) => geohash.decode(...args);

package/dist/geohash/geohash-encode.d.ts

@@ -0,0 +1,2 @@
+import geohash from 'ngeohash';
+export declare const geohashEncode: (...args: Parameters<typeof geohash.encode>) => string;

package/dist/geohash/geohash-encode.js

@@ -0,0 +1,4 @@
+/* * */
+import geohash from 'ngeohash';
+/* * */
+export const geohashEncode = (...args) => geohash.encode(...args);

package/dist/geohash/index.d.ts

@@ -0,0 +1,2 @@
+export * from './geohash-decode.js';
+export * from './geohash-encode.js';

package/dist/geohash/index.js

@@ -0,0 +1,2 @@
+export * from './geohash-decode.js';
+export * from './geohash-encode.js';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './geohash/index.js';
+export * from './measurements/index.js';
+export * from './polylines/index.js';
+export * from './transformers/index.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './geohash/index.js';
+export * from './measurements/index.js';
+export * from './polylines/index.js';
+export * from './transformers/index.js';

package/dist/measurements/distance-between-points.d.ts

@@ -0,0 +1,21 @@
+import { type GeoJsonPointGeometry, type GeoJsonPosition } from '@tmlmobilidade/go-types-geo';
+/**
+ * Calculates the distance between two points, in meters.
+ * This is a wrapper function around the `getDistanceBetweenPositions` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @returns The distance between the two points, in meters.
+ */
+export declare function getDistanceBetweenPoints(pointA: GeoJsonPointGeometry, pointB: GeoJsonPointGeometry): number;
+/**
+ * Calculates the distance between two coordinate positions, in meters.
+ * This function uses the Haversine formula to calculate the distance
+ * between two points on the Earth's surface, given their latitude and longitude.
+ * The formula accounts for the curvature of the Earth.
+ * It is important to note that this function assumes the Earth is a perfect sphere,
+ * which is not entirely accurate, but it provides a good approximation for small distances.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @returns The distance between the two points, in meters.
+ */
+export declare function getDistanceBetweenPositions(positionA: GeoJsonPosition, positionB: GeoJsonPosition): number;

package/dist/measurements/distance-between-points.js

@@ -0,0 +1,35 @@
+/* * */
+import { METERS_PER_DEGREE } from '@tmlmobilidade/go-types-geo';
+/**
+ * Calculates the distance between two points, in meters.
+ * This is a wrapper function around the `getDistanceBetweenPositions` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @returns The distance between the two points, in meters.
+ */
+export function getDistanceBetweenPoints(pointA, pointB) {
+    return getDistanceBetweenPositions(pointA.coordinates, pointB.coordinates);
+}
+/**
+ * Calculates the distance between two coordinate positions, in meters.
+ * This function uses the Haversine formula to calculate the distance
+ * between two points on the Earth's surface, given their latitude and longitude.
+ * The formula accounts for the curvature of the Earth.
+ * It is important to note that this function assumes the Earth is a perfect sphere,
+ * which is not entirely accurate, but it provides a good approximation for small distances.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @returns The distance between the two points, in meters.
+ */
+export function getDistanceBetweenPositions(positionA, positionB) {
+    // Extract coordinates from the points
+    const [lngA, latA] = positionA;
+    const [lngB, latB] = positionB;
+    // Calculate the average latitude
+    const averageLatitude = (latA + latB) / 2;
+    // Calculate the differences in longitude and latitude
+    const dx = (lngB - lngA) * METERS_PER_DEGREE * Math.cos((averageLatitude * Math.PI) / 180);
+    const dy = (latB - latA) * METERS_PER_DEGREE;
+    // Calculate the distance using the Pythagorean theorem
+    return Math.sqrt(dx * dx + dy * dy);
+}

package/dist/measurements/index.d.ts

@@ -0,0 +1,2 @@
+export * from './distance-between-points.js';
+export * from './interpolate.js';

package/dist/measurements/index.js

@@ -0,0 +1,2 @@
+export * from './distance-between-points.js';
+export * from './interpolate.js';

package/dist/measurements/interpolate.d.ts

@@ -0,0 +1,22 @@
+import { type GeoJsonPointGeometry, type GeoJsonPosition } from '@tmlmobilidade/go-types-geo';
+/**
+ * Interpolates between two points at a given ratio (0..1).
+ * This is a wrapper function around the `interpolatePosition` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @param ratio The ratio at which to interpolate (0 = pointA, 1 = pointB).
+ * @returns The interpolated point.
+ */
+export declare function interpolatePoints(pointA: GeoJsonPointGeometry, pointB: GeoJsonPointGeometry, ratio: number): GeoJsonPointGeometry;
+/**
+ * Linearly interpolates between two positions at a given ratio (0..1).
+ * This function is useful for calculating intermediate points
+ * along a line segment defined by two positions.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @param ratio The ratio at which to interpolate (0 = positionA, 1 = positionB).
+ * A ratio of 0.5 would give the midpoint between the two positions.
+ * A ratio of 0.25 would give a point closer to positionA.
+ * @returns The interpolated position.
+ */
+export declare function interpolatePositions(positionA: GeoJsonPosition, positionB: GeoJsonPosition, ratio: number): GeoJsonPosition;

package/dist/measurements/interpolate.js

@@ -0,0 +1,40 @@
+/* * */
+import { GeoJsonPointGeometrySchema, LatitudeSchema, LongitudeSchema } from '@tmlmobilidade/go-types-geo';
+/**
+ * Interpolates between two points at a given ratio (0..1).
+ * This is a wrapper function around the `interpolatePosition` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @param ratio The ratio at which to interpolate (0 = pointA, 1 = pointB).
+ * @returns The interpolated point.
+ */
+export function interpolatePoints(pointA, pointB, ratio) {
+    const result = interpolatePositions(pointA.coordinates, pointB.coordinates, ratio);
+    return GeoJsonPointGeometrySchema.parse({
+        coordinates: result,
+        type: 'Point',
+    });
+}
+/**
+ * Linearly interpolates between two positions at a given ratio (0..1).
+ * This function is useful for calculating intermediate points
+ * along a line segment defined by two positions.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @param ratio The ratio at which to interpolate (0 = positionA, 1 = positionB).
+ * A ratio of 0.5 would give the midpoint between the two positions.
+ * A ratio of 0.25 would give a point closer to positionA.
+ * @returns The interpolated position.
+ */
+export function interpolatePositions(positionA, positionB, ratio) {
+    // Extract coordinates from the points
+    const lng = LongitudeSchema.parse(positionA[0] + (positionB[0] - positionA[0]) * ratio);
+    const lat = LatitudeSchema.parse(positionA[1] + (positionB[1] - positionA[1]) * ratio);
+    // Preserve elevation if present
+    if (positionA.length === 3 && positionB.length === 3) {
+        const alt = positionA[2] + (positionB[2] - positionA[2]) * ratio;
+        return [lng, lat, alt];
+    }
+    // Return the interpolated position
+    return [lng, lat];
+}

package/dist/polylines/from-line-string-to-polyline.d.ts

@@ -0,0 +1,7 @@
+import { type EncodedPolyline, type GeoJsonLineStringGeometry } from '@tmlmobilidade/go-types-geo';
+/**
+ * Decode a polyline from an encoded string into a GeoJSON LineString.
+ * @param value The polyline to encode.
+ * @returns The encoded polyline.
+ */
+export declare function fromGeoJsonLineStringToEncodedPolyline(lineString: GeoJsonLineStringGeometry): EncodedPolyline;

package/dist/polylines/from-line-string-to-polyline.js

@@ -0,0 +1,48 @@
+/* * */
+import { EncodedPolylineSchema, GeoJsonLineStringGeometrySchema } from '@tmlmobilidade/go-types-geo';
+/**
+ * Decode a polyline from an encoded string into a GeoJSON LineString.
+ * @param value The polyline to encode.
+ * @returns The encoded polyline.
+ */
+export function fromGeoJsonLineStringToEncodedPolyline(lineString) {
+    // Validate the GeoJSON LineString.
+    const validatedLineString = GeoJsonLineStringGeometrySchema.parse(lineString);
+    // Initialize the output string.
+    let result = '';
+    // Initialize the previous latitude and longitude values.
+    let previousLat = 0;
+    let previousLng = 0;
+    // Define a function to encode a value.
+    function encodeValue(value) {
+        // Initialize the output string.
+        let encoded = '';
+        // If the value is negative, negate it.
+        value = value < 0 ? ~(value << 1) : value << 1;
+        // Loop until the value is less than 0x20.
+        while (value >= 0x20) {
+            // Add the encoded value to the output string.
+            encoded += String.fromCharCode((0x20 | (value & 0x1f)) + 63);
+            // Shift the value by 5 bits.
+            value >>= 5;
+        }
+        // Add the final encoded value to the output string.
+        encoded += String.fromCharCode(value + 63);
+        // Return the encoded value.
+        return encoded;
+    }
+    // Loop through the coordinates of the polyline.
+    for (const [lng, lat] of validatedLineString.coordinates) {
+        // Convert the latitude and longitude values to E5 format.
+        const latE6 = Math.round(lat * 1e6);
+        const lngE6 = Math.round(lng * 1e6);
+        // Encode the latitude and longitude values.
+        result += encodeValue(latE6 - previousLat);
+        result += encodeValue(lngE6 - previousLng);
+        // Update the previous latitude and longitude values.
+        previousLat = latE6;
+        previousLng = lngE6;
+    }
+    // Validate and return the encoded polyline.
+    return EncodedPolylineSchema.parse(result);
+}

package/dist/polylines/from-polyline-to-line-string.d.ts

@@ -0,0 +1,9 @@
+import { type EncodedPolyline, type GeoJsonLineStringGeometry } from '@tmlmobilidade/go-types-geo';
+/**
+ * Decode a polyline from an encoded string into a GeoJSON LineString.
+ * @param encoded The encoded polyline to decode.
+ * @param onPoint A callback function that receives the latitude
+ * and longitude values for each decoded coordinate.
+ * @throws An error if the input is malformed.
+ */
+export declare function fromEncodedPolylineToGeoJsonLineString(value: EncodedPolyline): GeoJsonLineStringGeometry;

package/dist/polylines/from-polyline-to-line-string.js

@@ -0,0 +1,19 @@
+/* * */
+import { GeoJsonLineStringGeometrySchema, parseEncodedPolyline } from '@tmlmobilidade/go-types-geo';
+/**
+ * Decode a polyline from an encoded string into a GeoJSON LineString.
+ * @param encoded The encoded polyline to decode.
+ * @param onPoint A callback function that receives the latitude
+ * and longitude values for each decoded coordinate.
+ * @throws An error if the input is malformed.
+ */
+export function fromEncodedPolylineToGeoJsonLineString(value) {
+    // Initialize the coordinates array.
+    const result = { coordinates: [], type: 'LineString' };
+    // Parse the encoded polyline.
+    parseEncodedPolyline(value, (decodedLatitude, decodedLongitude) => {
+        result.coordinates.push([decodedLongitude, decodedLatitude]);
+    });
+    // Return the decoded polyline.
+    return GeoJsonLineStringGeometrySchema.parse(result);
+}

package/dist/polylines/index.d.ts

@@ -0,0 +1,2 @@
+export * from './from-line-string-to-polyline.js';
+export * from './from-polyline-to-line-string.js';

package/dist/polylines/index.js

@@ -0,0 +1,2 @@
+export * from './from-line-string-to-polyline.js';
+export * from './from-polyline-to-line-string.js';

package/dist/transformers/chunk-line-by-distance.d.ts

@@ -0,0 +1,13 @@
+import { type GeoJsonLineStringGeometry } from '@tmlmobilidade/go-types-geo';
+/**
+ * Resamples a GeoJSON LineString into equidistant points by walking the full
+ * cumulative distance of the polyline. This function accumulates distance from
+ * the start of the line to each vertex, and places nodes at exact `segmentLength` intervals,
+ * interpolating between vertices. This means that on long "straight" segments, the output will have
+ * more points than on curves, and on short "curved" segments, the output will have fewer points,
+ * maintaining the same overall length of the line and of each chunked segment.
+ * @param inputLineString The LineString to resample.
+ * @param segmentLength The target distance between consecutive output points, in meters.
+ * @returns A GeoJSON LineString with equidistant coordinates along the original path.
+ */
+export declare function chunkLineStringByDistance(inputLineString: GeoJsonLineStringGeometry, segmentLength: number): GeoJsonLineStringGeometry;

package/dist/transformers/chunk-line-by-distance.js

@@ -0,0 +1,54 @@
+/*  * */
+import { getDistanceBetweenPositions } from '../measurements/distance-between-points.js';
+import { interpolatePositions } from '../measurements/interpolate.js';
+import { GeoJsonLineStringGeometrySchema } from '@tmlmobilidade/go-types-geo';
+/**
+ * Resamples a GeoJSON LineString into equidistant points by walking the full
+ * cumulative distance of the polyline. This function accumulates distance from
+ * the start of the line to each vertex, and places nodes at exact `segmentLength` intervals,
+ * interpolating between vertices. This means that on long "straight" segments, the output will have
+ * more points than on curves, and on short "curved" segments, the output will have fewer points,
+ * maintaining the same overall length of the line and of each chunked segment.
+ * @param inputLineString The LineString to resample.
+ * @param segmentLength The target distance between consecutive output points, in meters.
+ * @returns A GeoJSON LineString with equidistant coordinates along the original path.
+ */
+export function chunkLineStringByDistance(inputLineString, segmentLength) {
+    //
+    if (inputLineString.coordinates.length < 2)
+        throw new Error('LineString must have at least 2 coordinates.');
+    //
+    // Pre-compute cumulative distances at each original vertex
+    const cumDist = [0];
+    for (let i = 0; i < inputLineString.coordinates.length - 1; i++) {
+        cumDist.push(cumDist[i] + getDistanceBetweenPositions(inputLineString.coordinates[i], inputLineString.coordinates[i + 1]));
+    }
+    //
+    // If the total length is 0, then return the input line string as is.
+    const totalLength = cumDist[cumDist.length - 1];
+    if (totalLength === 0)
+        return inputLineString;
+    const result = inputLineString.coordinates;
+    //
+    // Walk the polyline placing a node every segmentLength meters
+    let segmentIndex = 0;
+    const nodeCount = Math.floor(totalLength / segmentLength);
+    for (let n = 1; n <= nodeCount; n++) {
+        // Calculate the target distance for the current node
+        const targetDist = n * segmentLength;
+        // Advance segmentIndex to the segment that contains targetDist
+        while (segmentIndex < inputLineString.coordinates.length - 2 && cumDist[segmentIndex + 1] < targetDist) {
+            segmentIndex++;
+        }
+        // Calculate the start and end of the segment
+        const segStart = cumDist[segmentIndex];
+        const segEnd = cumDist[segmentIndex + 1];
+        const ratio = segEnd > segStart ? (targetDist - segStart) / (segEnd - segStart) : 0;
+        // Interpolate the position of the node between the start and end of the segment
+        result.push(interpolatePositions(inputLineString.coordinates[segmentIndex], inputLineString.coordinates[segmentIndex + 1], ratio));
+    }
+    return GeoJsonLineStringGeometrySchema.parse({
+        coordinates: result,
+        type: 'LineString',
+    });
+}

package/dist/transformers/cut-line-at-length.d.ts

@@ -0,0 +1,10 @@
+import { type GeoJsonLineStringGeometry } from '@tmlmobilidade/go-types-geo';
+/**
+ * Cuts a LineString at a specified length.
+ * If the line is shorter than the specified length, it returns the entire line.
+ * @param inputLineString The LineString to cut.
+ * @param length The length at which to cut the line, in meters, from the start of the line.
+ * @param direction The direction in which to cut the line. If 'forward', it cuts from the start of the line.
+ * @returns A new LineString that is cut at the specified length.
+ */
+export declare function cutLineStringAtLength(inputLineString: GeoJsonLineStringGeometry, length: number, direction?: 'forward' | 'reversed'): GeoJsonLineStringGeometry | null;

package/dist/transformers/cut-line-at-length.js

@@ -0,0 +1,72 @@
+/* * */
+import { getDistanceBetweenPositions } from '../measurements/distance-between-points.js';
+import { interpolatePositions } from '../measurements/interpolate.js';
+import { GeoJsonLineStringGeometrySchema } from '@tmlmobilidade/go-types-geo';
+/**
+ * Cuts a LineString at a specified length.
+ * If the line is shorter than the specified length, it returns the entire line.
+ * @param inputLineString The LineString to cut.
+ * @param length The length at which to cut the line, in meters, from the start of the line.
+ * @param direction The direction in which to cut the line. If 'forward', it cuts from the start of the line.
+ * @returns A new LineString that is cut at the specified length.
+ */
+export function cutLineStringAtLength(inputLineString, length, direction = 'forward') {
+    //
+    //
+    // Return the input line string if it is empty,
+    // or null if the length is less than or equal to 0.
+    if (inputLineString.coordinates.length < 2)
+        throw new Error('LineString must have at least 2 coordinates.');
+    if (length <= 0)
+        throw new Error('Length must be greater than 0.');
+    //
+    // Reverse the line if the direction is 'reversed'
+    if (direction === 'reversed') {
+        inputLineString.coordinates = inputLineString.coordinates.slice().reverse();
+    }
+    //
+    // Hold the cumulative distance between points
+    // and the coordinates of the new line
+    let cumulativeLength = 0;
+    const newLineStringCoordinates = [];
+    //
+    // Loop through the coordinates of the line
+    for (let i = 0; i < inputLineString.coordinates.length - 1; i++) {
+        // Get the coordinates of the current and the next point
+        const coordA = inputLineString.coordinates[i];
+        const coordB = inputLineString.coordinates[i + 1];
+        // Calculate the distance between the two points
+        const segmentLength = getDistanceBetweenPositions(coordA, coordB);
+        // If the current segment length plus the cumulative length
+        // extends the desired length of the resulting string
+        // then the line should be cut at the interpolation point
+        if (cumulativeLength + segmentLength >= length) {
+            const remainingLength = length - cumulativeLength;
+            const relativePositionOnSegment = remainingLength / segmentLength;
+            const interpolated = interpolatePositions(coordA, coordB, relativePositionOnSegment);
+            newLineStringCoordinates.push(coordA, interpolated);
+            return GeoJsonLineStringGeometrySchema.parse({
+                coordinates: newLineStringCoordinates,
+                type: 'LineString',
+            });
+        }
+        // Add the length of the current segment to the
+        // cumulative length of the line up until this point
+        cumulativeLength += segmentLength;
+        // If the cumulative length is already greater than the desired length
+        // then the line should be cut at this point. Break the loop now.
+        if (cumulativeLength > length)
+            break;
+        // If the cumulative length is not yet up to the desired length
+        // then the current point should be added to the new line
+        newLineStringCoordinates.push(coordA);
+    }
+    //
+    // If the entire line is shorter than the target length,
+    // then return the full line string as is.
+    newLineStringCoordinates.push(inputLineString.coordinates[inputLineString.coordinates.length - 1]);
+    return GeoJsonLineStringGeometrySchema.parse({
+        coordinates: newLineStringCoordinates,
+        type: 'LineString',
+    });
+}

package/dist/transformers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './chunk-line-by-distance.js';
+export * from './cut-line-at-length.js';

package/dist/transformers/index.js

@@ -0,0 +1,2 @@
+export * from './chunk-line-by-distance.js';
+export * from './cut-line-at-length.js';

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@tmlmobilidade/go-utils-geo",
+	"version": "20260828.1636.54",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/go-types-geo": "*",
+		"ngeohash": "0.6.4"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/ngeohash": "0.6.8",
+		"@types/node": "26.1.2",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}