@swissgeo/coordinates 1.0.0-rc.1 → 1.0.1

package/src/extentUtils.ts

@@ -0,0 +1,196 @@
+import { round } from '@swissgeo/numbers'
+import { bbox, bboxClip, bboxPolygon, buffer, point } from '@turf/turf'
+import proj4 from 'proj4'
+
+import type { SingleCoordinate } from '@/coordinatesUtils'
+import type { CoordinateSystem } from '@/proj'
+
+import { WGS84 } from '@/proj'
+
+export type FlatExtent = [number, number, number, number]
+export type NormalizedExtent = [[number, number], [number, number]]
+
+/**
+ * @param fromProj Current projection used to describe the extent
+ * @param toProj Target projection we want the extent be expressed in
+ * @param extent An extent, described as `[minx, miny, maxx, maxy].` or `[[minx, miny], [maxx,
+ *   maxy]]`
+ * @returns The reprojected extent
+ */
+export function projExtent<T extends FlatExtent | NormalizedExtent>(
+    fromProj: CoordinateSystem,
+    toProj: CoordinateSystem,
+    extent: T
+): T {
+    if (extent.length === 4) {
+        const bottomLeft = proj4(fromProj.epsg, toProj.epsg, [
+            extent[0],
+            extent[1],
+        ]) as SingleCoordinate
+        const topRight = proj4(fromProj.epsg, toProj.epsg, [
+            extent[2],
+            extent[3],
+        ]) as SingleCoordinate
+        return [...bottomLeft, ...topRight].map((value) => toProj.roundCoordinateValue(value)) as T
+    } else if (extent.length === 2) {
+        const bottomLeft = proj4(fromProj.epsg, toProj.epsg, extent[0]).map((value) =>
+            toProj.roundCoordinateValue(value)
+        )
+        const topRight = proj4(fromProj.epsg, toProj.epsg, extent[1]).map((value) =>
+            toProj.roundCoordinateValue(value)
+        )
+        return [bottomLeft, topRight] as T
+    }
+    return extent
+}
+
+/**
+ * Return an extent normalized to [[x, y], [x, y]] from a flat extent
+ *
+ * @param extent Extent to normalize
+ * @returns Extent in the form [[x, y], [x, y]]
+ */
+export function normalizeExtent(extent: FlatExtent | NormalizedExtent): NormalizedExtent {
+    let extentNormalized = extent
+    if (extent?.length === 4) {
+        // convert to the flat extent to [[x, y], [x, y]]
+        extentNormalized = [
+            [extent[0], extent[1]],
+            [extent[2], extent[3]],
+        ]
+    }
+    return extentNormalized as NormalizedExtent
+}
+
+/**
+ * Flatten extent
+ *
+ * @param extent Extent to flatten
+ * @returns Flatten extent in from [minx, miny, maxx, maxy]
+ */
+export function flattenExtent(extent: FlatExtent | NormalizedExtent): FlatExtent {
+    let flattenExtent = extent
+    if (extent?.length === 2) {
+        flattenExtent = [...extent[0], ...extent[1]]
+    }
+    return flattenExtent as FlatExtent
+}
+
+/**
+ * Get the intersection of the extent with the current projection, as a flatten extent expressed in
+ * the current projection
+ *
+ * @param extent Such as [minx, miny, maxx, maxy]. or [bottomLeft, topRight]
+ * @param extentProjection
+ * @param currentProjection
+ */
+export function getExtentIntersectionWithCurrentProjection(
+    extent: FlatExtent | NormalizedExtent,
+    extentProjection: CoordinateSystem,
+    currentProjection: CoordinateSystem
+): FlatExtent | undefined {
+    if (
+        (extent?.length !== 4 && extent?.length !== 2) ||
+        !extentProjection ||
+        !currentProjection ||
+        !currentProjection.bounds
+    ) {
+        return undefined
+    }
+    let currentProjectionAsExtentProjection: FlatExtent = currentProjection.bounds
+        .flatten as FlatExtent
+    if (extentProjection.epsg !== currentProjection.epsg) {
+        // We used to reproject the extent here, but there's problem arising if current projection is LV95 and
+        // the extent is going a little bit out of Switzerland.
+        // As LV95 is quite location-locked, the further we get, the bigger the mathematical errors start growing.
+        // So to counteract that, we transform the current projection bounds in the extent projection to do the comparison.
+        currentProjectionAsExtentProjection = projExtent(
+            currentProjection,
+            extentProjection,
+            currentProjectionAsExtentProjection
+        )
+    }
+    let intersectionOfExtents = bbox(bboxClip(bboxPolygon(currentProjectionAsExtentProjection), flattenExtent(extent)))
+
+    if (
+        !intersectionOfExtents || intersectionOfExtents.length !== 4 ||
+        intersectionOfExtents.every((value) => Math.abs(value) === Infinity)
+    ) {
+        return undefined
+    }
+    if (extentProjection.epsg !== currentProjection.epsg) {
+        // if we transformed the current projection extent above, we now need to output the correct proj
+        intersectionOfExtents = projExtent(extentProjection, currentProjection, intersectionOfExtents)
+    }
+
+    return intersectionOfExtents
+}
+
+export function getExtentCenter(extent: FlatExtent | NormalizedExtent): SingleCoordinate {
+    const [topLeft, bottomRight] = normalizeExtent(extent)
+    return [(topLeft[0] + bottomRight[0]) / 2, (topLeft[1] + bottomRight[1]) / 2]
+}
+
+interface ConfigCreatePixelExtentAround {
+    /**
+     * Number of pixels the extent should be (if s100 is given, a box of 100x100 pixels with the
+     * coordinate at its center will be returned)
+     */
+    size: number
+    /** Where the center of the "size" pixel(s) extent should be. */
+    coordinate: SingleCoordinate
+    /** Projection used to describe the coordinates */
+    projection: CoordinateSystem
+    /** Current map resolution, necessary to calculate how much distance "size" pixel(s) means. */
+    resolution: number
+    /** Tells if the extent's value should be rounded before being returned. Default is `false` */
+    rounded?: boolean
+}
+
+export function createPixelExtentAround(
+    config: ConfigCreatePixelExtentAround
+): FlatExtent | undefined {
+    const { size, coordinate, projection, resolution, rounded = false } = config
+    if (!size || !coordinate || !projection || !resolution) {
+        return undefined
+    }
+    let coordinatesWgs84 = coordinate
+    if (projection.epsg !== WGS84.epsg) {
+        coordinatesWgs84 = proj4(projection.epsg, WGS84.epsg, coordinate)
+    }
+    const bufferAround = buffer(
+        point(coordinatesWgs84),
+        // sphere of the wanted number of pixels as radius around the coordinate
+        size * resolution,
+        { units: 'meters' }
+    )
+    if (!bufferAround) {
+        return undefined
+    }
+    const extent: FlatExtent = projExtent(WGS84, projection, bbox(bufferAround) as FlatExtent)
+
+    if (rounded) {
+        return extent.map((value: number) => round(value)) as FlatExtent
+    }
+    return extent
+}
+
+export interface SwissGeoExtentUtils {
+    projExtent: typeof projExtent
+    normalizeExtent: typeof normalizeExtent
+    flattenExtent: typeof flattenExtent
+    getExtentIntersectionWithCurrentProjection: typeof getExtentIntersectionWithCurrentProjection
+    createPixelExtentAround: typeof createPixelExtentAround
+    getExtentCenter: typeof getExtentCenter
+}
+
+const extentUtils: SwissGeoExtentUtils = {
+    projExtent,
+    normalizeExtent,
+    flattenExtent,
+    getExtentIntersectionWithCurrentProjection,
+    createPixelExtentAround,
+    getExtentCenter,
+}
+export { extentUtils }
+export default extentUtils

package/src/index.ts

@@ -0,0 +1,29 @@
+/** @module swissgeo/coordinates */
+
+import proj4 from 'proj4'
+
+import type { SwissGeoCoordinatesUtils } from '@/coordinatesUtils'
+import type { SwissGeoExtentUtils } from '@/extentUtils'
+import type { SwissGeoCoordinateCRS } from '@/proj'
+
+import { coordinatesUtils } from '@/coordinatesUtils'
+import { extentUtils } from '@/extentUtils'
+import crs from '@/proj'
+import registerProj4 from '@/registerProj4'
+
+export * from '@/proj'
+export * from '@/registerProj4'
+export * from '@/coordinatesUtils'
+export * from '@/extentUtils'
+
+// registering local instance of proj4, needed for some @swissgeo/coordinates functions
+registerProj4(proj4)
+
+interface SwissGeoCoordinates extends SwissGeoCoordinateCRS {
+    coordinatesUtils: SwissGeoCoordinatesUtils
+    extentUtils: SwissGeoExtentUtils
+    registerProj4: typeof registerProj4
+}
+
+const coordinates: SwissGeoCoordinates = { ...crs, coordinatesUtils, extentUtils, registerProj4 }
+export default coordinates

package/src/ol.ts

@@ -0,0 +1,53 @@
+/** @module swissgeo/coordinates/ol */
+
+import type proj4 from 'proj4'
+
+import { View } from 'ol'
+import { register } from 'ol/proj/proj4'
+import WMTSTileGrid from 'ol/tilegrid/WMTS'
+
+import { LV95 } from '@/proj'
+import { LV95_RESOLUTIONS } from '@/proj/SwissCoordinateSystem'
+import registerProj4 from '@/registerProj4'
+
+export function registerSwissGeoProjections(proj4Instance: typeof proj4) {
+    registerProj4(proj4Instance)
+    register(proj4Instance)
+}
+
+function indexOfMaxResolution(layerMaxResolution: number): number {
+    const resolutionSteps = LV95.getResolutionSteps()
+    const matchResolutionStep = resolutionSteps.find(
+        (step) => step.resolution === layerMaxResolution
+    )
+    if (!matchResolutionStep) {
+        return resolutionSteps.length - 1
+    }
+    return resolutionSteps.indexOf(matchResolutionStep)
+}
+
+export function getLV95TileGrid(maxResolution = 0.25): WMTSTileGrid {
+    const maxResolutionIndex = indexOfMaxResolution(maxResolution)
+    let resolutionSteps = LV95.getResolutionSteps()
+    if (resolutionSteps.length > maxResolutionIndex) {
+        resolutionSteps = resolutionSteps.slice(0, maxResolutionIndex + 1)
+    }
+    return new WMTSTileGrid({
+        resolutions: resolutionSteps.map((step) => step.resolution),
+        origin: LV95.getTileOrigin(),
+        matrixIds: resolutionSteps.map((_, index) => index.toString()),
+        extent: LV95.bounds?.flatten,
+    })
+}
+
+export function getLV95View(): View {
+    return new View({
+        projection: LV95.epsg,
+        center: LV95.bounds.center,
+        zoom: LV95.getDefaultZoom(),
+        minResolution: LV95_RESOLUTIONS[LV95_RESOLUTIONS.length - 1],
+        resolutions: LV95_RESOLUTIONS,
+        extent: LV95.bounds.flatten,
+        constrainOnlyCenter: true,
+    })
+}

package/src/proj/CoordinateSystem.ts

@@ -0,0 +1,315 @@
+import { round } from '@swissgeo/numbers'
+import { earthRadius } from '@turf/turf'
+import proj4 from 'proj4'
+
+import type { SingleCoordinate } from '@/coordinatesUtils'
+import type { ResolutionStep } from '@/proj/types'
+
+import CoordinateSystemBounds from '@/proj/CoordinateSystemBounds'
+
+/**
+ * These are the zoom levels, for each projection, which give us a 1:25'000 ratio map.
+ *
+ * These variables are declared here, as the config.js import the LV95 coordinate system, and it
+ * could lead to initialization errors (even when initializing the constants before importing the
+ * class). Thus we declare them here, at the root class of the coordinates systems.
+ */
+export const STANDARD_ZOOM_LEVEL_1_25000_MAP: number = 15.5
+export const SWISS_ZOOM_LEVEL_1_25000_MAP: number = 8
+
+/**
+ * Resolution (pixel/meter) found at zoom level 0 while looking at the equator. This constant is
+ * used to calculate the resolution taking latitude into account. With Mercator projection, the
+ * deformation increases when latitude increases.
+ *
+ * Length of the Earth around its equator (in meters) / 256 pixels
+ *
+ * @see https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Resolution_and_Scale
+ * @see https://wiki.openstreetmap.org/wiki/Zoom_levels
+ */
+export const PIXEL_LENGTH_IN_KM_AT_ZOOM_ZERO_WITH_256PX_TILES: number =
+    (2 * Math.PI * earthRadius) / 256
+
+export interface CoordinateSystemProps {
+    /**
+     * EPSG:xxxx representation of this coordinate system, but only the numerical part (without the
+     * "EPSG:")
+     */
+    epsgNumber: number
+    /**
+     * Label to show users when they are dealing with this coordinate system (can be a translation
+     * key)
+     */
+    label: string
+    /**
+     * Name of this projection, if applicable, so that it can be tested against name in fields such
+     * as COG metadata parsing.
+     */
+    technicalName?: string
+    /**
+     * A string describing how proj4 should handle projection/reprojection of this coordinate
+     * system, in regard to WGS84. These matrices can be found on the EPSG website for each
+     * projection in the Export section, inside the PROJ.4 export type (can be directly accessed by
+     * adding .proj4 to the URL of one projection's page on the EPSG website, i.e.
+     * https://epsg.io/3857.proj4 for WebMercator)
+     */
+    proj4transformationMatrix: string
+    /**
+     * Bounds of this projection system, expressed as in its own coordinate system. These boundaries
+     * can also be found on the EPSG website, in the section "Projected bounds" of a projection's
+     * page. It is possible to specify a custom center to these bounds, so that the application
+     * starts at this custom center instead of the natural center (when no coordinates are specified
+     * at startup).
+     */
+    bounds?: CoordinateSystemBounds
+    /**
+     * A boolean variable indicating whether the Mercator projection pyramid is used.
+     *
+     * The Mercator projection pyramid is a specific spatial reference system commonly used in
+     * mapping and geographic information systems (GIS) applications.
+     *
+     * If set to `true`, it signifies that the system or dataset is leveraging this projection
+     * methodology.
+     *
+     * If set to `false`, it indicates that the dataset uses an alternative projection or tiling
+     * scheme.
+     */
+    usesMercatorPyramid: boolean
+}
+
+/**
+ * Representation of a coordinate system (or also called projection system) in the context of this
+ * application.
+ *
+ * These coordinate systems will be used to drive the mapping framework, helping it grasp which zoom
+ * level or resolution to show, where to start the view (with the center of bounds), how to handle a
+ * projection change, etc...
+ *
+ * @abstract
+ */
+export default abstract class CoordinateSystem {
+    /**
+     * EPSG:xxxx representation of this coordinate system, but only the numerical part (without the
+     * "EPSG:")
+     */
+    public readonly epsgNumber: number
+    /** EPSG:xxxx representation of this coordinate system */
+    public readonly epsg: string
+    /**
+     * Label to show users when they are dealing with this coordinate system (can be a translation
+     * key)
+     */
+    public readonly label: string
+    /**
+     * Name of this projection, if applicable, so that it can be tested against name in fields such
+     * as COG metadata parsing.
+     */
+    public readonly technicalName?: string
+    /**
+     * A string describing how proj4 should handle projection/reprojection of this coordinate
+     * system, in regard to WGS84. These matrices can be found on the EPSG website for each
+     * projection in the Export section, inside the PROJ.4 export type (can be directly accessed by
+     * adding .proj4 to the URL of one projection's page on the EPSG website, i.e.
+     * https://epsg.io/3857.proj4 for WebMercator)
+     */
+    public readonly proj4transformationMatrix: string
+    /**
+     * Bounds of this projection system, expressed as in its own coordinate system. These boundaries
+     * can also be found on the EPSG website, in the section "Projected bounds" of a projection's
+     * page. It is possible to specify a custom center to these bounds, so that the application
+     * starts at this custom center instead of the natural center (when no coordinates are specified
+     * at startup).
+     */
+    public readonly bounds?: CoordinateSystemBounds
+    /**
+     * A boolean variable indicating whether the Mercator projection pyramid is used.
+     *
+     * The Mercator projection pyramid is a specific spatial reference system commonly used in
+     * mapping and geographic information systems (GIS) applications.
+     *
+     * If set to `true`, it signifies that the system or dataset is leveraging this projection
+     * methodology.
+     *
+     * If set to `false`, it indicates that the dataset uses an alternative projection or tiling
+     * scheme.
+     */
+    public readonly usesMercatorPyramid: boolean
+
+    constructor(args: CoordinateSystemProps) {
+        const {
+            epsgNumber,
+            label,
+            proj4transformationMatrix,
+            bounds,
+            technicalName,
+            usesMercatorPyramid = false,
+        } = args
+        this.epsgNumber = epsgNumber
+        /**
+         * Full EPSG identifier used by most libraries (such as proj4, or OpenLayers)
+         *
+         * @type {`EPSG:${Number}`}
+         */
+        this.epsg = `EPSG:${epsgNumber}`
+        this.label = label
+        this.proj4transformationMatrix = proj4transformationMatrix
+        this.bounds = bounds
+        this.technicalName = technicalName
+        this.usesMercatorPyramid = usesMercatorPyramid
+    }
+
+    /**
+     * Transforms the bounds of this coordinates system to be expressed in the wanted coordinate
+     * system
+     *
+     * If the coordinate system is invalid, or if bounds are not defined, it will return null
+     *
+     * @param {CoordinateSystem} coordinateSystem The target coordinate system we want bounds
+     *   expressed in
+     * @returns {CoordinateSystemBounds | undefined} Bounds, expressed in the coordinate system, or
+     *   undefined if bounds are undefined or the coordinate system is invalid
+     */
+    getBoundsAs(coordinateSystem: CoordinateSystem): CoordinateSystemBounds | undefined {
+        if (this.bounds) {
+            if (coordinateSystem.epsg === this.epsg) {
+                return this.bounds
+            }
+            const newBottomLeft = proj4(this.epsg, coordinateSystem.epsg, this.bounds.bottomLeft)
+            const newTopRight = proj4(this.epsg, coordinateSystem.epsg, this.bounds.topRight)
+            let customCenter: SingleCoordinate | undefined
+            if (this.bounds.customCenter) {
+                customCenter = proj4(this.epsg, coordinateSystem.epsg, this.bounds.customCenter)
+            }
+            return new CoordinateSystemBounds({
+                lowerX: newBottomLeft[0],
+                lowerY: newBottomLeft[1],
+                upperX: newTopRight[0],
+                upperY: newTopRight[1],
+                customCenter,
+            })
+        }
+        return
+    }
+
+    isInBounds(x: number, y: number): boolean
+    isInBounds(coordinate: SingleCoordinate): boolean
+
+    /**
+     * Tells if a coordinate is in bound of this coordinate system.
+     *
+     * Will return false if no bounds are defined for this coordinate system
+     */
+    isInBounds(xOrCoordinate: number | SingleCoordinate, y?: number): boolean {
+        if (!this.bounds) {
+            return false
+        }
+        if (typeof xOrCoordinate === 'number') {
+            return this.bounds.isInBounds(xOrCoordinate, y!)
+        }
+        return this.bounds.isInBounds(xOrCoordinate[0], xOrCoordinate[1])
+    }
+
+    /**
+     * @abstract
+     * @returns The Index in the resolution list where the 1:25000 zoom level is
+     */
+    abstract get1_25000ZoomLevel(): number
+
+    /**
+     * @abstract
+     * @returns The default zoom to use when starting the map in this coordinate system (if none are
+     *   set so far)
+     */
+    abstract getDefaultZoom(): number
+
+    /**
+     * Rounds a zoom level.
+     *
+     * You can, by overwriting this function, add custom zoom level roundings or similar function in
+     * your custom coordinate systems.
+     *
+     * @param zoom A zoom level in this coordinate system
+     * @returns The given zoom level after rounding
+     */
+    roundZoomLevel(zoom: number): number {
+        return round(zoom, 3)
+    }
+
+    /**
+     * Returns the corresponding resolution to the given zoom level and center (some coordinate
+     * system must take some deformation into account the further north we are)
+     *
+     * @abstract
+     * @param zoom A zoom level
+     * @param center The current center of view, expressed with this coordinate system
+     * @returns The resolution at the given zoom level, in the context of this coordinate system
+     */
+    abstract getResolutionForZoomAndCenter(zoom: number, center: SingleCoordinate): number
+
+    /**
+     * Returns the zoom level to match the given resolution and center (some coordinate system must
+     * take some deformation into account the further north we are)
+     *
+     * @abstract
+     * @param resolution The resolution of the map, expressed in meter per pixel
+     * @param center The current center of view, expressed in this coordinate system
+     * @returns The corresponding zoom level, in the context of this coordinate system
+     */
+    abstract getZoomForResolutionAndCenter(resolution: number, center: SingleCoordinate): number
+
+    /**
+     * Returns a rounded value of a coordinate value, in the context of this coordinate system. This
+     * enables us to decide how many decimal points we want to keep for numbers after calculation
+     * within this coordinate system (no need to keep values that are irrelevant to precision for
+     * most maps, such as below 1cm)
+     *
+     * @abstract
+     * @param {Number} value A value to be rounded
+     * @returns {Number} The rounded value, with desired remaining decimal point for this coordinate
+     *   system
+     */
+    abstract roundCoordinateValue(value: number): number
+
+    /**
+     * A (descending) list of all the available resolution steps for this coordinate system. If this
+     * is not the behavior you want, you have to override this function.
+     */
+    getResolutionSteps(latitude?: number): ResolutionStep[] {
+        if (!this.bounds) {
+            return []
+        }
+        const zoom0PixelSizeInMeters = PIXEL_LENGTH_IN_KM_AT_ZOOM_ZERO_WITH_256PX_TILES
+        const resolutions: ResolutionStep[] = []
+        const latInRad = ((latitude ?? 0) * Math.PI) / 180.0
+        for (let z = 0; z < 21; ++z) {
+            resolutions.push({
+                resolution: (zoom0PixelSizeInMeters * Math.cos(latInRad)) / Math.pow(2, z),
+                zoom: z,
+            })
+        }
+        return resolutions
+    }
+
+    /**
+     * The origin to use as anchor for tile coordinate calculations. It will return the bound's
+     * [lowerX, upperY] as default value (meaning the top-left corner of bounds). If this is not the
+     * behavior you want, you have to override this function.
+     *
+     * If no bounds are defined, it will return [0, 0]
+     */
+    getTileOrigin(): SingleCoordinate {
+        return this.bounds?.topLeft ?? [0, 0]
+    }
+
+    /**
+     * List of matrix identifiers for this coordinate system. If this is not the behavior you want,
+     * you have to override this function.
+     */
+    getMatrixIds(): number[] {
+        const matrixIds = []
+        for (let z = 0; z < this.getResolutionSteps().length; ++z) {
+            matrixIds[z] = z
+        }
+        return matrixIds
+    }
+}