3dtiles-geo-transform

A geographic coordinate transformation library for 3D Tiles, providing ECEF (Earth-Centered, Earth-Fixed) coordinate transformations and CESIUM_RTC extension support for Three.js and React applications.

Features

• 🌍 Geographic Coordinate Transformation: Convert 3D Tiles from ECEF/WGS84 coordinates to local coordinate systems
• 🎮 CESIUM_RTC Support: Handle Cesium's Relative To Center (RTC) extension for improved precision
• ⚡ Three.js Integration: Seamless integration with Three.js for 3D rendering
• ⚛️ React Components: Ready-to-use React components for React Three Fiber applications
• 📦 TypeScript Support: Full TypeScript definitions included
• 🚀 Framework Agnostic Core: Core transformation logic can be used independently

Installation

npm install 3dtiles-geo-transform

or

yarn add 3dtiles-geo-transform

Quick Start

Basic Three.js Usage

import { CesiumRTCPlugin, createTransformMatrix } from '3dtiles-geo-transform';
import { TilesRenderer } from '3d-tiles-renderer';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';

// Setup GLTF loader with CESIUM_RTC support
const gltfLoader = new GLTFLoader();
gltfLoader.register((parser) => new CesiumRTCPlugin(parser));

// Create tiles renderer
const tilesRenderer = new TilesRenderer(tilesetUrl);
tilesRenderer.manager.addHandler(/\.gltf$/, gltfLoader);

// Apply geographic transformation
const center = new THREE.Vector3(x, y, z); // ECEF coordinates
const transformMatrix = createTransformMatrix(center);
tilesRenderer.group.applyMatrix4(transformMatrix);

React Three Fiber Usage

import { TilesetTransformComponent } from '3dtiles-geo-transform';
import { Canvas } from '@react-three/fiber';

function App() {
  return (
    <Canvas>
      <TilesetTransformComponent>
        {/* Your 3D Tiles components */}
      </TilesetTransformComponent>
    </Canvas>
  );
}

API Reference

Core Functions

ecefToLngLat(x, y, z)

Convert ECEF coordinates to longitude/latitude/height.

lngLatToEcef(lng, lat, height)

Convert longitude/latitude/height to ECEF coordinates.

createTransformMatrix(center)

Create a transformation matrix for converting from ECEF to local coordinates.

Three.js Classes

CesiumRTCPlugin

GLTFLoader plugin for handling CESIUM_RTC extension.

const plugin = new CesiumRTCPlugin(parser);

TilesetTransform

Class for managing 3D tileset transformations.

React Components

TilesetTransformComponent

React component that provides transformation context for child components.

Supported Data

This library works with any 3D Tiles dataset that uses:

• WGS84/ECEF coordinate system
• CESIUM_RTC extension
• Standard 3D Tiles format (OGC specification)

Compatible with:

• Geographic 3D city models
• Cesium ion tilesets
• Any geographic 3D Tiles data

Example

Check out the example/ directory for a complete working example using geographic 3D Tiles data.

cd example
npm install
npm start

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Start development mode
npm run dev

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

• [ ] Babylon.js support
• [ ] WebGL-only implementation
• [ ] Additional coordinate systems support
• [ ] Performance optimizations

Credits

This library is designed to work with geographic 3D Tiles data from various sources, including government and commercial providers worldwide.