@tmlmobilidade/geo 20251202.1817.5

package/dist/chunk-line.d.ts

@@ -0,0 +1,10 @@
+import { type LineString } from 'geojson';
+/**
+ * This function takes a GeoJSON LineString and splits it into equal chunks of a given precision
+ * using a custom implementation. This is useful to ensure greater precision when calculating the nearest
+ * point on a path, as some paths may have very long "straight" segments with only two points.
+ * @param line The LineString to be split into chunks.
+ * @param segmentLength The length of each segment in meters.
+ * @returns A GeoJSON LineString with the split chunks.
+ */
+export declare function chunkLineByDistance(line: LineString, segmentLength: number): LineString;

package/dist/chunk-line.js

@@ -0,0 +1,75 @@
+/*  * */
+import { toLineStringFromPositions } from './conversions.js';
+import { getDistanceBetweenPositions, interpolatePositions } from './measurements.js';
+/**
+ * This function takes a GeoJSON LineString and splits it into equal chunks of a given precision
+ * using a custom implementation. This is useful to ensure greater precision when calculating the nearest
+ * point on a path, as some paths may have very long "straight" segments with only two points.
+ * @param line The LineString to be split into chunks.
+ * @param segmentLength The length of each segment in meters.
+ * @returns A GeoJSON LineString with the split chunks.
+ */
+export function chunkLineByDistance(line, segmentLength) {
+    //
+    //
+    // Exit early if the line is empty
+    if (line.coordinates.length < 2)
+        return line;
+    //
+    // Setup variables to hold the coordinates of the chunked line
+    const chunkedLineCoordinates = [];
+    //
+    // Add the first point to the chunked line
+    chunkedLineCoordinates.push(line.coordinates[0]);
+    //
+    // Loop through the coordinates of the line
+    for (let i = 0; i < line.coordinates.length - 1; i++) {
+        // Extract the coordinates of the current and the next point
+        const [lngA, latA] = line.coordinates[i];
+        const [lngB, latB] = line.coordinates[i + 1];
+        // Calculate the length of the current segment
+        const currentSegmentLength = getDistanceBetweenPositions(line.coordinates[i], line.coordinates[i + 1]);
+        // If the current segment length is greater than the desired segment length
+        if (currentSegmentLength > segmentLength) {
+            // Calculate the number of segments needed to fill the current segment
+            const segmentsNeeded = Math.floor(currentSegmentLength / segmentLength);
+            // Calculate the length of each chunked segment
+            const chunkedSegmentLength = currentSegmentLength / segmentsNeeded;
+            // Calculate the remaining distance to be filled
+            let remainingDist = segmentLength;
+            // Loop through the segments needed
+            for (let j = 0; j < segmentsNeeded; j++) {
+                // Calculate the ratio of the segment
+                const ratio = remainingDist / chunkedSegmentLength;
+                // Interpolate the coordinates of the segment
+                const interpolated = interpolatePositions([lngA, latA], [lngB, latB], ratio);
+                // Add the interpolated coordinates to the chunked line
+                chunkedLineCoordinates.push(interpolated);
+                // Update the remaining distance to be filled
+                remainingDist -= chunkedSegmentLength;
+            }
+            // Add the last point of the segment to the chunked line
+            const lastPoint = line.coordinates[i + 1];
+            if (chunkedLineCoordinates[chunkedLineCoordinates.length - 1][0] !== lastPoint[0] || chunkedLineCoordinates[chunkedLineCoordinates.length - 1][1] !== lastPoint[1]) {
+                chunkedLineCoordinates.push(lastPoint);
+            }
+        }
+        else {
+            // If the current segment length is less than or equal to the desired segment length
+            // Add the current point to the chunked line
+            if (chunkedLineCoordinates[chunkedLineCoordinates.length - 1][0] !== line.coordinates[i][0] || chunkedLineCoordinates[chunkedLineCoordinates.length - 1][1] !== line.coordinates[i][1]) {
+                chunkedLineCoordinates.push(line.coordinates[i]);
+            }
+        }
+    }
+    //
+    // Add the last point of the line to the chunked line
+    const lastPoint = line.coordinates[line.coordinates.length - 1];
+    if (chunkedLineCoordinates[chunkedLineCoordinates.length - 1][0] !== lastPoint[0] || chunkedLineCoordinates[chunkedLineCoordinates.length - 1][1] !== lastPoint[1]) {
+        chunkedLineCoordinates.push(lastPoint);
+    }
+    //
+    // Return the chunked line as a GeoJSON LineString
+    return toLineStringFromPositions(chunkedLineCoordinates);
+    //
+}

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Earth's radius in meters.
+ */
+export declare const EARTH_RADIUS = 6371000;
+/**
+ * Approximate number of meters per degree of latitude.
+ */
+export declare const METERS_PER_DEGREE = 111320;

package/dist/constants.js

@@ -0,0 +1,8 @@
+/**
+ * Earth's radius in meters.
+ */
+export const EARTH_RADIUS = 6_371_000;
+/**
+ * Approximate number of meters per degree of latitude.
+ */
+export const METERS_PER_DEGREE = 111_320;

package/dist/conversions.d.ts

@@ -0,0 +1,36 @@
+import { type HashedShape } from '@tmlmobilidade/types';
+import { type Feature, type GeoJsonProperties, type LineString, type Point, type Polygon, type Position } from 'geojson';
+/**
+ * Converts a list of GTFS shape points into a GeoJSON LineString.
+ * @param hashedShape The hashed shape containing GTFS shape points.
+ * @returns GeoJSON LineString feature
+ */
+export declare function toLineStringFromHashedShape(hashedShape: HashedShape): LineString;
+/**
+ * Creates a new LineString from the given set of coordinates.
+ * @param positions An array of coordinate positions for the LineString. Defaults to an empty array.
+ * @returns A GeoJSON LineString with the specified coordinates.
+ */
+export declare function toLineStringFromPositions(positions?: Position[]): LineString;
+/**
+ * Creates a new Point from the given coordinates.
+ * @param position A coordinate position for the Point. Defaults to an empty array.
+ * @returns A GeoJSON Point with the specified coordinates.
+ */
+export declare function toPointFromPositions(position?: Position): Point;
+/**
+ * Creates a new Feature from the given object and properties.
+ * @param object The object to convert to a Feature. Can be a LineString, Point, or Polygon.
+ * @param properties Optional properties to attach to the Feature. Defaults to an empty object.
+ * @returns A GeoJSON Feature with the specified object and properties.
+ */
+export declare function toFeatureFromObject<T extends LineString | Point | Polygon>(object: T, properties?: GeoJsonProperties): Feature<T>;
+/**
+ * Converts a value in kilometers or meters to meters based on a ballpark value.
+ * If the ballpark value is greater than 800 meters, it assumes the value is in meters.
+ * Otherwise, it assumes the value is in kilometers and converts it to meters.
+ * @param value The value to be converted, which can be a number or a string that can be converted to a number.
+ * @param ballpark The ballpark value to determine the unit of the value, which can also be a number or a string that can be converted to a number.
+ * @returns The converted value in meters.
+ */
+export declare function toMetersFromKilometersOrMeters(value: number | string, ballpark: number | string): number;

package/dist/conversions.js

@@ -0,0 +1,79 @@
+/* * */
+/**
+ * Converts a list of GTFS shape points into a GeoJSON LineString.
+ * @param hashedShape The hashed shape containing GTFS shape points.
+ * @returns GeoJSON LineString feature
+ */
+export function toLineStringFromHashedShape(hashedShape) {
+    // Exit if no points are provided
+    if (!hashedShape.points?.length)
+        return toLineStringFromPositions([]);
+    // Sort points by shape_pt_sequence
+    const sortedPoints = [...hashedShape.points].sort((a, b) => a.shape_pt_sequence - b.shape_pt_sequence);
+    // Create a LineString feature
+    const coordinates = sortedPoints.map(p => [Number(p.shape_pt_lon), Number(p.shape_pt_lat)]);
+    // Return the LineString feature
+    return toLineStringFromPositions(coordinates);
+}
+/**
+ * Creates a new LineString from the given set of coordinates.
+ * @param positions An array of coordinate positions for the LineString. Defaults to an empty array.
+ * @returns A GeoJSON LineString with the specified coordinates.
+ */
+export function toLineStringFromPositions(positions = []) {
+    return {
+        coordinates: positions,
+        type: 'LineString',
+    };
+}
+/**
+ * Creates a new Point from the given coordinates.
+ * @param position A coordinate position for the Point. Defaults to an empty array.
+ * @returns A GeoJSON Point with the specified coordinates.
+ */
+export function toPointFromPositions(position = []) {
+    return {
+        coordinates: position,
+        type: 'Point',
+    };
+}
+/**
+ * Creates a new Feature from the given object and properties.
+ * @param object The object to convert to a Feature. Can be a LineString, Point, or Polygon.
+ * @param properties Optional properties to attach to the Feature. Defaults to an empty object.
+ * @returns A GeoJSON Feature with the specified object and properties.
+ */
+export function toFeatureFromObject(object, properties) {
+    return {
+        geometry: object,
+        properties: properties || {},
+        type: 'Feature',
+    };
+}
+/**
+ * Converts a value in kilometers or meters to meters based on a ballpark value.
+ * If the ballpark value is greater than 800 meters, it assumes the value is in meters.
+ * Otherwise, it assumes the value is in kilometers and converts it to meters.
+ * @param value The value to be converted, which can be a number or a string that can be converted to a number.
+ * @param ballpark The ballpark value to determine the unit of the value, which can also be a number or a string that can be converted to a number.
+ * @returns The converted value in meters.
+ */
+export function toMetersFromKilometersOrMeters(value, ballpark) {
+    //
+    const BALLPARK_THRESHOLD = 800; // meters
+    const valueAsNumber = Number(value);
+    const ballparkAsNumber = Number(ballpark);
+    if (Number.isNaN(valueAsNumber))
+        throw new Error('Value must be a number or a string that can be converted to a number.');
+    if (Number.isNaN(ballparkAsNumber))
+        throw new Error('Ballpark must be a number or a string that can be converted to a number.');
+    // If the ballpark is bigger than 800, then the value is in meters
+    // Otherwise, the value is in kilometers. This is because it is unlikely
+    // that a trip will be smaller than 800 meters, and longer than 800 kilometers.
+    if (ballparkAsNumber > BALLPARK_THRESHOLD) {
+        return valueAsNumber;
+    }
+    return valueAsNumber * 1000;
+    //
+}
+;

package/dist/coordinates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Checks if the given latitude value is valid given Portugal limits.
+ * @param value The latitude value to check.
+ * @returns The clamped latitude value if valid, false otherwise.
+ */
+export declare function isValidLatitude(value: number): false | number;
+/**
+ * Checks if the given longitude value is valid given Portugal limits.
+ * @param value The longitude value to check.
+ * @returns The clamped longitude value if valid, false otherwise.
+ */
+export declare function isValidLongitude(value: number): false | number;
+/**
+ * Checks if the given latitude and longitude values form a valid coordinate pair.
+ * @param lat The latitude value to check.
+ * @param lng The longitude value to check.
+ * @returns True if the coordinate pair is valid, false otherwise.
+ */
+export declare function isValidCoordinatePair(lat: number, lng: number): boolean;
+/**
+ * Clamps a coordinate value to 6 decimal places.
+ * @param value The coordinate value to clamp.
+ * @returns The clamped coordinate value.
+ */
+export declare function clampCoordinate(value: number): number;
+/**
+ * Parses a coordinate pair string in the following formats:
+ * - `lat, lng`
+ * - `lat lng` (with a space or a tab)
+ * @param input The coordinate pair string to parse.
+ * @param clamp Whether to clamp the latitude and longitude values to 6 decimal places.
+ * @returns The parsed coordinates as an object, or null if the input is invalid.
+ */
+export declare const parseCoordinatePairString: (input: string, clamp?: boolean) => null | {
+    lat: number;
+    lng: number;
+};

package/dist/coordinates.js

@@ -0,0 +1,64 @@
+/* * */
+/**
+ * Checks if the given latitude value is valid given Portugal limits.
+ * @param value The latitude value to check.
+ * @returns The clamped latitude value if valid, false otherwise.
+ */
+export function isValidLatitude(value) {
+    const hasValue = value !== undefined && value !== null;
+    const isWithinPortugal = value >= 36.9 && value <= 42.0;
+    if (!hasValue || !isWithinPortugal)
+        return false;
+    return clampCoordinate(value);
+}
+/**
+ * Checks if the given longitude value is valid given Portugal limits.
+ * @param value The longitude value to check.
+ * @returns The clamped longitude value if valid, false otherwise.
+ */
+export function isValidLongitude(value) {
+    const hasValue = value !== undefined && value !== null;
+    const isWithinPortugal = value >= -9.5 && value <= -6.0;
+    if (!hasValue || !isWithinPortugal)
+        return false;
+    return clampCoordinate(value);
+}
+/**
+ * Checks if the given latitude and longitude values form a valid coordinate pair.
+ * @param lat The latitude value to check.
+ * @param lng The longitude value to check.
+ * @returns True if the coordinate pair is valid, false otherwise.
+ */
+export function isValidCoordinatePair(lat, lng) {
+    const isValidLat = isValidLatitude(lat);
+    const isValidLng = isValidLongitude(lng);
+    return !!isValidLat && !!isValidLng;
+}
+/**
+ * Clamps a coordinate value to 6 decimal places.
+ * @param value The coordinate value to clamp.
+ * @returns The clamped coordinate value.
+ */
+export function clampCoordinate(value) {
+    return parseFloat(value.toFixed(6));
+}
+/**
+ * Parses a coordinate pair string in the following formats:
+ * - `lat, lng`
+ * - `lat lng` (with a space or a tab)
+ * @param input The coordinate pair string to parse.
+ * @param clamp Whether to clamp the latitude and longitude values to 6 decimal places.
+ * @returns The parsed coordinates as an object, or null if the input is invalid.
+ */
+export const parseCoordinatePairString = (input, clamp = true) => {
+    const regex = /^\s*([+-]?\d+(?:\.\d+)?)\s*(?:,|\s)\s*([+-]?\d+(?:\.\d+)?)\s*$/;
+    const match = input.match(regex);
+    if (!match)
+        return null;
+    const lat = parseFloat(match[1]);
+    const lng = parseFloat(match[2]);
+    if (clamp)
+        return isValidCoordinatePair(lat, lng) ? { lat: clampCoordinate(lat), lng: clampCoordinate(lng) } : null;
+    else
+        return isValidCoordinatePair(lat, lng) ? { lat, lng } : null;
+};

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

@@ -0,0 +1,10 @@
+import { type LineString } from 'geojson';
+/**
+ * Cuts a LineString at a specified length.
+ * If the line is shorter than the specified length, it returns the entire line.
+ * @param line 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(line: LineString, length: number, direction?: 'forward' | 'reversed'): LineString;

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

@@ -0,0 +1,68 @@
+/* * */
+import { toLineStringFromPositions } from './conversions.js';
+import { getDistanceBetweenPositions, interpolatePositions } from './measurements.js';
+/**
+ * Cuts a LineString at a specified length.
+ * If the line is shorter than the specified length, it returns the entire line.
+ * @param line 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(line, length, direction = 'forward') {
+    //
+    //
+    // Return the line if it is empty
+    if (line.coordinates.length < 2) {
+        return line;
+    }
+    //
+    // Return an empty line if the length is equal to 0
+    if (length <= 0) {
+        return toLineStringFromPositions([]);
+    }
+    //
+    // Reverse the line if the direction is 'reversed'
+    if (direction === 'reversed') {
+        line.coordinates = line.coordinates.slice().reverse();
+    }
+    //
+    // Hold the cumulative distance between points
+    // and the coordinates of the new line
+    let cumulativeLength = 0;
+    const newLinePositions = [];
+    //
+    // Loop through the coordinates of the line
+    for (let i = 0; i < line.coordinates.length - 1; i++) {
+        // Get the coordinates of the current and the next point
+        const coordA = line.coordinates[i];
+        const coordB = line.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);
+            newLinePositions.push(coordA, interpolated);
+            return toLineStringFromPositions(newLinePositions);
+        }
+        // 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
+        newLinePositions.push(coordA);
+    }
+    //
+    // If the entire line is shorter than the target length
+    newLinePositions.push(line.coordinates[line.coordinates.length - 1]);
+    return toLineStringFromPositions(newLinePositions);
+    //
+}

package/dist/geojson-collections.d.ts

@@ -0,0 +1,11 @@
+import { type Feature, type FeatureCollection, type Geometry } from 'geojson';
+/**
+ * Creates a base GeoJSON feature collection for the given feature type.
+ * @returns A base GeoJSON feature collection with an empty features array.
+ */
+export declare function getBaseGeoJsonFeature<T extends Geometry, K>(type: T['type'], properties?: K): Feature<T, K>;
+/**
+ * Creates a base GeoJSON feature collection for the given feature type.
+ * @returns A base GeoJSON feature collection with an empty features array.
+ */
+export declare function getBaseGeoJsonFeatureCollection<T extends Geometry, K>(): FeatureCollection<T, K>;

package/dist/geojson-collections.js

@@ -0,0 +1,29 @@
+/* * */
+/**
+ * Creates a base GeoJSON feature collection for the given feature type.
+ * @returns A base GeoJSON feature collection with an empty features array.
+ */
+export function getBaseGeoJsonFeature(type, properties) {
+    const emptyGeometries = {
+        GeometryCollection: { geometries: [], type: 'GeometryCollection' },
+        LineString: { coordinates: [], type: 'LineString' },
+        MultiLineString: { coordinates: [], type: 'MultiLineString' },
+        MultiPoint: { coordinates: [], type: 'MultiPoint' },
+        MultiPolygon: { coordinates: [], type: 'MultiPolygon' },
+        Point: { coordinates: [0, 0], type: 'Point' },
+        Polygon: { coordinates: [], type: 'Polygon' },
+    };
+    return {
+        geometry: emptyGeometries[type],
+        properties: (properties ?? {}),
+        type: 'Feature',
+    };
+}
+/**
+ * Creates a base GeoJSON feature collection for the given feature type.
+ * @returns A base GeoJSON feature collection with an empty features array.
+ */
+export function getBaseGeoJsonFeatureCollection() {
+    return Object.assign({ features: [], type: 'FeatureCollection' });
+}
+;

package/dist/get-geofence-on-point.d.ts

@@ -0,0 +1,17 @@
+import { type Feature, type Point, type Polygon } from 'geojson';
+/**
+ * Create a geofence around a given point with a given radius in meters (default is 50 meters).
+ * @param point A GeoJSON Point representation of the point to create the geofence around.
+ * @param radius The distance in meters to calculate the geofence radius. Default is 50 meters.
+ * @param steps The number of steps to use for the buffer. Default is 16.
+ * @returns The GeoJSON Feature of a Polygon.
+ */
+export declare function getGeofenceOnPoint(point: Feature<Point>, radius?: number, steps?: number): Feature<Polygon>;
+/**
+ * Create a geofence around a given position with a given radius in meters (default is 50 meters).
+ * @param position A tuple representing the coordinates of the point to create the geofence around.
+ * @param radius The distance in meters to calculate the geofence radius. Default is 50 meters.
+ * @param steps The number of steps to use for the buffer. Default is 16.
+ * @returns The GeoJSON Feature of a Polygon.
+ */
+export declare function getGeofenceOnPosition(position: [number, number], radius?: number, steps?: number): Feature<Polygon>;

package/dist/get-geofence-on-point.js

@@ -0,0 +1,46 @@
+/* * */
+import { EARTH_RADIUS } from './constants.js';
+import { toFeatureFromObject, toPointFromPositions } from './conversions.js';
+import { polygon } from '@turf/turf';
+/**
+ * Create a geofence around a given point with a given radius in meters (default is 50 meters).
+ * @param point A GeoJSON Point representation of the point to create the geofence around.
+ * @param radius The distance in meters to calculate the geofence radius. Default is 50 meters.
+ * @param steps The number of steps to use for the buffer. Default is 16.
+ * @returns The GeoJSON Feature of a Polygon.
+ */
+export function getGeofenceOnPoint(point, radius = 50, steps = 16) {
+    // Extract the center coordinates from the point
+    const [centerLon, centerLat] = point.geometry.coordinates;
+    // Set the angle size based on the number of steps
+    const angleStep = (2 * Math.PI) / steps;
+    // Set an empty array to hold the coordinates of the polygon vertices
+    const coords = [];
+    // Calculate the coordinates of the polygon vertices
+    for (let i = 0; i < steps; i++) {
+        const angle = i * angleStep;
+        const dx = radius * Math.cos(angle);
+        const dy = radius * Math.sin(angle);
+        const newLat = centerLat + (dy / EARTH_RADIUS) * (180 / Math.PI);
+        const newLng = centerLon + (dx / (EARTH_RADIUS * Math.cos((centerLat * Math.PI) / 180))) * (180 / Math.PI);
+        coords.push([newLng, newLat]);
+    }
+    // Close the polygon by adding the first coordinate to the end
+    coords.push(coords[0]);
+    // Return the polygon feature
+    return polygon([coords]);
+}
+/**
+ * Create a geofence around a given position with a given radius in meters (default is 50 meters).
+ * @param position A tuple representing the coordinates of the point to create the geofence around.
+ * @param radius The distance in meters to calculate the geofence radius. Default is 50 meters.
+ * @param steps The number of steps to use for the buffer. Default is 16.
+ * @returns The GeoJSON Feature of a Polygon.
+ */
+export function getGeofenceOnPosition(position, radius = 50, steps = 16) {
+    // Create a point feature from the coordinates
+    const newPoint = toPointFromPositions(position);
+    const newFeature = toFeatureFromObject(newPoint);
+    // Call the getGeofenceOnPoint function to create the geofence
+    return getGeofenceOnPoint(newFeature, radius, steps);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './chunk-line.js';
+export * from './constants.js';
+export * from './conversions.js';
+export * from './coordinates.js';
+export * from './cut-line-at-length.js';
+export * from './geojson-collections.js';
+export * from './get-geofence-on-point.js';
+export * from './is-point-in-polygon.js';
+export * from './measurements.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './chunk-line.js';
+export * from './constants.js';
+export * from './conversions.js';
+export * from './coordinates.js';
+export * from './cut-line-at-length.js';
+export * from './geojson-collections.js';
+export * from './get-geofence-on-point.js';
+export * from './is-point-in-polygon.js';
+export * from './measurements.js';

package/dist/is-point-in-polygon.d.ts

@@ -0,0 +1,9 @@
+import { type Feature, type Point, type Polygon, type Position } from 'geojson';
+/**
+ * Check if a point is inside a polygon using the ray-casting algorithm.
+ * @param point A GeoJSON Point representation of the point to check.
+ * @param geofence A GeoJSON Polygon representation of the geofence.
+ * @returns A boolean indicating if the point is inside the polygon.
+ * @see https://en.wikipedia.org/wiki/Point_in_polygon#Ray_casting_algorithm
+ */
+export declare function isPointInPolygon(point: Feature<Point> | Position, polygon: Feature<Polygon>): boolean;

package/dist/is-point-in-polygon.js

@@ -0,0 +1,37 @@
+/* * */
+/**
+ * Check if a point is inside a polygon using the ray-casting algorithm.
+ * @param point A GeoJSON Point representation of the point to check.
+ * @param geofence A GeoJSON Polygon representation of the geofence.
+ * @returns A boolean indicating if the point is inside the polygon.
+ * @see https://en.wikipedia.org/wiki/Point_in_polygon#Ray_casting_algorithm
+ */
+export function isPointInPolygon(point, polygon) {
+    //
+    const pt = Array.isArray(point) ? point : point.geometry.coordinates;
+    const [x, y] = pt;
+    const ring = polygon.geometry.coordinates[0]; // Outer ring only
+    let inside = false;
+    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+        const xi = ring[i][0], yi = ring[i][1];
+        const xj = ring[j][0], yj = ring[j][1];
+        const intersectsVertically = (yi > y) !== (yj > y);
+        const edgeSlope = (xj - xi) / (yj - yi + 1e-10); // slope of the edge
+        const xIntersect = edgeSlope * (y - yi) + xi;
+        const isToRight = x < xIntersect;
+        const intersects = intersectsVertically && isToRight;
+        if (intersects)
+            inside = !inside;
+    }
+    return inside;
+}
+// /**
+//  * Check if a point is inside a geofence polygon.
+//  * @param point A GeoJSON Point representation of the point to check.
+//  * @param geofence A GeoJSON Polygon representation of the geofence.
+//  * @returns A boolean indicating if the point is inside the geofence polygon.
+//  */
+// export function isInsideGeofence(point: Position, geofence: Feature<Polygon>): boolean {
+// 	// Check if the point is inside the polygon
+// 	return isPointInPolygon(point, geofence);
+// }

package/dist/measurements.d.ts

@@ -0,0 +1,42 @@
+import { type Point, type Position } from 'geojson';
+/**
+ * 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: Point, pointB: Point): 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: Position, positionB: Position): number;
+/**
+ * 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: Point, pointB: Point, ratio: number): 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 declare function interpolatePositions(positionA: Position, positionB: Position, ratio: number): Position;

package/dist/measurements.js

@@ -0,0 +1,71 @@
+/* * */
+import { METERS_PER_DEGREE } from './constants.js';
+import { toPointFromPositions } from './conversions.js';
+/**
+ * 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);
+}
+/**
+ * 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 toPointFromPositions(result);
+}
+/**
+ * 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 = positionA[0] + (positionB[0] - positionA[0]) * ratio;
+    const lat = positionA[1] + (positionB[1] - positionA[1]) * ratio;
+    // Preserve elevation if present
+    if (positionA.length > 2 && positionB.length > 2) {
+        const alt = positionA[2] + (positionB[2] - positionA[2]) * ratio;
+        return [lng, lat, alt];
+    }
+    // Return the interpolated position
+    return [lng, lat];
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@tmlmobilidade/geo",
+	"version": "20251202.1817.5",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://github.com/tmlmobilidade/go#readme",
+	"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": {
+		"@turf/turf": "7.3.1"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@tmlmobilidade/types": "*",
+		"@types/geojson": "7946.0.16",
+		"@types/node": "24.10.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.0",
+		"typescript": "5.9.3"
+	}
+}