Skip to main content

Crate three_rs_controls

Crate three_rs_controls 

Source
Expand description

three-rs-controls — a camera over a ground, and the ground.

An addon in the sense of three.js’ examples/jsm/controls/: it depends on three-rs the way any user would and is not a port of anything in three.js’ src/. Ground and MapControls are this crate’s own design; smooth_damp is camera-controls’, not three.js’.

Ground is a sphere with a distinguished point at the world origin and arc-length coordinates around it; at its largest radius it is a plane to the eye. MapControls drives a camera over it the way three.js’ MapControls drives one over a map — the ground is what you grab — with camera-controls’ smoothDamp on every field.

use three_rs::cameras::PerspectiveCamera;
use three_rs_controls::{Ground, MapControls, Pose};

let mut controls = MapControls::new(
    Ground::new(1e7),
    Pose {
        u: 0.0,
        v: 0.0,
        distance: 160.0,
        azimuth: 0.0,
        polar: 0.0,
    },
);

let mut camera = PerspectiveCamera::new(60.0, 16.0 / 9.0, 1.0, 50_000.0);
controls.update(1.0 / 60.0);
controls.apply(&mut camera);

Structs§

Damping
The feel: three smooth times and the wheel’s step. camera-controls exposes smoothTime and draggingSmoothTime as properties for the same reason — an app tunes the feel for itself:
Frame
An orthonormal frame on the ground: where a point is and which way is along-the-surface east, along-the-surface north, and up.
Ground
A sphere of radius radius centred at ( 0, -radius, 0 ), so that ground coordinate ( 0, 0 ) is the world origin with normal +Y for every radius — content authored on a plane keeps its place when the ground is curled up.
MapControls
A map camera over a Ground, damped the way camera-controls damps.
Pane
One rectangle lying flat on the ground, face up, for the overview to fit and the pointer to pick.
Pose
Where the camera is: an orbit target on the ground, and a direction and distance from it.

Enums§

Mode
Free movement, or the overview the pane set is fitted into.

Constants§

DRAGGING_SMOOTH_TIME
CameraControls.draggingSmoothTime, whose default is 0.125. See the module docs for why it is a third of that.
MAX_DISTANCE
OrbitControls.maxDistance.
MAX_POLAR
OrbitControls.maxPolarAngle — misc_controls_map.html uses π / 2, which puts the eye on the ground. 85° keeps the horizon in shot instead.
MAX_RADIUS
The largest ground radius. At 1e7 a sphere is a plane to the eye — the drop over the 800-unit demo grid is a centimetre and a half — while every term below stays finite, which is why there is no separate plane case.
MIN_DISTANCE
OrbitControls.minDistance.
MIN_POLAR
OrbitControls.minPolarAngle. Not 0: there the offset is parallel to up and Matrix4.lookAt() has to nudge itself out of the degeneracy.
MIN_RADIUS
The smallest ground radius. Below this the curvature is so tight that a camera at the altitude ceiling is further from the surface than the surface is wide, and the exponential map stops being a useful coordinate system.
PANE_LIFT
How far a pane floats above the ground, so that it is not z-fighting the surface it lies on.
REST_THRESHOLD
CameraControls.restThreshold.
SMOOTH_TIME
CameraControls.smoothTime, at its default.
WHEEL_SMOOTH_TIME
The smooth time a wheel notch is damped with. camera-controls has no such thing — a notch eases over smoothTime — but a zoom wants to snap where a release glide wants to ease, so it is its own knob.

Functions§

smooth_damp
smoothDamp() from yomotsu’s camera-controls (src/utils/math-utils.ts), itself Unity’s Mathf.SmoothDamp and Game Programming Gems 4 chapter 1.10.