Skip to content

API.md

Latest commit

 

History

History
556 lines (373 loc) · 8.69 KB

API.md

File metadata and controls

556 lines (373 loc) · 8.69 KB

3d-tiles-renderer/r3f

CanvasDOMOverlay

Creates a DOM overlay positioned absolutely over the canvas. Children are rendered into a separate React root. Remaining props are passed to the root div element.

Props

<CanvasDOMOverlay
	children?: ReactNode
/>

.children

children?: ReactNode

DOM content to render in the overlay.

CameraTransition

Manages transitions between perspective and orthographic cameras. Wraps CameraTransitionManager and integrates with R3F's camera state. All CameraTransitionManager properties can be set as props.

Props

<CameraTransition
	mode?: string = 'perspective'
	perspectiveCamera?: PerspectiveCamera
	orthographicCamera?: OrthographicCamera
	onBeforeToggle?: function
/>

.mode

mode?: string = 'perspective'

Active camera mode: 'perspective' or 'orthographic'.

.perspectiveCamera

perspectiveCamera?: PerspectiveCamera

Override the internal perspective camera.

.orthographicCamera

orthographicCamera?: OrthographicCamera

Override the internal orthographic camera.

.onBeforeToggle

onBeforeToggle?: function

Called before the camera mode switches, with the manager and target camera as arguments. Defaults to syncing via active controls if present.

TilesAttributionOverlay

Displays attributions collected from the loaded tileset. Must be a child of TilesRenderer. Remaining props are passed to the underlying CanvasDOMOverlay element.

Props

<TilesAttributionOverlay
	generateAttributions?: function
	style?: Object
	children?: ReactNode
/>

.generateAttributions

generateAttributions?: function

Custom function to generate attribution elements. Receives the attributions array and the overlay element's unique id. Defaults to built-in rendering.

.style

style?: Object

Style overrides applied to the overlay container.

.children

children?: ReactNode

Additional content rendered above the attributions.

AnimatedSettledObject

A SettledObject that smoothly interpolates its position as the query result updates. Must be a descendant of SettledObjects.

Props

<AnimatedSettledObject
	interpolationFactor?: number = 0.025
	onQueryUpdate?: function
/>

.interpolationFactor

interpolationFactor?: number = 0.025

Controls interpolation speed. Smaller values produce slower, smoother movement.

.onQueryUpdate

onQueryUpdate?: function

Called with the raycast hit result each time the query updates.

EastNorthUpFrame

Creates a group positioned and oriented at a geographic coordinate on the tileset ellipsoid. Must be a child of TilesRenderer. Does not modify the tileset transform.

Props

<EastNorthUpFrame
	lat?: number = 0
	lon?: number = 0
	height?: number = 0
	az?: number = 0
	el?: number = 0
	roll?: number = 0
	ellipsoid?: Ellipsoid
	children?: ReactNode
/>

.lat

lat?: number = 0

Latitude in radians.

.lon

lon?: number = 0

Longitude in radians.

.height

height?: number = 0

Height above the ellipsoid in meters.

.az

az?: number = 0

Azimuth rotation in radians, applied first.

.el

el?: number = 0

Elevation rotation in radians, applied second.

.roll

roll?: number = 0

Roll rotation in radians, applied third.

.ellipsoid

ellipsoid?: Ellipsoid

Ellipsoid to use when no TilesRenderer parent is present.

.children

children?: ReactNode

Children positioned relative to the east-north-up frame.

EnvironmentControls

Wraps the three.js EnvironmentControls class. Automatically attaches to the R3F camera, scene, and canvas. All EnvironmentControls properties can be set as props.

Props

<EnvironmentControls
	camera?: Camera
	scene?: Object3D
	domElement?: HTMLCanvasElement
/>

.camera

camera?: Camera

Override the default R3F camera.

.scene

scene?: Object3D

Override the default R3F scene.

.domElement

domElement?: HTMLCanvasElement

Override the default canvas element.

GlobeControls

Wraps the three.js GlobeControls class. Must be a child of TilesRenderer to receive ellipsoid context. All GlobeControls properties can be set as props.

Props

<GlobeControls
	camera?: Camera
	scene?: Object3D
	domElement?: HTMLCanvasElement
/>

.camera

camera?: Camera

Override the default R3F camera.

.scene

scene?: Object3D

Override the default R3F scene.

.domElement

domElement?: HTMLCanvasElement

Override the default canvas element.

SettledObject

Positions a component on the surface of the tileset at a lat/lon coordinate or along a ray. Must be a descendant of SettledObjects.

Props

<SettledObject
	component?: ReactNode = <group/>
	lat?: number = null
	lon?: number = null
	rayorigin?: Vector3 = null
	raydirection?: Vector3 = null
	onQueryUpdate?: function
/>

.component

component?: ReactNode = <group/>

The element to clone and position on the surface.

.lat

lat?: number = null

Latitude in radians. Use with lon for geographic positioning.

.lon

lon?: number = null

Longitude in radians. Use with lat for geographic positioning.

.rayorigin

rayorigin?: Vector3 = null

Ray origin for arbitrary ray-based positioning.

.raydirection

raydirection?: Vector3 = null

Ray direction for arbitrary ray-based positioning.

.onQueryUpdate

onQueryUpdate?: function

Called with the raycast hit result each time the query updates.

CompassGizmo

Renders a compass overlay that rotates to indicate north based on the camera orientation relative to the tileset ellipsoid. Must be a child of TilesRenderer. Remaining props are passed to the root group element.

Props

<CompassGizmo
	mode?: string = '3d'
	scale?: number = 35
	margin?: number | Array = 10
	visible?: boolean = true
	overrideRenderLoop?: boolean
	children?: ReactNode
/>

.mode

mode?: string = '3d'

Rotation mode: '3d' tracks full camera orientation, '2d' tracks yaw only.

.scale

scale?: number = 35

Size of the compass in pixels.

.margin

margin?: number | Array = 10

Margin from the bottom-right corner in pixels. Pass [x, y] to set each axis independently.

.visible

visible?: boolean = true

Whether the compass is rendered.

.overrideRenderLoop

overrideRenderLoop?: boolean

If true, renders the main scene before drawing the compass overlay.

.children

children?: ReactNode

Custom compass graphic replacing the default. Should fit within a -0.5 to 0.5 unit cube with +Y pointing north and +X pointing east.

TilesPlugin

Registers a plugin on the nearest parent TilesRenderer. Must be a child of TilesRenderer. All properties on the plugin instance can be set as props directly. Note that some plugin properties cannot be changed after construction.

Props

<TilesPlugin
	plugin: function
	args?: Object | Array
	children?: ReactNode
/>

.plugin

plugin: function

The plugin class to instantiate.

.args

args?: Object | Array

Constructor arguments: an object (single arg) or array (spread as multiple args).

.children

children?: ReactNode

Children rendered once the plugin is registered.

SettledObjects

Manages raycasting queries against the tileset for positioning child SettledObject components. Must be a child of TilesRenderer. All QueryManager properties can be set as props.

Props

<SettledObjects
	scene?: Object3D | Array
	children?: ReactNode
/>

.scene

scene?: Object3D | Array

Scene(s) to raycast against. Defaults to the R3F scene.

.children

children?: ReactNode

SettledObject or AnimatedSettledObject components.

TilesRenderer

Wrapper for the three.js TilesRenderer class. All properties on the TilesRenderer instance can be set as props using dot-notation for nested properties (e.g. lruCache-minSize). Events are registered with a camel-cased on prefix (e.g. onLoadModel).

Props

<TilesRenderer
	url?: string
	enabled?: boolean = true
	group?: Object
	children?: ReactNode
/>

.url

url?: string

URL of the tileset to load.

.enabled

enabled?: boolean = true

If false, update is not called on the renderer each frame.

.group

group?: Object

Props applied to the root Three.js group of the tileset.

.children

children?: ReactNode

Child components such as TilesPlugin, GlobeControls, etc.