feat(core) coordinateSystem prop now accepts no-import string constants

[ibgreen]

Summary

One my pet peeves with deck.gl is the need to import the COORDINATE_SYSTEM enum. Today such APIs are specified with typescript string constants.

• This PR changes the API to accept string constants, and keeps the enum as a deprecated export.
• The enum values are now the string constants, not the old numbers.
• Therefore would only be a breaking change if an application was using numbers directly, not the enums.

Previously

import {COORDINATE_SYSTEM} from '@deck.gl/core';
new Layer({coordinateSystem: COORDINATE_SYSTEM.LNGLAT});

Now

new Layer({coordinateSystem: 'lnglat'});

---

Refactor coordinateSystem to use string-valued coordinate system identifiers across the public API and internal runtime paths, while keeping COORDINATE_SYSTEM as a deprecated compatibility export.

Compared to master, this updates 21 files with 213 insertions and 122 deletions.

What Changed

• Changed CoordinateSystem in modules/core/src/lib/constants.ts from numeric literals to a string union:

  • 'default'
  • 'lnglat'
  • 'meter-offsets'
  • 'lnglat-offsets'
  • 'cartesian'

• Updated COORDINATE_SYSTEM.* runtime values to those string constants and marked COORDINATE_SYSTEM as deprecated in favor of direct string usage.

• Kept COORDINATE_SYSTEM.IDENTITY as a deprecated alias to cartesian behavior.

• Switched internal coordinate-system handling from enum comparisons to string comparisons in:

  • modules/core/src/lib/layer.ts
  • modules/core/src/shaderlib/project/project-functions.ts
  • modules/core/src/shaderlib/project/viewport-uniforms.ts
  • modules/layers/src/bitmap-layer/bitmap-layer.ts
  • modules/aggregation-layers/src/heatmap-layer/heatmap-layer.ts
  • modules/layers/src/solid-polygon-layer/solid-polygon-layer.ts
  • modules/mesh-layers/src/utils/matrix.ts
  • modules/extensions/src/fp64/fp64-extension.ts

• Added an explicit string-to-shader mapping in modules/core/src/shaderlib/project/viewport-uniforms.ts via getShaderCoordinateSystem().

• Updated shader constant generation in:

  • modules/core/src/shaderlib/project/project.glsl.ts
  • modules/core/src/shaderlib/project/project.wgsl.ts
    so shader uniforms still receive numeric coordinate-system IDs even though the runtime API is now string-based.

• Updated modules/core/src/shaderlib/shadow/shadow.ts to compare against shader coordinate-system IDs instead of runtime enum values.

Behavior Changes

• coordinateSystem, fromCoordinateSystem, and _imageCoordinateSystem now use string values instead of numeric values.
• Raw legacy numeric coordinate-system inputs are no longer supported.
• Existing enum-style usage such as COORDINATE_SYSTEM.LNGLAT continues to work, but now resolves to strings.
• Direct consumers that relied on COORDINATE_SYSTEM.* being numeric will need to migrate.

Docs

• Updated core layer docs to describe coordinateSystem as a string-valued API and list supported string values.
• Updated bitmap layer docs to describe _imageCoordinateSystem as string-valued.
• Updated the JSON conversion reference example to use "meter-offsets" instead of numeric enum values.
• Added an upgrade-guide note calling out that coordinate-system constants are now string-valued and raw numeric inputs are unsupported.

Tests

• Updated import contract coverage to assert that deck.COORDINATE_SYSTEM.* exports strings.
• Updated project shaderlib tests to use string coordinate systems in the main cases.
• Added regression coverage for:
  • rejecting legacy numeric coordinate-system inputs
  • preserving deprecated COORDINATE_SYSTEM.IDENTITY cartesian behavior
• Updated related bench/test fixtures that still used raw numeric coordinate-system values.

Verification

• yarn vitest run --project node test/modules/imports.node.spec.ts
• yarn vitest run --project headless test/modules/core/shaderlib/project/viewport-uniforms.spec.ts test/modules/core/shaderlib/project/project-functions.spec.ts test/modules/layers/bitmap-layer.spec.ts

[coveralls]

coverage: 80.458% (+0.001%) from 80.457% — ib/coordinate-system-string into master

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 70cdaa0c52

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Normalize 'default' before rejecting coordinate systems

The new default branch now throws for any unrecognized coordinate system, but Layer.project() still forwards this.props.coordinateSystem directly and the layer default is now 'default' (modules/core/src/lib/layer.ts), so calling layer.project(...) on layers that keep the default coordinate system will now throw Invalid coordinateSystem: default. This regresses a public helper for common layer configurations; please normalize 'default' to 'lnglat'/'cartesian' (as projectPosition already does) before this check.

Useful? React with 👍 / 👎.

[chrisgervang]

Is the type recast at this point to make it impossible for the string value "default" to make it to this point?