3d-tiles-renderer

The 3d-tiles-renderer library provides a JavaScript implementation for the 3D Tiles format with support for multiple rendering engines. Depending on your project's engine, you will use different entry points:

Core API

• 3d-tiles-renderer/core: The base implementation.

Engine-Specific APIs

• 3d-tiles-renderer/three: For Three.js users. Includes a dedicated usage guide and plugin system.
• 3d-tiles-renderer/babylonjs: For Babylon.js users.
• 3d-tiles-renderer/r3f: For React Three Fiber users.

Plugin APIs

• 3d-tiles-renderer/three/plugins: Plugins specifically for Three.js.
• 3d-tiles-renderer/core/plugins: Core-level plugins.

The 3d-tiles-renderer/r3f package provides a set of React components designed to load and render 3D Tiles within a @react-three/fiber (R3F) environment. You can use the <TilesRenderer /> component to load a tileset via a URL, or compose it with other components like <TilesPlugin />, <GlobeControls />, and <TilesAttributionOverlay /> for advanced features.

import { TilesRenderer } from '3d-tiles-renderer/r3f';

const TILESET_URL = /* your tileset url */;
const cameraPosition = [ x, y, z ];

export default function App() {
  return (
    <Canvas camera={ { position: cameraPosition } }>
      <TilesRenderer url={ TILESET_URL } />
    </Canvas>
  );
}

The 3d-tiles-renderer/core package provides the framework-agnostic foundation of the 3D Tiles renderer. It includes the base TilesRendererBase class, scheduling logic, parsing utilities, and shared core functions.

When to use this package: Use this package only if you are building a custom renderer integration from scratch.

When NOT to use this package: If you are using Three.js or Babylon.js, do not use the core package directly. Instead, use the specialized renderer packages designed for those frameworks:

• For Three.js: Use 3d-tiles-renderer/three
• For Babylon.js: Use 3d-tiles-renderer/babylonjs

import { TilesRendererBase } from '3d-tiles-renderer/core';

The SettledObjects component acts as a manager that performs raycasting queries against the tileset to find surface positions. It must be a child of TilesRenderer. It accepts SettledObject or AnimatedSettledObject components as children.

• SettledObjects: Manages the query lifecycle and provides the context for raycasting.
• SettledObject: The individual element being positioned. It can be positioned by latitude/longitude or by a ray.
• AnimatedSettledObject: A specialized version of SettledObject that uses an interpolationFactor to smoothly move the component when the query result changes, preventing jitter.

The renderer is designed to be resilient to various loading failures:

• Missing tileset.json: If the main tileset file is not found, the renderer should log the error exactly once and stop attempting downloads.
• Broken Parent Tiles: If a parent tile fails to load, child tiles should still be able to load and render.
• Empty Root Content: If the root tile has no content, the tileset should still render correctly once children are loaded.
• Broken External Tilesets: If an external tileset fails to load, the rest of the main tileset should continue to function, leaving a gap where the external content would have been.

TilesRendererBase is the base class for all 3D Tiles renderers. It manages the core lifecycle of a tileset, including tile loading, caching, traversal, and a plugin system. Engine-specific renderers (like those for Three.js) extend this class to handle camera projection and scene management.

Key responsibilities include:

• Tile Management: Handles loading, parsing, and caching via lruCache.
• Concurrency Control: Uses downloadQueue, parseQueue, and processNodeQueue to manage background tasks.
• Traversal: The update() method runs the traversal loop, which should be called once per frame after camera updates.

When using additive tilesets (where multiple layers are rendered on top of each other):

• Rendering: With colorMode set to RANDOM_COLOR, all layers (including the root) should render on top of each other. Increasing the errorTarget should cause deeper tiles to disappear.
• Raycasting: When clicking on additive layers, the renderer should return the correct depth (e.g., depth 0 for the root tile, depth 1 for a child tile).

The TileTraversalData object contains the per-frame traversal state for a tile, which is updated during TilesRendererBase.update. This data is useful for debugging visibility, performance, or custom traversal logic.

Key properties include:

• .distanceFromCamera: The distance from the tile bounds to the nearest active camera.
• .error: The computed screen space error (SSE) for the tile.
• .inFrustum: Boolean indicating if the tile was within the camera frustum during the last update.
• .isLeaf: Boolean indicating if the tile is a leaf node in the used tile tree.
• .used: Boolean indicating if the tile was visited during the current update traversal.
• .usedLastFrame: Boolean indicating if the tile was visited in the previous frame.
• .visible: Boolean indicating if the tile is currently visible (meaning it is loaded, within the frustum, and meets the SSE requirements).

The renderer manages tile visibility based on the camera frustum and specific configuration options:

• Frustum Culling: Only tiles within the camera's view frustum should be displayed.
• Multiple Cameras: If multiple cameras are active, the renderer accounts for all of them. Tiles are only displayed if they are within the frustum of both cameras, and geometric error is calculated relative to the nearest camera.
• displayActiveTiles: When enabled, tiles are displayed even if they are not currently 'active' in the LOD selection (e.g., when zoomed out).
• maxDepth: Limits how deep into the tileset hierarchy the renderer will go. No tiles should be displayed at or above the maxDepth value.

To use the 3d-tiles-renderer in your project, install it using npm:

npm install 3d-tiles-renderer --save