From d467a290aa4bbb21fb0ba6d27b793876e494100b Mon Sep 17 00:00:00 2001 From: Bouillaguet Quentin Date: Sat, 16 Nov 2024 10:25:02 +0100 Subject: [PATCH] chore(Crs): update and refine documentation --- src/Core/Geographic/Crs.ts | 83 ++++++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 26 deletions(-) diff --git a/src/Core/Geographic/Crs.ts b/src/Core/Geographic/Crs.ts index b5513d2ce2..311967dc35 100644 --- a/src/Core/Geographic/Crs.ts +++ b/src/Core/Geographic/Crs.ts @@ -5,7 +5,9 @@ import type { ProjectionDefinition } from 'proj4'; proj4.defs('EPSG:4978', '+proj=geocent +datum=WGS84 +units=m +no_defs'); /** - * A projection as a CRS identifier string. + * A projection as a CRS identifier string. This identifier references a + * projection definition previously defined with + * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections). */ export type ProjectionLike = string; @@ -19,19 +21,31 @@ function mustBeString(crs: string) { } } +/** + * Checks that a given CRS identifier follows the TMS:XXXX format. + * @internal + * + * @param crs - The CRS identifier string. + */ export function isTms(crs: string) { return isString(crs) && crs.startsWith('TMS'); } +/** + * Checks that a given CRS identifier follows the EPSG:XXXX format. + * @internal + * + * @param crs - The CRS identifier string. + */ export function isEpsg(crs: string) { return isString(crs) && crs.startsWith('EPSG'); } /** - * Format crs to tile matrix set notation: TMS:XXXX. + * Converts the input to the tile matrix set notation: TMS:XXXX. + * @internal * - * @param crs - The crs to format - * @returns formated crs + * @param crs - The input to format. */ export function formatToTms(crs: string) { mustBeString(crs); @@ -39,10 +53,10 @@ export function formatToTms(crs: string) { } /** - * Format crs to European Petroleum Survey Group notation: EPSG:XXXX. + * Converts the input to European Petroleum Survey Group notation: EPSG:XXXX. + * @internal * - * @param crs - The crs to format - * @returns formated crs + * @param crs - The input to format. */ export function formatToEPSG(crs: string) { mustBeString(crs); @@ -50,18 +64,33 @@ export function formatToEPSG(crs: string) { } /** - * Units that can be used for a CRS. + * System units supported for a coordinate system. See + * [proj](https://proj4.org/en/9.5/operations/conversions/unitconvert.html#angular-units). + * Note that only degree and meters units are supported for now. */ export const UNIT = { + /** + * Angular unit in degree. + */ DEGREE: 1, + /** + * Distance unit in meter. + */ METER: 2, } as const; +/** + * @internal + */ export const tms_3857 = 'TMS:3857'; +/** + * @internal + */ export const tms_4326 = 'TMS:4326'; /** - * Is the CRS EPSG:4326? + * Checks that the CRS is EPSG:4326. + * @internal * * @param crs - The CRS to test. */ @@ -84,9 +113,9 @@ function unitFromProj4Unit(proj: ProjectionDefinition) { } /** - * Get the unit to use with the CRS. + * Returns the horizontal coordinates system units associated with this CRS. * - * @param crs - The CRS to get the unit from. + * @param crs - The CRS to extract the unit from. * @returns Either `UNIT.METER`, `UNIT.DEGREE` or `undefined`. */ export function toUnit(crs: ProjectionLike) { @@ -99,9 +128,9 @@ export function toUnit(crs: ProjectionLike) { } /** - * Assert that the CRS is using metric units. + * Asserts that the CRS is using metric units. * - * @param crs - The CRS to validate. + * @param crs - The CRS to check. * @throws {@link Error} if the CRS is not valid. */ export function isMetricUnit(crs: ProjectionLike) { @@ -109,9 +138,9 @@ export function isMetricUnit(crs: ProjectionLike) { } /** - * Assert that the CRS is geographic. + * Asserts that the CRS is geographic. * - * @param crs - The CRS to validate. + * @param crs - The CRS to check. * @throws {@link Error} if the CRS is not valid. */ export function isGeographic(crs: ProjectionLike) { @@ -119,10 +148,10 @@ export function isGeographic(crs: ProjectionLike) { } /** - * Is the CRS geocentric? - * if crs isn't defined the method returns false. + * Asserts that the CRS is geocentric. * * @param crs - The CRS to test. + * @returns false if the crs isn't defined. */ export function isGeocentric(crs: ProjectionLike) { mustBeString(crs); @@ -131,11 +160,11 @@ export function isGeocentric(crs: ProjectionLike) { } /** - * Assert that the CRS is a valid one. + * Asserts that the CRS is valid, meaning it has been previously defined and + * includes an unit. * - * @param crs - The CRS to validate. - * - * @throws {@link Error} if the CRS is not valid. + * @param crs - The CRS to test. + * @throws {@link Error} if the crs is not valid. */ export function isValid(crs: ProjectionLike) { const proj = proj4.defs(crs); @@ -148,7 +177,7 @@ export function isValid(crs: ProjectionLike) { } /** - * Give a reasonnable epsilon to use with this CRS. + * Gives a reasonnable epsilon for this CRS. * * @param crs - The CRS to use. * @returns 0.01 if the CRS is EPSG:4326, 0.001 otherwise. @@ -162,10 +191,12 @@ export function reasonnableEpsilon(crs: ProjectionLike) { } /** - * Define a proj4 projection as a string and reference. + * Defines a proj4 projection as a named alias. + * This function is a specialized wrapper over the + * [`proj4.defs`](https://github.com/proj4js/proj4js#named-projections) + * function. * - * @param code - projection's SRS code (only used internally by the Proj4js - * library) - * @param proj4def - Proj4 definition string for the projection to use + * @param code - Named alias of the currently defined projection. + * @param proj4def - Proj4 or WKT string of the defined projection. */ export const defs = (code: string, proj4def: string) => proj4.defs(code, proj4def);