Merge eaf79b4 into b73b81a

docs/developer-guide/coordinate-systems.md

@@ -31,7 +31,7 @@ new PointCloudLayer({
 | `COORDINATE_SYSTEM.LNGLAT` (default) | [longitude, latitude, altitude] | meters | Longitude and latitude are specified as [WGS84](https://gisgeography.com/wgs84-world-geodetic-system/) coordinates in degrees from Greenwich meridian / equator respectively, and altitude is specified in meters above sea level. |
 | `COORDINATE_SYSTEM.METER_OFFSETS` *   | [Δx, Δy, Δz]   | meters | Positions are given in meter offsets from a reference geo-location that is specified separately (`coordinateOrigin`). The `x` axis points map east, the `y` axis points map north, and `z` points up. |
 | `COORDINATE_SYSTEM.LNGLAT_OFFSETS`    | [Δlongitude, Δlatitude, Δaltitude]   | meters | Positions are given in meter offsets from a reference geo-location that is specified separately (`coordinateOrigin`). |
-| `COORDINATE_SYSTEM.IDENTITY`         | [x, y, z] | identity units | A linear system with no interpretation for pure info-vis layers. Viewports can be used without supplying geospatial reference points. |
+| `COORDINATE_SYSTEM.CARTESIAN`         | [x, y, z] | identity units | A linear system with no interpretation for pure info-vis layers. Viewports can be used without supplying geospatial reference points. |
 | `COORDINATE_SYSTEM.LNGLAT_DEPRECATED`| [longitude, latitude, altitude] | meters | A lower precision version of the `COORDINATE_SYSTEM.LNGLAT` mode, that was the default until deck.gl v6.2. Will be removed in a future release. |
 
 * Note that although UTM ([Universal Transverse Mercator](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system)) coordinates uses similar meter offsets as the deck.gl meters mode, be aware there are subtle differences, so be careful before making assumptions.

docs/upgrade-guide.md

@@ -35,6 +35,9 @@
   + `projectFlat`: use `projectPosition`
 - `PerspectiveView` class - use `FirstPersonView`
 - `ThirdPersonView` class - use `MapView` (geospatial) or `OrbitView` (info-vis)
+- `COORDINATE_SYSTEM` enum
+  + `LNGLAT_DEPRECATED`: use `LNGLAT`
+  + `METERS`: use `METER_OFFSETS`
 
 ##### Standalone bundle
 

examples/experimental/bezier/src/bezier-graph-layer.js

@@ -16,7 +16,7 @@ export default class BezierGraphLayer extends CompositeLayer {
       new BezierCurveLayer({
         id: 'edges',
         data: edges,
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
+        coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
         getSourcePosition: e => e.source,
         getTargetPosition: e => e.target,
         getControlPoint: e => e.controlPoint,
@@ -30,7 +30,7 @@ export default class BezierGraphLayer extends CompositeLayer {
       new ScatterplotLayer({
         id: 'nodes',
         data: nodes,
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
+        coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
         getPosition: d => d.position,
         getRadius: 5,
         getFillColor: [0, 0, 150, 255],

examples/gallery/src/icon-layer.html

@@ -43,7 +43,6 @@
 
       const iconLayer = new IconLayer({
         id: 'users',
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
         data,
         getIcon: d => ({
           url: d.avatar_url,
@@ -58,7 +57,6 @@
 
       const lineLayer = new LineLayer({
         id: 'links',
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
         data,
         pickable: true,
         getSourcePosition: d => ORIGIN,
@@ -69,7 +67,6 @@
 
       const scatterPlotLayer = new ScatterplotLayer({
         id: 'deck.gl-circle',
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
         data: [{position: [0, 0]}],
         getPosition: d => d.position,
         getFillColor: [23, 38, 42],
@@ -79,7 +76,6 @@
 
       const textLayer = new TextLayer({
         id: 'deck.gl-label',
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
         data: [{position: [0, 0]}],
         getSize: 15,
         getPosition: d => d.position,

examples/gallery/src/point-cloud-layer.html

@@ -69,7 +69,6 @@
       layers: [
         new PointCloudLayer({
           id: 'pointCloud',
-          coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
           data: points,
           getPosition: d => d.position,
           getNormal: d => d.normal,

examples/layer-browser/src/app.js

@@ -197,7 +197,7 @@ export default class App extends PureComponent {
 
     switch (coordinateSystem) {
       case COORDINATE_SYSTEM.METER_OFFSETS:
-      case COORDINATE_SYSTEM.IDENTITY:
+      case COORDINATE_SYSTEM.CARTESIAN:
         const {
           settings: {rotationZ, rotationX}
         } = this.state;

examples/layer-browser/src/examples/infovis-layers.js

@@ -1,7 +1,7 @@
 import {COORDINATE_SYSTEM} from '@deck.gl/core';
 import PlotLayer from '../../../website/plot/plot-layer';
 
-// TODO - add point cloud layer for COORDINATE_SYSTEM.IDENTITY
+// TODO - add point cloud layer for COORDINATE_SYSTEM.CARTESIAN
 
 // import {PointCloudLayer} from 'deck.gl';
 // import * as dataSamples from '../data-samples';
@@ -20,7 +20,7 @@ const EQUATION = (x, y) => (Math.sin(x * x + y * y) * x) / Math.PI;
 const PlotLayerInfovisExample = {
   layer: PlotLayer,
   props: {
-    coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
+    coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
     uCount: 200,
     vCount: 200,
     drawAxes: true,
@@ -52,7 +52,7 @@ const PointCloudLayerInfovisExample = {
   props: {
     id: 'pointCloudLayer',
     outline: true,
-    coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
+    coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
     coordinateOrigin: dataSamples.positionOrigin,
     opacity: 1,
     radiusPixels: 4,

examples/layer-browser/src/map.js

@@ -137,7 +137,7 @@ export default class Map extends PureComponent {
   // Only show infovis layers in infovis mode and vice versa
   _layerFilter({layer, renderPass}) {
     const {settings} = this.props;
-    const isIdentity = layer.props.coordinateSystem === COORDINATE_SYSTEM.IDENTITY;
+    const isIdentity = layer.props.coordinateSystem === COORDINATE_SYSTEM.CARTESIAN;
     return settings.infovis ? isIdentity : !isIdentity;
   }
 

examples/website/mesh/app.js

@@ -68,7 +68,7 @@ export default class App extends PureComponent {
         id: 'mini-coopers',
         data: SAMPLE_DATA,
         mesh: MESH_URL,
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
+        coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
         getPosition: d => d.position,
         getColor: d => d.color,
         getOrientation: d => d.orientation
@@ -78,7 +78,7 @@ export default class App extends PureComponent {
         id: 'background',
         data: background,
         extruded: false,
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
+        coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
         getPolygon: f => f,
         getFillColor: [0, 0, 0, 0]
       })

examples/website/plot/plot-layer/plot-layer.js

@@ -28,7 +28,7 @@ const defaultProps = {
   zTitle: AxesLayer.defaultProps.zTitle,
   axesPadding: AxesLayer.defaultProps.padding,
   axesColor: AxesLayer.defaultProps.color,
-  coordinateSystem: COORDINATE_SYSTEM.IDENTITY
+  coordinateSystem: COORDINATE_SYSTEM.CARTESIAN
 };
 
 /*

examples/website/point-cloud/app.js

@@ -96,7 +96,7 @@ export default class App extends PureComponent {
         id: 'laz-point-cloud-layer',
         data: LAZ_SAMPLE,
         onDataLoad: this._onLoad,
-        coordinateSystem: COORDINATE_SYSTEM.IDENTITY,
+        coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
         getNormal: [0, 1, 0],
         getColor: [255, 255, 255],
         opacity: 0.5,

modules/aggregation-layers/src/utils/gpu-grid-aggregation/grid-aggregation-utils.js

@@ -28,8 +28,15 @@ export function pointToDensityGridData({
   log.assert(cellSizeMeters > 0);
   let cellSize = [cellSizeMeters, cellSizeMeters];
   let worldOrigin = [0, 0];
+
+  if (coordinateSystem === COORDINATE_SYSTEM.DEFAULT) {
+    coordinateSystem =
+      viewport && !viewport.isGeospatial ? COORDINATE_SYSTEM.CARTESIAN : COORDINATE_SYSTEM.LNGLAT;
+  }
+
   log.assert(
-    coordinateSystem === COORDINATE_SYSTEM.LNGLAT || coordinateSystem === COORDINATE_SYSTEM.IDENTITY
+    coordinateSystem === COORDINATE_SYSTEM.LNGLAT ||
+      coordinateSystem === COORDINATE_SYSTEM.CARTESIAN
   );
 
   switch (coordinateSystem) {
@@ -39,7 +46,7 @@ export function pointToDensityGridData({
       cellSize = [gridOffset.xOffset, gridOffset.yOffset];
       worldOrigin = [-180, -90]; // Origin used to define grid cell boundaries
       break;
-    case COORDINATE_SYSTEM.IDENTITY:
+    case COORDINATE_SYSTEM.CARTESIAN:
       const {width, height} = viewport;
       worldOrigin = [-width / 2, -height / 2]; // Origin used to define grid cell boundaries
       break;

modules/core/src/lib/constants.js

@@ -21,25 +21,42 @@
 // Note: The numeric values here are matched by shader code in the
 // "project" and "project64" shader modules. Both places need to be
 // updated.
+import log from '../utils/log';
 
-// TODO: Maybe "POSITIONS" would be a better name?
+// Describes the format of positions
 export const COORDINATE_SYSTEM = {
+  // `LNGLAT` if rendering into a geospatial viewport, `CARTESIAN` otherwise
+  DEFAULT: -1,
   // Positions are interpreted as [lng, lat, elevation]
   // lng lat are degrees, elevation is meters. distances as meters.
   LNGLAT: 1,
-  LNGLAT_DEPRECATED: 5,
 
   // Positions are interpreted as meter offsets, distances as meters
   METER_OFFSETS: 2,
-  // Planned to deprecate in later versions, in favor of METER_OFFSETS
-  METERS: 2,
 
   // Positions are interpreted as lng lat offsets: [deltaLng, deltaLat, elevation]
   // deltaLng, deltaLat are delta degrees, elevation is meters.
   // distances as meters.
   LNGLAT_OFFSETS: 3,
 
-  // Positions and distances are not transformed: [x, y, z] in unit coordinates
+  // Non-geospatial
+  CARTESIAN: 0
+};
+
+// Deprecated
+/* eslint-disable accessor-pairs */
+Object.defineProperty(COORDINATE_SYSTEM, 'IDENTITY', {
+  get: () => log.deprecated('COORDINATE_SYSTEM.IDENTITY', 'COORDINATE_SYSTEM.CARTESIAN')() || 0
+});
+/* eslint-enable accessor-pairs */
+
+// Describes the common space
+export const PROJECTION_MODE = {
+  WEB_MERCATOR: 1,
+
+  // This is automatically assigned by the project module
+  WEB_MERCATOR_AUTO_OFFSET: 4,
+
   IDENTITY: 0
 };
 

modules/core/src/lib/layer.js

@@ -68,7 +68,7 @@ const defaultProps = {
   onDrag: {type: 'function', value: null, compare: false, optional: true},
   onDragEnd: {type: 'function', value: null, compare: false, optional: true},
 
-  coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
+  coordinateSystem: COORDINATE_SYSTEM.DEFAULT,
   coordinateOrigin: {type: 'array', value: [0, 0, 0], compare: true},
   modelMatrix: {type: 'array', value: null, compare: true, optional: true},
   wrapLongitude: false,
@@ -203,9 +203,11 @@ export default class Layer extends Component {
   }
 
   use64bitPositions() {
+    const {coordinateSystem} = this.props;
     return (
-      this.props.coordinateSystem === COORDINATE_SYSTEM.LNGLAT ||
-      this.props.coordinateSystem === COORDINATE_SYSTEM.IDENTITY
+      coordinateSystem === COORDINATE_SYSTEM.DEFAULT ||
+      coordinateSystem === COORDINATE_SYSTEM.LNGLAT ||
+      coordinateSystem === COORDINATE_SYSTEM.IDENTITY
     );
   }
 
@@ -843,6 +845,7 @@ ${flags.viewportChanged ? 'viewport' : ''}\
 
   _initState() {
     assert(!this.internalState && !this.state);
+    assert(isFinite(this.props.coordinateSystem), `${this.id}: invalid coordinateSystem`);
 
     const attributeManager = this._getAttributeManager();
 

modules/core/src/shaderlib/project/project.glsl.js

@@ -18,17 +18,22 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-import {PROJECT_COORDINATE_SYSTEM} from './constants';
+import {COORDINATE_SYSTEM, PROJECTION_MODE} from '../../lib/constants';
 
 // We are generating these from the js code in constants.js
-const COORDINATE_SYSTEM_GLSL_CONSTANTS = Object.keys(PROJECT_COORDINATE_SYSTEM)
-  .map(key => `const float COORDINATE_SYSTEM_${key} = ${PROJECT_COORDINATE_SYSTEM[key]}.;`)
+const COORDINATE_SYSTEM_GLSL_CONSTANTS = Object.keys(COORDINATE_SYSTEM)
+  .map(key => `const float COORDINATE_SYSTEM_${key} = ${COORDINATE_SYSTEM[key]}.;`)
+  .join('');
+const PROJECTION_MODE_GLSL_CONSTANTS = Object.keys(PROJECTION_MODE)
+  .map(key => `const float PROJECTION_MODE_${key} = ${PROJECTION_MODE[key]}.;`)
   .join('');
 
 export default `\
 ${COORDINATE_SYSTEM_GLSL_CONSTANTS}
+${PROJECTION_MODE_GLSL_CONSTANTS}
 
 uniform float project_uCoordinateSystem;
+uniform float project_uProjectionMode;
 uniform float project_uScale;
 uniform bool project_uWrapLongitude;
 uniform float project_uAntimeridian;
@@ -81,7 +86,7 @@ vec3 project_normal(vec3 vector) {
 
 vec4 project_offset_(vec4 offset) {
   float dy = offset.y;
-  if (project_uCoordinateSystem == COORDINATE_SYSTEM_LNGLAT_AUTO_OFFSET) {
+  if (project_uCoordinateSystem == COORDINATE_SYSTEM_LNGLAT) {
     dy = clamp(dy, -1., 1.);
   }
   vec3 commonUnitsPerWorldUnit = project_uCommonUnitsPerWorldUnit + project_uCommonUnitsPerWorldUnit2 * dy;
@@ -103,31 +108,25 @@ vec2 project_mercator_(vec2 lnglat) {
 }
 
 //
-// Projects lnglats (or meter offsets, depending on mode) to common space
+// Projects positions (defined by project_uCoordinateSystem) to common space (defined by project_uProjectionMode)
 //
 vec4 project_position(vec4 position, vec3 position64Low) {
-  // TODO - why not simply subtract center and fall through?
-  if (project_uCoordinateSystem == COORDINATE_SYSTEM_LNG_LAT) {
+  if (project_uCoordinateSystem == COORDINATE_SYSTEM_LNGLAT && project_uProjectionMode == PROJECTION_MODE_WEB_MERCATOR) {
     return project_uModelMatrix * vec4(
       project_mercator_(position.xy) * WORLD_SCALE,
       project_size(position.z),
       position.w
     );
   }
 
-  if (project_uCoordinateSystem == COORDINATE_SYSTEM_LNGLAT_AUTO_OFFSET) {
-    // Subtract high part of 64 bit value. Convert remainder to float32, preserving precision.
-    return project_offset_(vec4(position.xyz - project_uCoordinateOrigin + position64Low, position.w));
-  }
+  vec4 position_world = project_uModelMatrix * position;
 
-  if (project_uCoordinateSystem == COORDINATE_SYSTEM_LNGLAT_OFFSETS) {
-    return project_offset_(position);
+  if (project_uCoordinateSystem == COORDINATE_SYSTEM_LNGLAT && project_uProjectionMode == PROJECTION_MODE_WEB_MERCATOR_AUTO_OFFSET) {
+    // Subtract high part of 64 bit value. Convert remainder to float32, preserving precision.
+    position_world.xyz -= project_uCoordinateOrigin;
+    position_world.xyz += position64Low;
   }
-
-  // METER_OFFSETS or IDENTITY
-  // Apply model matrix
-  vec4 position_world = project_uModelMatrix * position;
-  if (project_uCoordinateSystem == COORDINATE_SYSTEM_IDENTITY) {
+  if (project_uProjectionMode == PROJECTION_MODE_IDENTITY) {
     position_world.xyz -= project_uCoordinateOrigin;
     // Translation is already added to the high parts
     position_world += project_uModelMatrix * vec4(position64Low, 0.0);