Physics adds causal channels to the familiar visual grammar. Color and position say what a datum looks like; mass, force, collision, and constraints change what itdoes. Treating those as the same kind of encoding produces attractive but unreadable models, so one rule runs through this whole page:every causal channel needs a visible or evidentiary twin -- never make an important value discoverable only by watching a collision.
Test the Channel Families
Select a family to change the compiled initial world. The readout names what is data, what changes execution, and what has to survive in a static projection.
Channel families
Eight families run from ordinary Bertin marks to causal simulation inputs. Two supportreading (they change what the eye compares); the rest arecausal (they change execution). Every family names what survives when the chart is static:
- Appearance (reading) --
color, shape, size, opacity. What can the eye compare before anything moves? Static projection: Legend plus visible marks. - Placement (reading) --
x, y, lane, target. Where does a body begin or belong? Static projection: Axes, lanes, and target anchors. - Time (causal) --
spawnAt, pacing, duration. When does a datum enter the process? Static projection: Arrival table and timestamps. - Kinematics (causal) --
velocityX, velocityY, impulse. How is motion initially directed? Static projection: Vectors and event log. - Dynamics (causal) --
mass, force, friction, restitution. How does a body respond to causes? Static projection: Visible twin encoding plus evidence. - Constraints (causal) --
collision, barrier, membrane, tether, region. What relationships and boundaries govern motion? Static projection: Authored geometry and relationship list. - Process (causal) --
stage, work, capacity, group, transition. What domain state changes as the body moves? Static projection: Stage ledger and transition table. - Evidence (reading) --
occupancy, throughput, wait, settled outcome. What did the simulation actually observe? Static projection: Metrics, observations, settled rows.
Encode, execute, observe
A physics chart is authored in three layers, each with a clear owner:
- Encode data (
compilePhysicsEncoding) -- resolve accessors into stable IDs, initial positions, collision shapes, appearance, process metadata, and accessible language. - Execute a world (
StreamPhysicsFrame) -- add curated constraints, colliders, regions, and controllers. Solver coefficients are implementation presets unless the domain explicitly defines them. - Observe evidence (
onObservation / controller snapshots) -- read occupancy, transitions, wait, throughput, and settled outcome. Observations are results, not decoration.
Compile accessors before simulation
createPhysicsEncodingLayout gives PhysicsCustomChart the same accessor-first vocabulary as other Semiotic HOCs. Its extend callback owns domain topology while the compiler owns the repeatable data-to-body contract.
JSX
import { PhysicsCustomChart, createPhysicsEncodingLayout, } from "semiotic/physics" const layout = createPhysicsEncodingLayout({ encoding: { id: "id", appearance: { color: "category", size: "magnitude", }, placement: { x: "score", y: "laneIndex", lane: "lane", }, time: { spawnAt: "arrivedAt" }, process: { stage: "stage", work: "remaining" }, evidence: { value: "magnitude", status: "status" }, accessible: { label: "name", description: "summary" }, }, extend: (context, compiled) => ({ constraints: constraintsFromDomainTopology(compiled.rows), regionEffects: regionsFromProcessStages(context), }), }) <PhysicsCustomChart data={rows} xExtent={[0, 100]} yExtent={[0, 4]} layout={layout} />
Give dynamics a visible twin
Mass may legitimately change collision response, but it should not silently stand in for priority, population, cost, or confidence. When a causal channel carries meaning, pair it with a readable appearance channel and an evidence field:
JS
// Bad: quantity is encoded only as mass. dynamics: { mass: "priority" } // Better: the causal channel has readable twins. { appearance: { size: (d) => priorityScale(d.priority), }, dynamics: { mass: "priority", }, evidence: { priority: "priority", }, accessible: { description: (d) => `Priority ${d.priority}; mass changes collision response`, }, }
One owner for authored geometry
A barrier, membrane, or habitat region should compile from one definition into collider or sensor geometry, painted appearance, semantic bounds, and observation metadata. If those four shapes are authored separately, the visualization can look correct while interaction and accessibility disagree.
- Stakeholder Journey -- stage-level simulation, accessible outcomes, and settled process evidence
- Motion Encodings -- the shared channels connecting realtime transitions to causal physics
- Realtime Encoding -- how arrival, window, age, and freshness extend conventional streaming marks
- When Physics -- choosing physics only when visible process behavior earns the complexity