feat(core): layer coordinateSystem supports arbitrary CRS

docs/api-reference/core/custom-projection-view.md

@@ -12,7 +12,7 @@ import {Deck, _CustomProjectionView as CustomProjectionView} from '@deck.gl/core
 new Deck({
   views: new CustomProjectionView({
     crs: '+proj=eqearth +lon_0=0 +datum=WGS84 +units=m',
-    resolution: 5,
+    resolution: 72,
     controller: true
   }),
   initialViewState: {center: [0, 0, 0], zoom: 1}
@@ -28,7 +28,7 @@ Inherits [View options](./view.md#constructor), including layout, padding and co
 | Option | Default | Description |
 | --- | --- | --- |
 | `crs` | Required | A supported planar CRS identifier, such as `EPSG:3857`, or PROJ string. Linear axis units are read from the descriptor. |
-| `resolution` | `0` | Maximum subdivision cell size in WGS84 degrees for paths, polygons and bitmaps. Smaller positive values smooth projected curves at higher processing cost. Zero disables subdivision. |
+| `resolution` | `0` | Subdivision intervals around the earth for paths, polygons and bitmaps. The step is `EarthCircumference / resolution`, converted to source CRS units. Higher values generate more detailed geometry. Zero disables subdivision. |
 | `orthographic` | `false` | Use an orthographic camera instead of perspective. |
 
 The descriptor supplies conversion functions, WGS84 normalization, target-coordinate bounds and ground distance scales. For example, Web Mercator normalizes longitude and clamps latitude to its supported range. Bounds describe the size-sampling rectangle; they do not clip geometry.
@@ -73,10 +73,10 @@ When displaying multiple views with different projections, create a separate lay
 ## Limitations
 
 - Tiled layers and `WMSLayer` are not supported, including `TileLayer`, `Tile3DLayer`, `MVTLayer`, `TerrainLayer` and layers built on them.
-- `BitmapLayer` approximates the projection with a triangle mesh. A positive `resolution` creates an interior grid in WGS84 and projects every grid vertex; smaller values improve the approximation at a higher processing cost. Image coordinates are linearly interpolated within each triangle. If the image is generated in a different coordinate system than WGS84, subdivision cannot correct its pixel-to-coordinate mapping.
+- `BitmapLayer` approximates the projection with a triangle mesh. A positive `resolution` creates an interior grid in the source CRS and projects every grid vertex; higher values improve the approximation at a higher processing cost. Image coordinates are linearly interpolated within each triangle. Subdivision cannot correct an image's pixel-to-coordinate mapping when it differs from the declared source CRS.
 - Great-circle paths are not supported by `GreatCircleLayer` or `ArcLayer` with `greatCircle: true`. They fall back to ordinary arcs between projected endpoints, as with `greatCircle: false`. To preserve a great-circle path, sample it in geographic coordinates and render the samples with `PathLayer`.
-- `LineLayer`, `ArcLayer`, `PathLayer` and `SolidPolygonLayer` ignore `wrapLongitude` when the viewport uses preprojection. Split geometry at the desired longitude boundary before passing it to these layers.
-- With `coordinateSystem: 'default'`, layer positions are interpreted as coordinates in WGS84. `modelMatrix` is applied before conversion, and `coordinateOrigin` is ignored. Bypass this behavior with `coordinateSystem: 'cartesian'`. Cartesian positions are in target CRS units in `crs`, and `modelMatrix` and `coordinateOrigin` both apply.
+- `LineLayer`, `ArcLayer`, `PathLayer` and `SolidPolygonLayer` ignore `wrapLongitude` when the layer uses CPU preprojection or its source coordinates are not WGS84. Split geometry at the desired longitude boundary before passing it to these layers.
+- With `coordinateSystem: 'default'`, layer positions are interpreted as coordinates in WGS84. `modelMatrix` and then `coordinateOrigin` are applied in the source CRS before conversion. Use a CRS identifier or PROJ string to declare another source CRS. Positions whose CRS signature matches the view's descriptor bypass CPU conversion. Legacy `coordinateSystem: 'cartesian'` also bypasses conversion. Cartesian positions are in target CRS units in `crs`, and `modelMatrix` and `coordinateOrigin` both apply.
 - Split geometry at projection discontinuities before passing it to the layer. This view does not automatically clip geometry at those boundaries. The converter must return finite coordinates for the geometry you render.
 - Picked coordinates are returned as world coordinates in WGS84. They may be unavailable where the descriptor’s inverse converter cannot return a valid position.
 

docs/api-reference/core/custom-projection-viewport.md

@@ -48,13 +48,9 @@ The local scale field samples the descriptor's finite target-coordinate `renderi
 
 Inherits [Viewport](./viewport.md) methods with these coordinate semantics:
 
-### `preproject(position)`
+### `getPreprojection(sourceCrs)`
 
-Normalizes WGS84 coordinates and converts them to target XYZ. Independent of camera state.
-
-### `postUnproject(position)`
-
-Delegates target XYZ conversion to `crs.converter.WGS84.to`. Returns `null` if math.gl reports a conversion failure.
+Returns `{preproject, unpreproject, packedCrs}` for the resolved source descriptor. When its signature matches the viewport's descriptor, both functions are `null` and attributes remain in target CRS units. Otherwise, conversion goes through WGS84 and the target descriptor's normalization. `unpreproject` reverses the conversion. These functions are independent of camera state and exclude layer transforms; layers retain them in internal state.
 
 ### `project(position, options)`
 

docs/api-reference/core/globe-view.md

@@ -50,9 +50,6 @@ const view = new GlobeView({id, ...});
 
 `GlobeView` takes the same parameters as the [View](./view.md) superclass constructor, plus the following:
 
-#### `resolution` (number, optional) {#resolution}
-
-The resolution at which to turn flat features into 3D meshes, in degrees. Smaller numbers will generate more detailed mesh. Default `10`.
 
 #### `nearZMultiplier` (number, optional) {#nearzmultiplier}
 

docs/api-reference/core/layer.md

@@ -241,23 +241,25 @@ Normally only used when the application wants to work with coordinates that are
 
 * Default: `'default'`
 
-Specifies how layer positions and offsets should be geographically interpreted. One of:
+Specifies the CRS of layer positions after `modelMatrix` and `coordinateOrigin` are applied. Built-in coordinate systems include:
 
 - `'default'`
 - `'cartesian'`
 - `'lnglat'`
 - `'meter-offsets'`
 - `'lnglat-offsets'`
 
-The default is to interpret positions as latitude and longitude, however it is also possible to interpret positions as meter offsets added to projection center specified by the `coordinateOrigin` prop.
+`'lnglat'`, `'WGS84'`, `'EPSG:4326'`, and `'EPSG:4979'` identify WGS84 longitude/latitude/elevation. `'globe'` identifies geocentric meter coordinates on deck.gl's existing sphere; `'EPSG:4978'` identifies WGS84 ellipsoid geocentric coordinates. Other CRS identifiers and PROJ strings are resolved by `@math.gl/projection`. While resolution is pending, the layer waits before initialization or updates; failures are reported through the layer's error handler.
+
+`'default'` uses WGS84 in geospatial views and Cartesian coordinates in non-geospatial views. Shader-supported source CRSs retain their attribute coordinates. Other source CRSs are converted on the CPU to WGS84, or to the target CRS of a custom projection.
 
 See the article on [Coordinate Systems](../../developer-guide/coordinate-systems.md) for details.
 
 #### `coordinateOrigin` (number[3], optional) {#coordinateorigin}
 
 * Default: `[0, 0, 0]`
 
-Specifies a reference point for coordinates that are expressed as offsets. Used when the `coordinateSystem` is set to one of the following modes:
+For an absolute CRS, this value is added in source CRS units after `modelMatrix`, before projection. For offset modes, it specifies the geographic reference point:
 
 - `'cartesian'` (optional)
 - `'meter-offsets'` (required)
@@ -856,7 +858,7 @@ Parameters:
   - `modelMatrix` (Matrix4 | null) - defaults to `this.props.modelMatrix`. Pass `null` to skip the layer matrix.
   - `coordinateOrigin` (number[3]) - defaults to `this.props.coordinateOrigin`.
   - `coordinateSystem` (string) - defaults to `this.props.coordinateSystem`.
-  - `fromCoordinateOrigin` (number[3]) - defaults to passed `coordinateOrigin`.
+  - `fromCoordinateOrigin` (number[3]) - defaults to passed `coordinateOrigin` for the same source system, or `[0, 0, 0]` for a different system.
   - `fromCoordinateSystem` (string) - defaults to passed `coordinateSystem`.
 
 Returns:

docs/api-reference/core/project.md

@@ -40,7 +40,7 @@ The JavaScript uniforms are extracted from both contextual and per-layer props.
 
 Uniforms are considered private to each shader module. They may change in between patch releases. Always use documented functions instead of accessing module uniforms directly.
 
-The uniforms of the `project` shader module are prefixed with `project_` in their names.
+The `project.coordinateFrame` uniform describes packed attributes as identity, geodetic, projected, or geocentric coordinates. It is distinct from a layer's `coordinateSystem` CRS string. Local meter and degree offsets select their own projection modes. Both numeric enum definitions are internal to the project shader module.
 
 ## GLSL Functions
 

docs/api-reference/core/view.md

@@ -52,6 +52,10 @@ A relative (e.g. `'50%'`) or absolute extent. Accepts CSS-like expressions that
 
 Padding around the viewport, in the shape of `{left, right, top, bottom}` where each value is either a relative (e.g. `'50%'`) or absolute pixels. These values support the same CSS-style expressions (numbers/percentages/`px` with parentheses and `calc()` addition/subtraction) as `x`, `y`, `width`, and `height`. This can be used to move the "look at"/target/vanishing point away from the center of the viewport rectangle.
 
+#### `resolution` (number, optional) {#resolution}
+
+Divide long straight lines in paths, polygons or meshes into smaller segments so that they closely follow the shape of the target CRS. Higher values produce finer geometry details but requires more processing and memory. Default `0` disables subdivision. See [geometry approximation](./viewport.md#geometry-approximation).
+
 #### `controller` (Function | boolean | object, optional) {#controller}
 
 Options for viewport interactivity.

docs/api-reference/core/viewport.md

@@ -146,6 +146,13 @@ Returns:
 * `[longitude, latitude, altitude]`
 
 
+#### `getPreprojection`
+
+Returns conversions between a source CRS and the CRS accepted by the viewport's projection shader.
+
+- `sourceCrs` (`CRSDescriptor | null`) - Resolved source descriptor; `null` denotes Cartesian or meter-offset input.
+- Returns `{preproject, unpreproject, packedCrs}`. Both functions are `null` when the shader accepts the source CRS directly. Otherwise, `preproject` converts source coordinates to packed coordinates and `unpreproject` reverses that conversion. `packedCrs` describes the attribute coordinates. These functions do not apply the layer's model matrix or coordinate origin.
+
 #### `getBounds` {#getbounds}
 
 Extracts the axis-aligned bounding box of the current visible area.
@@ -200,6 +207,23 @@ if (outDir) {
 * To support pixel project/unproject functions (in addition to the clipspace projection that Camera classes typically manage), the `Viewport` is also aware of the viewport extents.
 * In geospatial setups, Viewports can contain geospatial anchors.
 
+
+### Geometry Approximation
+
+![subdivision](https://raw.githubusercontent.com/visgl/deck.gl-data/refs/heads/master/images/docs/viewport-resolution.png)
+
+<small>Left to right: same polygons in resolution 0, 10, 60, rendering 487, 501, 591 outline vertices respectively.
+Notice the shape of the 49th-parallel.
+<br/><i>Natural Earth 1:110 country boundaries of continental Canada and United States. Albers projection, central metidian -96°, standard parallels 29.5° / 45.5°</i>
+</small>
+
+
+When a geometry is displayed in a different CRS from its definition, long segments are still rendered as straight lines, instead of warping along the surface of the new CRS.
+
+Use `resolution` to divide long straight lines into smaller segments to better follow the shape of the target CRS. Subdivision adds vertices before projection so paths, polygon edges and bitmap meshes can follow projected curves more closely. Higher values produce finer detail, with more processing and memory overhead. Subdivision is by default disabled.
+
+The setting is relative to the earth's circumference and works across source CRSs with different units. For example, `resolution: 36` gives a 10-degree step for WGS84 geometry. When implementing a custom layer, use `context.viewport.getSubdivisionStep(sourceCrs)` to retrieve a step in the geometry's source CRS units.
+
 ## Source
 
 [modules/core/src/viewports/viewport.ts](https://github.com/visgl/deck.gl/blob/master/modules/core/src/viewports/viewport.ts)

docs/api-reference/extensions/fill-style-extension.md

@@ -231,7 +231,7 @@ the pattern and the background color styles the area behind it.
 The units of the pattern size, one of `'meters'`, `'common'` and `'pixels'`. See [unit system](../../developer-guide/coordinate-systems.md#supported-units). A 24 x 24 pixel pattern at [`getFillPatternScale: 1`](#getfillpatternscale) covers 24 units of the chosen unit. Procedural pattern stroke widths, gaps, and radii use the same units.
 
 + `'meters'` anchors the pattern to the ground, so it zooms along with the rest of the map.
-+ `'common'` sizes the pattern in [common space](../../developer-guide/coordinate-systems.md) units, which is what a non-geospatial view (`COORDINATE_SYSTEM.CARTESIAN`) wants - meters are converted with a fixed Web Mercator ratio and are not meaningful there.
++ `'common'` sizes the pattern in [common space](../../developer-guide/coordinate-systems.md) units, which is what a non-geospatial view (`'cartesian'`) wants - meters are converted with a fixed Web Mercator ratio and are not meaningful there.
 + `'pixels'` keeps the pattern at a constant size on screen instead. The size is re-anchored at each integer zoom level rather than followed continuously, so that the tiling stays put while zooming within a level; the pattern therefore stays within a factor of `sqrt(2)` of its nominal pixel size.
 
 ```js

docs/api-reference/geo-layers/mvt-layer.md

@@ -325,6 +325,8 @@ Remarks:
 
 ## Tile
 
+Tiles are loaded in tile-local coordinates. Sublayers declare `coordinateSystem: 'OSMTile512'`, with a tile-specific model matrix and origin mapping positions to a 512-unit Mercator world (X eastward, Y southward, Z in meters). Each sublayer converts these positions for the active viewport.
+
 Aside from all members of the [Tile](./tile-layer.md#tile) class, tile instances from the `MVTLayer` also include the following fields:
 
 #### `dataInWGS84` (Feature[]) {#datainwgs84}

docs/developer-guide/coordinate-systems.md

@@ -52,6 +52,10 @@ Each layer is expected to specify its `coordinateSystem` prop to match the world
 
 By default, a layer's [coordinateSystem](../api-reference/core/layer.md#coordinatesystem) is assumed to be `'lnglat'` if rendered in a geospatial view (e.g. `MapView`, `GlobeView`) and `'cartesian'` if rendered in a non-geospatial view (e.g. `OrbitView`, `OrthographicView`).
 
+A layer may also supply a CRS identifier or PROJ string supported by `@math.gl/projection`. Deck.gl waits for the descriptor before initializing or updating the layer. It converts positions on the CPU when the view's projection shader cannot consume that source CRS. Each layer retains the source CRS and the CRS of its packed attributes, so CPU conversion and shader projection apply transforms once.
+
+For absolute CRSs, `modelMatrix` and then `coordinateOrigin` apply in the declared source CRS before conversion.
+
 Some coordinate systems need to be used with the [coordinateOrigin](../api-reference/core/layer.md#coordinateorigin) prop, which specifies where the positions are measured from.