Twelve camera roles in six families. An author names a role instead of building a pose, and the framing solver turns it into a pitch, a distance and a field of view fitted to the objects on this bench. Within a family the roles share a direction and differ in how close they sit or what they frame.
Presets only set the starting vantage at each authored moment; the student can freely rotate, zoom, and pitch (mouse wheel / arrows / right-click drag) between them.
Roles — 12 · Families — 6 · Rules — 7 · Applied examples — 3
Two questions pick the role. What does the step name: nothing (the whole scene), one
object:, or a list of objects:? And from what angle should
the student see it? Every role sits in exactly one cell.
| Angle | Whole scenenames nothing | One objectobject: | Several objectsobjects: |
|---|---|---|---|
| Opening27° | intro | — | — |
| Low31° solver default | — | phenomenonphenomenon_close | comparecompare_close |
| Working angle50° | workingworking_close | — | — |
| High75° | — | — | working_high |
| Top-down85° | overhead | — | overhead_focusedoverhead_close |
| Head-onfaces the display | — | instrument | — |
Distance is a multiple of the tight fit around the role’s targets, so the same role works on a small bench or a large one. Below 1.0× the camera sits inside the fit and magnifies; above it, the frame leaves room around the targets. When a role reads too far, step to its close variant rather than overriding the distance.
The establishing shot. One role.
Wide opening over the whole desk, slightly above eye level, so a fresh viewer takes in the full layout.
working. Pulling out to intro between two close shots is jarring.The student’s working angle, slightly behind them. Most steps live here.
Mid-distance, scene-wide, at the angle someone takes when they reach forward to the desk. The default role.
instrument. Flat layouts → overhead.Same angle as working, dollied in. The whole compact prop set stays in frame at near arm’s length.
working.phenomenon or instrument. Spread-out props → stay on working.Tilted up to 75° on a list of objects, to read displays mounted high while keeping the rig’s height readable.
overhead_focused. Flat desk layouts → working.Top-down at 85°. The three differ only in what they fit and how close they sit.
Near-vertical view of the whole scene, with just enough tilt to tell heights from shadows.
overhead_focused. Tall apparatus → working_high.Top-down on a list of objects; everything else on the desk drops out of frame.
overhead. Fine detail → overhead_close.Tight top-down on a list of objects, well inside the fit: an aggressive close-up from above.
overhead_focused. Vertical displays → instrument.Head-on to one display. One role.
Tight, head-on framing of one instrument’s display. The camera turns to face the object’s display anchor, so a vertical thermometer and a top-facing scale both read square.
phenomenon, or an explicit pose.One object, no readout in frame. Fitted to the object’s own shape.
Close on one science object, generous enough that its whole form stays readable.
instrument. Two or more objects → compare.Leans right in on one object, at 0.3× the fit: the tightest role in the library.
compare_close. Keep the whole set visible → working_close.Several objects side by side, equal weight.
Sized to fit every named object at the tight fit; unrelated props drop out of frame.
compare_close. One object → phenomenon or instrument.Close-up on a small set of related objects, tight enough to read sub-centimetre features.
compare. One object → phenomenon_close.
A role is the preferred way to move the camera. The same role: works in
every camera block: camera_ui: while the student acts,
camera_op: while the simulation runs, zoom_in: on a button
the student presses, or a camera step of its own. Fall back to explicit framing
constraints only when no role fits.
Name nothing; the role fits every object on the bench.
camera_ui:
role: workingFor instrument and the phenomenon family.
camera_op:
role: instrument
object: scale1For compare, working_high and the focused overheads.
camera_ui:
role: compare
objects: [cup_warm, cup_cool]Every authored vantage has a pedagogical reason.
Don't add a preset because "the scene looks nicer from there". Add one because there is a specific thing the student must see. If you can't answer what must be visible in one sentence, the preset isn't earned.
Pitch is chosen by the face being observed.
Match the camera's pitch to the face the student reads: flat, top-facing
surfaces (paper, top-facing digital scales) want the overhead family at 85°;
volumetric objects (cups, coils) want the working angle at 50° for depth cues
during a drag; vertical-face readouts (thermometer scales, upright
dials) want a near-horizontal camera — a thermometer standing in a
cup is unreadable from above. instrument handles this on its own
by turning to face the object's display.
Distance is chosen by the legibility requirement.
If digits or needles must be read, the role must sit close enough to read
them without further zoom. If an object must be grabbed, close enough to make
it grab-size. Distance is a multiple of the fit around the targets, so pick
the role by how close it sits: from phenomenon_close at 0.3× to
intro at 1.6×.
Name the objects; don't place the orbit target by hand.
A role given object: or objects: centres the camera
on them. Set an orbit_target by hand, in an explicit pose, only
for a one-off composition no role covers. If the same composition keeps
coming back, propose a role for it.
Lerp durations communicate intent.
Step-to-step: 300–400 ms, trackable.
Opening intro → working: 1000–1500 ms, cinematic.
Reading zoom-ins: 400–600 ms, slightly slow so the student
registers their action caused it. Exits back to working:
250–350 ms, snap-back feel.
Readings that would be illegible at a shared vantage get their own step.
If two instruments are too far apart — or too small at one zoom — to read
together, split them into separate steps. Each uses instrument,
phenomenon or a close variant, with Continue or Unpause. Exit
lerps back to working before the next step's preset takes over.
Full rule in the authoring-patterns section.
Student freedom is never suspended.
After a preset lerps into place, the student can rotate, zoom, and tilt —
even during paused_reading. Time is frozen, the camera isn't.
overhead_focused or
compare_close where they fit better.
The wide shot the student sees on load. Orientation, not interaction — the camera lerps inward to a working angle on step 1.
Why this zoom
distance 2.77 m fits coil, battery, four compasses and every
clip with breathing room. pitch 27° reads as "standing at the
desk" — physically present, not schematic — priming a hands-on expectation.
{ yaw: 90.3, pitch: 27.1, distance: 2.768, fov: 55 }
initial_camera; step 1 lerps into
setup_view over 1.2 s.
The "doing work" angle — clip connections, compass placement. The camera rests here after the opening lerp and returns here after every observation.
Why this zoom
distance 0.70 m makes the coil and clip targets grab-sized
(1:1 drag feel) while the far end of the coil stays in frame — no mid-task
rotation needed. pitch 58° gives depth cues for clip placement
while still revealing the flat desk for compass positioning.
{ yaw: 89.7, pitch: 57.9, distance: 0.698, fov: 50 }
reading_view returns to on Unpause (steps 9, 15).
Active only on reading steps, when the circuit is closed and compass needles align. The only preset that recentres the orbit target — onto the compass cluster rather than the coil, because the needles are the object of study.
Why this zoom
distance 0.42 m: each compass face fills a chunk of screen
so needle direction is legible with no further zoom. pitch 65°
(steeper than working) minimises perspective skew across four faces at
different depths — at shallow angle their needles would skew unevenly.
{ orbit_target: [0.019, 0.770, -0.104], yaw: 89.4, pitch: 65.4, distance: 0.424, fov: 50 }
paused_reading steps 9 and 15. Transient — on
Unpause the camera lerps back to setup_view over 300 ms.
instrument
Dominated by numeric readings — mass on a scale, temperature on a
thermometer — repeated across trials. Both readouts are small and sit in
different places, so working can't serve them alone. The
camera zooms into each instrument individually and returns to
working between.
The mixture-temperature phase is time-dependent (digits keep changing until
equilibrium). That's the one reading that uses phenomenon
with time paused; everything else uses instrument with Continue.
| Procedure moment | Role | Notes |
|---|---|---|
| Investigation load | intro | Wide shot of cups, scale, thermometer, baths. |
| Fill cups, place on scale | working | Medium pitch — see fill depth. |
| Read scale mass | instrument → Continue | Top-facing digital display — angled-down camera, pitch 50–70°, orbit target on scale. |
| Read starting temp (each cup) | instrument → Continue | Vertical thermometer face — near-horizontal camera, pitch 10–25°, orbit target on the scale's middle tick. One step per probe (R6). |
| Mix + insert probe | working | Back to the bench for the pour. |
| Watch temperature stabilise | phenomenon → Unpause | Same shallow-pitch framing as the starting-temp read — the thermometer is still vertical. Time paused until equilibrium. |
| Repeat trial | re-uses above | New condition, same camera sequence. |
| Compare trial values | compare | Side-by-side framing of the two recorded readouts. |
instrument / phenomenon case.
ui: button (description-only) covers this; the investigation
can be authored against it.
compare at the end
The whole activity happens on butcher paper — flat surface, perspective
distortion would undermine the learning. overhead dominates;
students drop to slight perspective only for pushing pins. Measurements and
shape comparisons need near-top-down so circles read as circles.
| Procedure moment | Role | Notes |
|---|---|---|
| Investigation load | intro | Wide shot of paper, pins, ruler, string loops. |
| Tape paper, gather tools | working | Slight perspective for tactile setup. |
| Place pin, trace circle | overhead | Near top-down so the circle reads true. |
| Measure radius with ruler | instrument → Continue | Tight on ruler tick. One step per measurement (R6). |
| Calculate eccentricity | (UI side) | No camera change; widget interaction. |
| Place two pins, trace ellipse | overhead | Same vantage; watch the ellipse form symmetrically. |
| Measure major axis, foci distance | instrument → Continue | One step per measurement. |
| Label features, add arrows | overhead | Student draws; camera fixed. |
| Compare circular vs elliptical | compare | Both drawings together, overhead, equal weight. |
phenomenon role needed — nothing
time-dependent. Pattern: setup → overhead for construction →
repeated instrument measurements → compare for
the pedagogical payoff.
When an investigation has multiple readings too far apart — or too small at any shared vantage — to be legible at once. Collapsing forces the student to zoom around (breaks flow) or squint (breaks trust). Split each reading into its own step.
The rulepaused_reading) when the
value would keep changing if time ran.
setup_view before the next step's preset,
giving a clean breathing moment between readings.
ui: paused_reading (Unpause) +
ui: button (Continue, description-only) cover both
variants.