Feature Request: Support US Survey Feet (`us-ft`) Units in Coordinates Class

Summary

Giro3D's Coordinates class does not recognize US Survey Feet (us-ft) as a valid unit, preventing Map entities from working with most US State Plane coordinate systems despite these CRS being fully supported by proj4.

Problem

When using CRS codes that specify +units=us-ft (such as EPSG:6434 - NAD83(2011) / Connecticut):

✅ CRS is successfully registered with Instance.registerCRS() via epsg.io
✅ Proj4 recognizes and handles the CRS correctly
✅ COPC point clouds load and display correctly
❌ Map entities fail with error: "Invalid crs parameter value 'EPSG:6434'"

Root Cause

File: node_modules/@giro3d/giro3d/src/core/geographic/Coordinates.ts

The unitFromProj4Unit() function (lines 45-62) only recognizes three unit types:

function unitFromProj4Unit(projunit: string | undefined) {
    switch (projunit) {
        case 'deg':
        case 'degrees':
        case 'degree':
            return UNIT.DEGREE;
        case 'm':
        case 'meter':
        case 'meters':
            return UNIT.METER;
        case 'ft':        // ✅ International Feet - SUPPORTED
        case 'foot':
        case 'feet':
            return UNIT.FOOT;
        default:
            return undefined;  // ❌ Returns undefined for 'us-ft'
    }
}

When us-ft is encountered, the function returns undefined, which causes crsToUnitWithError() (line 88-94) to throw the validation error.

What Works vs. What Doesn't

✅ Currently Supported Units

Unit	Proj4 String	Example CRS	Status
Degrees	`+units=deg`	EPSG:4326 (WGS84)	✅ Works
Meters	`+units=m`	EPSG:3857 (Web Mercator), EPSG:2992 (Oregon Lambert)	✅ Works
International Feet	`+units=ft`	EPSG:2914 (Oregon South), EPSG:6499 (Michigan South)	✅ Works

❌ Currently Unsupported Units

Unit	Proj4 String	Example CRS	Status
US Survey Feet	`+units=us-ft`	EPSG:6434 (Connecticut), EPSG:6435 (Delaware)	❌ Fails

Unit Differences

International Foot vs US Survey Foot:

International Foot: 1 ft = 0.3048 m (exact)
US Survey Foot: 1 ft = 0.30480061 m (exact)
Difference: ~2 parts per million (0.0006%)

While the difference is minimal, they use different proj4 unit identifiers (ft vs us-ft).

Impact

Affected CRS Codes

Most US State Plane coordinate systems use US Survey Feet and are affected:

States using us-ft (affected):

Connecticut: EPSG:6433, EPSG:6434
Delaware: EPSG:6435, EPSG:6436
Florida: EPSG:6437, EPSG:6438
And many more NAD83(2011) State Plane CRS codes

States using ft (not affected):

Oregon: EPSG:2914
Michigan: EPSG:6499
Arizona, Montana, North Dakota, South Carolina

User Impact

Users with COPC point cloud files in State Plane coordinate systems cannot:

❌ Add OpenStreetMap base layers
❌ Use Map entities for geographical context
❌ Display any imagery requiring the Map entity

This significantly limits Giro3D's usability for surveying, engineering, and GIS applications in the United States where State Plane coordinate systems are the standard.

Affected Files

The validation occurs in multiple locations:

src/core/geographic/Coordinates.ts
- Line 45-62: unitFromProj4Unit() - Missing us-ft case
- Line 88-94: crsToUnitWithError() - Throws validation error
- Line 195: Coordinates.set() - Calls validation
src/core/geographic/Extent.ts
- Line 256: assertCrsIsValid() - Validates CRS when creating extents for Map entities
src/entities/AxisGrid.ts
- Line 335: Uses crsToUnit() for grid labels

Request

Add support for us-ft (US Survey Feet) in the unitFromProj4Unit() function to enable compatibility with US State Plane coordinate systems.

This would bring Giro3D's unit recognition in line with proj4's capabilities, which already fully supports these coordinate systems.

Test Cases

Test with EPSG:6434 (Connecticut):

+proj=lcc +lat_0=40.8333333333333 +lon_0=-72.75 +lat_1=41.8666666666667 +lat_2=41.2
+x_0=304800.609601219 +y_0=152400.30480061 +ellps=GRS80 +units=us-ft +no_defs +type=crs

Test with EPSG:6435 (Delaware):

+proj=tmerc +lat_0=38 +lon_0=-75.4166666666667 +k=0.999995
+x_0=200000.0001016 +y_0=0 +ellps=GRS80 +units=us-ft +no_defs +type=crs

Expected Behavior After Fix

✅ CRS with +units=us-ft recognized as valid
✅ Map entities work with EPSG:6434 and similar State Plane CRS
✅ OSM layers display correctly for US State Plane coordinate systems
✅ No breaking changes to existing m, deg, or ft unit support

Current Workaround

We've implemented a workaround that detects unsupported CRS and disables Map entities with a warning:

const knownUnsupportedCRS = [
  'EPSG:6434', // NAD83(2011) / Connecticut
  'EPSG:6433', // NAD83(2011) / Connecticut (ftUS)
  'EPSG:6435', // NAD83(2011) / Delaware
  'EPSG:6436', // NAD83(2011) / Delaware (ftUS)
];

if (knownUnsupportedCRS.includes(srcCrs)) {
  console.warn('⚠️ OSM layer not supported for CRS:', srcCrs);
  return;
}

This requires maintaining a growing list of unsupported CRS codes, which is not sustainable.

Additional Context

Proj4 Support: ✅ Proj4 fully supports us-ft units (proj4-list)
CRS Registration: ✅ CRS definitions are successfully fetched from epsg.io and registered
Point Cloud Loading: ✅ COPC sources work correctly with these CRS
Map Entity Only: ❌ Only Map entity fails due to Coordinates class validation

References

EPSG Database: https://epsg.io/
Proj4 Documentation: https://proj.org/
US Survey Foot Definition: https://www.ngs.noaa.gov/PUBS_LIB/FedRegister/FRdoc59-5442.pdf
Proj4-list Repository: https://github.com/josueggh/proj4-list

Environment

Giro3D Version: v0.43.6 (latest as of 2025-10-31) ✅ Confirmed issue still exists
Proj4 Version: 2.9.0 (peer dependency)
Browser: Chrome, Firefox (reproduced in both)
Platform: Web application loading COPC files

Verification

✅ Confirmed in v0.43.6 (released 2025-10-06):

File: src/core/geographic/Coordinates.ts lines 45-62
The unitFromProj4Unit() function still only recognizes: deg, m, ft
No us-ft case exists in the switch statement
Changelog review shows no unit-related fixes in recent versions (v0.43.6 through v0.5.0)

Priority: Affects majority of US-based users working with standard surveying coordinate systems.

Edited Oct 31, 2025 by Ivan Bardak

Feature Request: Support US Survey Feet (us-ft) Units in Coordinates Class