Hardware Visualisation

Hardware Visualisation (Digital Twin)

The Hardware Visualisation screen (/hardware-twin) renders the saved automation topology read-only in 3D and overlays a live picture of equipment activity and handling-unit movement derived from the device-task feed — giving a real-time digital twin of the physical system without any extra backend instrumentation.

Backed by GET /api/flow/device-tasks (flow-orchestrator, port 8085), polled every 3 s. RBAC: ADMIN, SUPERVISOR, or OPERATOR role required.

Equipment state

The base scene is rendered using the same meshes as the Automation Topology Editor (two-tone conveyor ribbons, racked ASRS, sorter/workstation boxes, SCAN/QRY/DIV function-point markers and labels). Runtime state is shown as a clean overlay on top of the editor scene:

State	Overlay	Trigger
Idle	None — base mesh only	No active task seen in the current window
Running	Floating amber sphere above the equipment, pulsing in size and brightness	At least one active (REQUESTED/DISPATCHED) task on this equipment
Faulted	Floating red sphere above the equipment (steady)	Any FAILED task on this equipment in the current window
Selected	Lime floor ring below the equipment	User clicked the placement

Tote (handling-unit) markers

Active handling units are drawn as 3D tote models (600 × 400 × 320 mm open-top container — base plate, four slightly tapered walls, and a bright state-coloured rim) whose positions replay the observed scan trail — no motion is invented.

In-transit positioning (ADR-0008 3d-3): when a CONVEY task is running, the twin fetches the hu_transport_trace rows for that HU each poll tick. The most recent SCANNED row gives: the scanned node's world position (fromXZ) and the answered next node (toXZ). The marker is interpolated from fromXZ toward toXZ at the real conveyor speed (0.5 m/s) using elapsed wall-clock time from the scan timestamp — giving continuous per-frame motion between polls without inventing a path. If no scan trace is available, the tote falls back to its strict equipment anchor (explicit equipmentId on the task only; no family guess). A tote with neither an observed scan nor a direct equipment anchor is hidden rather than guessed.

Queued totes: the queue state is sourced from the real induction queue per GTP workstation (flow's getStationQueue API), so a tote that has finished all work simply disappears rather than lingering forever as "queued" from a stale completed CONVEY task. The twin falls back to task-inference when queue data is unavailable.

Equipment-activity anchoring still uses a family-level fallback (ASRS/AUTOSTORE/AMR → storage placement; CONVEYOR → longest-path conveyor) but only for the amber/red activity sphere overlay, never for tote-marker positions.

Totes at non-conveyor equipment (workstations, ASRS placements) sit on the top surface of that equipment's bounding box so they are visibly above the solid mesh.

Tote state	Meaning
In-transit	Tote has an active CONVEY task; position follows the scanned node trail
Recirculating	Last sorter decision was RECIRCULATED or HELD; loops back to induct
Queued	Tote is in the real induction queue at a GTP workstation
Done	Tasks completed; marker lingers briefly then is removed

Stats bar

A bar across the top of the screen shows live aggregate counters derived from the current device-task window:

Counter	Description
In-transit	Totes with at least one active transport task
Queued	Totes queued at a workstation
Throughput/min	Completed tasks in the last 60 s
Recirculations	Sorter RECIRCULATED decisions in the current window
Faults	Equipment with at least one FAILED task

Level filter

When the topology spans multiple floor levels, a level selector in the header restricts the scene to a single level. All unrelated equipment and tote markers are hidden; the stats bar counts only the visible level.

Labels toggle

A Labels checkbox in the control bar (default off) shows or hides the text labels that float above each equipment placement and function-point marker:

Setting	Effect
Off (default)	All decorative overlays are hidden: equipment-code text, SCAN/QRY/DIV function-point cones/diamonds, and conveyor junction rings. Only the base 3D meshes, tote markers, and activity/state overlays remain. Maximum signal-to-noise at a glance.
On	Equipment codes appear above each placement; SCAN/QRY/DIV labels and cone/diamond glyphs appear above each function-point; conveyor junction rings are shown. Matches the Automation Topology Editor view.

The toggle does not affect the 3D geometry, tote markers, or activity/state overlay indicators.

Interactions

Action	Result
Click equipment	Opens a detail panel with the equipment's recent device tasks
Click tote marker	Opens the HU trace panel for that handling unit (same trace as Transport Overview#per-hu-transport-trace)
Click background / grid	Clears both selections
Left-drag	Orbit the camera
Right-drag	Pan
Scroll / middle-drag	Zoom

Implementation notes

• Data sources per poll tick:

  Source	Endpoint	Purpose
  Device tasks	GET /api/flow/device-tasks	Equipment activity + tote state
  HU transport trace	GET /api/flow/hu-trace?huId= (fan-out, ≤ 12 active HUs)	SCANNED rows → in-transit tote positions
  Station queue	GET /api/flow/gtp/queue?stationId= (per workstation)	Real queued-tote truth source
  Conveyor topology	GET /api/flow/conveyor/topology?warehouseId=	Routing-node world positions; loaded once per warehouse alongside the topology

• Coordinate system: all twin geometry is floor-relative — matching the Automation Topology Editor, which renders each level on the floor plane regardless of the level's elevationM. The PlacementGeom.baseY field stores only posYM (the placement's own vertical offset); level elevation is intentionally excluded. Adding elevation would float overlays and tote markers metres above the equipment meshes on multi-level warehouses (bug HU-004).

• The 3D scene (HardwareTwin3D) is code-split into its own Vite/three.js chunk and loaded lazily; it does not affect the initial bundle size of other screens.

• The twin reuses the editor's presentational components (EquipmentMesh, FunctionPointMarker) from AutomationTopology3D in read-only mode (no drag gizmos, no waypoint handles, all edit handlers are no-ops). Equipment classification (conveyor vs rack vs sorter) is driven by a one-time load of the master-data equipment library (listEquipment) per warehouse; if that load fails the scene still renders with coarser classification.

• Conveyor node positions (loadConveyorNodePositions) are loaded once alongside the topology; if the endpoint is absent or returns no projected nodes, scan-replay degrades gracefully — totes fall back to strict equipment anchors rather than crashing.

Related

Transport Overview · Equipment Integration · Goods-to-Person Stations · Services