OrbitCamera3D QML Type

Width over height of the frame; 0 while view is not set.

Distance to the pivot.

Vertical FOV of the camera.

What to keep in frame while it moves: a function returning a vector3d or an array of them, called every frame. Null is off.

The subject may drift within the inner part of the frame without the rig reacting (followSlack); once any point crosses that zone the pivot pans along the ground - never zooms - just far enough to bring it back, over followMs. A frame, fit or goTo made while a follow is on still happens; the follow only corrects what leaves the picture after it. The pan leash still applies, so a subject that walks past panLeash does get left behind - back the shot off, that is what fit's pad is for.

How long one follow correction glides; the lag of the pan.

How much of the half-frame the subject may cross before the rig pans: 0 pans at the first pixel, 0.25 (default) lets it reach three quarters of the way to the edge.

Distance the rig is travelling to.

Pitch the rig is travelling to.

Pivot the rig is travelling to.

Where the camera ends up, in world coordinates.

The rig's own position is the interpolant; this is the same point computed from the goal pose, which is what reanchor and zoomToward do their arithmetic in.

Yaw the rig is travelling to.

Glide while gripped. Zero, and rarely anything else.

A hand is driving the pose right now, so it does not glide.

The distinction smoothMs was missing. A glide is right for a move the rig makes on its own - a focusOn, a scenario reframing itself, an arrow key - because there the eye needs to be carried along. It is wrong for a drag: grab-the-ground panning promises that the point under the cursor stays under the cursor, and a pose easing towards its goal over 150 ms mathematically cannot keep that promise. The ground trails the hand, and the rig reads as something heavy being nudged rather than as a sheet being pushed.

OrbitInput3D sets this for the length of a drag (and of the coast out of a flick, which is the same gesture still finishing). Everything else keeps its glide.

A frameWithReturn dive is open, so the next one comes home.

What a lab shows in its hint bar, so the second press of the framing key is offered rather than discovered.

The point panLeash measures from. Defaults to the origin.

How many places back the jumplist remembers.

Bounded because the alternative is a session-long leak of poses nobody will ever walk back to; the oldest entry falls off the bottom.

Places jumpForward can still take you.

Places jumpBack can still take you.

How much overshoot the leash allows, as a fraction of itself.

Past panLeash the pull-back grows exponentially, so the pivot can never get further than panLeash * (1 + leashSoftness) but the drag never stops dead either.

Furthest allowed retreat.

Steepest allowed angle (< 90).

Closest allowed approach.

Lowest the camera may sit above the pivot plane.

The leash: flattening the angle backs the rig off instead of letting it sink through the ground.

Flattest allowed angle.

How deep the pivot may sink: exactly as far as it can climb out of.

The height floor is a rule about the camera, and _fitDistance enforces it by backing the rig off - but backing off runs out at maxDistance. From a pivot deeper than that, no legal pose keeps the eye above ground, and the floor silently stops being a floor.

This is the missing half, and it is why the rule is a property rather than a line inside reanchor, which is where it used to live: only that one method consulted it, so orbitAround - which rotates the pivot rigidly and can therefore drive it hundreds of units under the ground - walked straight through. Every mutator goes through _fitPivot, so putting it there is what makes "never under the floor" true of the rig rather than of one method.

Furthest the pivot may wander from homePivot; 0 is no limit.

Measured in the ground plane (XZ), so height never counts against it.

Angle above the pivot plane, degrees.

The point the camera looks at.

Glide time for every move, in milliseconds; 0 snaps.

Built in rather than left to the lab so that all four pose properties ease together - a rig with a Behavior on distance and none on pivot swings while it zooms. Declaring your own Behavior on a pose property is a duplicate-binding error; change this instead.

Glide time for a goTo / focusOn journey, in milliseconds.

Longer than smoothMs on purpose: a hand-driven orbit wants to feel immediate, a jump across the scene wants to be followed with the eye.

A glide is in progress.

The View3D this rig renders through. Optional.

What tells the rig the shape of its frame. Without it every fit is made against the vertical field alone, which is right for a landscape window and too tight for a portrait one; with it aspect is known and fit composes against the real picture. Nothing else reads it.

Named poses, as { name: {yaw, pitch, distance, px, py, pz} }.

Any subset of the fields a state() carries; what is left out keeps its current value, so { pitch: 84 } is a legal "look straight down from wherever you are". goTo travels to one.

Angle around the pivot, degrees.

Restores a pose produced by state(). Missing fields keep theirs.

Re-applies the limits to the pose the rig is in right now.

For after a limit changes (a new maxDistance, a tighter minHeight, a shorter panLeash). It is not the way to apply a pose - see the note on setDistance.

Forgets everywhere the rig has been.

For a scene that has been replaced under the camera - a scenario applied, a board cleared - where the recorded poses now describe places in a world that no longer exists. Walking the list cannot do this: jumpBack and jumpForward only move an entry from one side to the other, which is what makes them reversible.

Forgets the open frameWithReturn excursion.

For a lab that ends one by other means - a scenario change, a scene rebuilt under the camera - where the pose the dive began from no longer describes anywhere the viewer would recognise.

Whether every point is inside the frame, margin (0..1, a fraction of the half-frame) away from its edges.

The question a shot is verified by: not "did the camera move" but "is the thing still in the picture". goal as for project.

Composes a shot: every point inside the picture, as close as that allows.

The screen-space fit. points is an array of vector3d (or {x, y, z}); opts is an optional object:

• yaw, pitch - the angles to shoot from; either alone is fine, what is left out keeps its goal value. Folded into the same glide.
• pad - headroom factor on the distance found (default 1.15).
• safe - {top, bottom, left, right}, each the fraction of the frame that is NOT picture: chrome, a flow bar, a hint strip. The points are fitted into what is left and centred in it, so a bar along the bottom moves the subject up rather than shrinking it.
• aspect - overrides aspect for this shot.
• ms - glide time for this move; left out, the rig's current glide applies (smoothMs, or travelMs inside a journey).

Where frame fits a sphere against the vertical field and keeps the pivot on the centre of the points, this projects every point and finds the nearest distance at which all of them sit inside the safe rectangle, shifting the pivot within the image plane to centre them there. The pivot may therefore leave the ground; minPivotY still bounds it. Returns false when there is nothing to fit. Clears the frameWithReturn excursion, like frame.

Travels to a point or a set of points and frames them.

what is a single vector3d (or {x, y, z}) or an array of them. A single point keeps the current distance and only re-centres - framing a point has no extent to fit, and diving at it is never what was meant. ms overrides travelMs for this journey.

The verb a lab's own picking calls: the input layer never decides what is worth looking at, it only offers the ride.

A journey, so it pushJump s: this is where you were before you dived at something, and jumpBack is how you get back.

Centres on the given world points and backs off until they fit.

points is an array of vector3d (or {x, y, z}); pad is a headroom factor (1.0 = tight, 1.3 = comfortable). Keeps the current yaw/pitch, so framing never disorients the viewer - unless angles asks for a specific one: an optional {yaw, pitch} (either field alone is fine) folded into the same single glide. For the framing that IS a deliberate change of viewpoint - a lab dropping to eye level while a character presents - where framing first and pitching second would move the camera twice.

Dives onto points, and the next call on the same thing comes back.

The framing key pressed twice is a round trip: dive in to read a value up close, press it again, and the overview you left is restored exactly - including the yaw you had turned to, which is what "exactly" has to mean or the second press is just another reframing.

• No return pose stored: remembers where you are and frames points.
• Stored, and points is the same extent again (or nothing is selected at all): flies home and forgets.
• Stored, and points is a different extent: reframes onto it and keeps the original return pose. The loop always closes where it began - walking from part to part is one excursion, not a chain of them, and the way home does not drift with it.

Sameness is the extent, not the selection: this layer has never been told what a part is, and the centre and radius of what it was asked to frame is the whole of what it can compare. Two different selections that occupy the same box are one place as far as the camera is concerned, which is also how they look.

Returns false only when there was nothing to do - no points and no way home. Any jump (goTo, focusOn, jumpBack) and any plain frame drops the return pose: those are departures, not the end of an excursion.

Travels to the named viewpoint; false if there is no such name.

Yaw takes the short way round: a rig turned three times over does not unwind on the way to a viewpoint that says yaw: 0.

Named places are jumps, so this pushJump s - and a name that does not exist does not, because it did not go anywhere.

Travels to the place before the last jump; false at the end.

False is the interesting half: nothing moves and the caller is expected to say so, because a key that silently does nothing reads as broken. The pose being left is put on the forward list, so the walk is reversible by jumpForward for as long as no new jump happens.

Undoes a jumpBack; false when there is nothing ahead.

Turns the rig about anchor instead of about the pivot.

The point of the gesture: anchor keeps its place on screen while everything else swings around it, because the rig is rotated rigidly - camera and pivot together, about the axes through anchor. orbitBy turns about the pivot, so anything else you were looking at slides off; this is what "turn about what I am pointing at" actually means.

The rotation is applied to the pivot, so the pivot generally leaves the ground plane - that is the price, and reanchor is what keeps it small: from a pivot already at the anchor's depth the two are almost the same point. Pitch clamping is honoured (only the allowed part of dPitch is applied to both), and the leash and the height floor still outrank the anchor - they are the only things that can shift it on screen. With no anchor it is orbitBy.

Turns the rig, then re-applies the leash.

Slides the pivot along the ground, in world units.

dRight is screen-right and dAway is screen-up projected onto the ground - both relative to the current yaw, which is what makes a drag feel like it is moving the scene rather than the axes. The height of the pivot is untouched, and panLeash still applies.

Where a world point lands in the frame, without a View3D.

Returns {x, y, depth}: x and y normalized so that -1..1 is the picture (y up), depth the distance in front of the lens - a point at or behind it has depth <= 0 and its x/y mean nothing. Computed from the rig's own pose, so it answers for a rig that is not rendering at all; goal true projects through the goal pose rather than the interpolant, which is what a follow correction needs.

Records the pose the rig is in as a place worth coming back to.

goTo, focusOn and frameWithReturn call it themselves; anything else that means a jump rather than travel calls it first - a lab's reset-the-view key, a flow step that aims the camera, a hint label selected and flown to. Travel deliberately does not: a jumplist that filled up with every drag would have nothing recognisable left in it, which is exactly why vim distinguishes the two.

Clears the forward list, because history that was walked back and then left is no longer where you are going - unless the jump turns out not to move the rig at all, and then nothing about the memory changes. A key that went nowhere must leave no trace, or the next jumpBack answers for a press that did nothing.

Moves the pivot to what you pointed at, without moving the camera.

The turn-around-what-I-am-looking-at gesture: press over a rooftop and the orbit that follows circles that, not the middle of the scene.

The pivot lands on the view axis at p's depth - the point of the axis nearest p - and the distance is re-derived so that goalPosition and the rig's rotation come out bit-for-bit unchanged. That last part is the whole point: a rig whose rotation is derived from the pivot cannot both aim somewhere else and keep the picture, so re-anchoring onto an off-centre point would swing the picked thing into the middle of the screen - exactly the jump this is meant to avoid. Anchoring at its depth turns about it instead, and the image does not move at all.

Returns false when there was nothing to anchor to. The leash still applies: re-anchoring outside panLeash is pulled back like any other pivot move, and that pull is the only thing that can shift the camera here. A point so far away that the axis has already dived under the ground anchors as deep as the rig can still climb back out of - see minHeight.

Moves to d with the leash applied - the safe way to set it.

Prefer this over writing distance directly: it limits the value before the single write, so it stays correct on a rig that animates its distance.

Moves what the camera looks at, on the leash.

Pose as a JSON-serializable object, for the viewState convention.

The goal pose, so a rig serialized mid-glide restores where it was going rather than the frame it was caught on.

The names goTo accepts.

World units one pixel covers at the pivot's depth.

What turns a drag in pixels into a pan in metres. Exact in the middle of the view at the pivot plane, which is where a grab-the-ground drag is judged.

Multiplies the distance (0.9 zooms in, 1.1 out).

Zooms along the ray to p, so p keeps its place on screen.

Wheel-to-cursor. zoomBy pulls the camera towards the pivot, which walks whatever you were aiming at off the edge of the screen; this moves the camera along the line towards p instead and slides the pivot the same fraction, so the rotation is untouched and p stays on exactly the pixel it was on.

factor is zoomBy's (0.9 in, 1.1 out), and the limits still cut it short: what the distance was actually allowed to do is what the pivot moves by, so a zoom that hits minDistance stops travelling too. With no p it is zoomBy.