Update proj4 docs (#162)

uber-web · Aug 18, 2020 · bc835f3 · bc835f3
1 parent 2a0f779
commit bc835f3
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 34 deletions.
diff --git 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
@@ -1,50 +1,76 @@
 # 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);
 ```
 
 ## 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 <https://epsg.io>. For example, <https://epsg.io/4326> 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
@@ -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: {