diff --git a/modules/proj4/docs/api-reference/proj4-projection.md b/modules/proj4/docs/api-reference/proj4-projection.md index acea3d5c..32b3e0d2 100644 --- a/modules/proj4/docs/api-reference/proj4-projection.md +++ b/modules/proj4/docs/api-reference/proj4-projection.md @@ -1,13 +1,15 @@ -# Ellipsoid - +# Proj4Projection ## Usage -Reproject WGS84 coordinates in another CRS +Reproject WGS84 coordinates to another CRS + ```js import {Proj4Projection} from '@math.gl/proj4'; -const projection = new Proj4Projection({from: 'WGS84', to: '...'}); +const nad83Proj = + '+title=NAD83 (long/lat) +proj=longlat +a=6378137.0 +b=6356752.31414036 +ellps=GRS80 +datum=NAD83 +units=degrees'; +const projection = new Proj4Projection({from: 'WGS84', to: nad83Proj}); const wgs84Position = [21, 78, 5000]; const reprojectedPosition = projection.project(wgs84Position); @@ -20,8 +22,10 @@ import {Proj4Projection} from '@math.gl/proj4'; Proj4Projection.defineProjectionAliases({ 'EPSG:4326': '+title=WGS 84 (long/lat) +proj=longlat +ellps=WGS84 +datum=WGS84 +units=degrees', - 'EPSG:4269': '+title=NAD83 (long/lat) +proj=longlat +a=6378137.0 +b=6356752.31414036 +ellps=GRS80 +datum=NAD83 +units=degrees' -}) + 'EPSG:4269': + '+title=NAD83 (long/lat) +proj=longlat +a=6378137.0 +b=6356752.31414036 +ellps=GRS80 +datum=NAD83 +units=degrees' +}); +const projection = new Proj4Projection({from: 'EPSG:4326', to: 'EPSG:4269'}); ``` ## Static Fields @@ -39,7 +43,7 @@ Create a new `Proj4Projection` instance that can convert between the specified c ### project(coord: number[]): number[] Project a coordinate project from first to second coordinate system - + ### unproject(coord: number[]): number[] Project a coordinate project from second to first coordinate system diff --git a/modules/proj4/docs/developer-guide/proj4-guide.md b/modules/proj4/docs/developer-guide/proj4-guide.md index 4ff81e8a..b5704374 100644 --- a/modules/proj4/docs/developer-guide/proj4-guide.md +++ b/modules/proj4/docs/developer-guide/proj4-guide.md @@ -1,24 +1,26 @@ # Overview -The `@math.gl/proj4` module provides support for conversion between major geospatial coordinate systems and projections used with computer maps, such as: +The `@math.gl/proj4` module provides support for conversion between major geospatial coordinate reference systems (CRS) and projections used with computer maps, such as: - [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) (World Geodetic System) coordinates. - [Web Mercator Projection](https://en.wikipedia.org/wiki/Web_Mercator_projection) -- etc ## Classes -| Class | Description | -| --- | --- | -| `Proj4Projection` | A projection class | +| Class | Description | +| ----------------- | ------------------ | +| `Proj4Projection` | A projection class | ## Usage -Reproject WGS84 coordinates in another CRS +Reproject WGS84 coordinates to another CRS + ```js import {Proj4Projection} from '@math.gl/proj4'; -const projection = new Proj4Projection({from: 'WGS84', to: '...'}); +const nad83Proj = + '+title=NAD83 (long/lat) +proj=longlat +a=6378137.0 +b=6356752.31414036 +ellps=GRS80 +datum=NAD83 +units=degrees'; +const projection = new Proj4Projection({from: 'WGS84', to: nad83Proj}); const wgs84Position = [21, 78, 5000]; const reprojectedPosition = projection.project(wgs84Position); @@ -26,25 +28,49 @@ const reprojectedPosition = projection.project(wgs84Position); ## Geospatial Coordinate Systems +There are an infinite number of possible coordinate systems; therefore strict syntax is required to describe the parameters of any given CRS. Two main systems are supported in this module: Proj4 strings and WKT strings. Within WKT there exists both OGC WKT and ESRI WKT syntax; both are generally supported though some more-obscure projection keywords may not be used. Note that Proj4 strings [can be slightly more accurate](https://github.com/proj4js/proj4js/issues/222) in some circumstances than WKT strings. + +There are thousands of named "EPSG" projections. This module only includes aliases for those in the section below by default. To use a different EPSG projection, you can use . For example, defines standard longitude-latitude coordinates and lists multiple projection strings. Choose one of the `OGC WKT`, `ESRI WKT`, or `PROJ.4` strings listed. + +The epsg.io website also has a public API, e.g., for WGS 84: `https://epsg.io/?q=4326&format=json` + +```json +{ + "status": "ok", + "number_result": 1, + "results": [ + { + "code": "4326", + "kind": "CRS-GEOGCRS", + "bbox": [90.0, -180.0, -90.0, 180.0], + "wkt": "GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563,AUTHORITY[\"EPSG\",\"7030\"]],AUTHORITY[\"EPSG\",\"6326\"]],PRIMEM[\"Greenwich\",0,AUTHORITY[\"EPSG\",\"8901\"]],UNIT[\"degree\",0.0174532925199433,AUTHORITY[\"EPSG\",\"9122\"]],AUTHORITY[\"EPSG\",\"4326\"]]", + "unit": "degree (supplier to define representation)", + "proj4": "+proj=longlat +datum=WGS84 +no_defs", + "name": "WGS 84", + "area": "World.", + "default_trans": 0, + "trans": [], + "accuracy": "" + } + ] +} +``` + ### Aliases Note that Proj4Projection allows aliases to be defined and comes with the following pre-installed aliases. -| Alias | Resolves To | -| --- | --- | -| 'WGS84' | 'EPSG:4326' | -| 'EPSG:3785' | 'EPSG:3857' 'EPSG:4269' | -| 'GOOGLE' | 'EPSG:3857' 'EPSG:4269' | -| 'EPSG:900913' | 'EPSG:3857' 'EPSG:4269' | -| 'EPSG:102113' | 'EPSG:3857' 'EPSG:4269' | - +| Coordinate system | Aliases | +| -------------------- | ---------------------------------------------------------------- | +| Lat/lon, WGS84 datum | `EPSG:4326`, `WGS84` | +| Lat/lon, NAD83 datum | `EPSG:4269` | +| Web mercator | `EPSG:3857`, `EPSG:3785`, `GOOGLE`, `EPSG:900913`, `EPSG:102113` | ### References - [OGC WKT-CRS Specification](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html) standards documentation. - [spatialreference.org](https://spatialreference.org/) a catalog of coordinate system references. -- [espg.io](https://epsg.io/) Lets the user look up the definition of a coordinate system. - +- [espg.io](https://epsg.io/) Lets the user look up the definition of a coordinate system. E.g. [https://epsg.io/4326](https://epsg.io/4326) provides the definition of WGS84 in WKT-CRS format: diff --git a/modules/proj4/src/lib/proj4-projection.d.ts b/modules/proj4/src/lib/proj4-projection.d.ts index 6c3602a1..d38c2885 100644 --- a/modules/proj4/src/lib/proj4-projection.d.ts +++ b/modules/proj4/src/lib/proj4-projection.d.ts @@ -1,13 +1,3 @@ -import proj4 from 'proj4'; - -/** - * Predefined Aliases - * 'WGS84': 'EPSG:4326' - * 'EPSG:3785': 'EPSG:3857' 'EPSG:4269' - * 'GOOGLE': 'EPSG:3857' 'EPSG:4269' - * 'EPSG:900913': 'EPSG:3857' 'EPSG:4269' - * 'EPSG:102113': 'EPSG:3857' 'EPSG:4269' - */ export class Proj4Projection { /** Define aliases for one or more projections */ static defineProjectionAliases(projections: {