Diagram library

Diagrams show the main execution paths, component relationships, and configuration flow. Select a figure to open its guide and full-size view.

Coordinates need a frame and unitsRead the guide → Anatomy of a named-move taskRead the guide → Why two previews may not form one sequenceRead the guide → Choose one MoveTo target formRead the guide → Where each behavior belongsRead the guide → One robot, two model-loading pathsRead the guide → From task requests to robot motionRead the guide → Task execution flowRead the guide → How batching groups tasksRead the guide → Tool exchange changes hardware, then the modelRead the guide → Vision turns a detection into a motion targetRead the guide → Beamline configuration within each processRead the guide → Execution state messages and control boundariesRead the guide →

Figure index

Figure	What it explains	Read the explanation
Frames and units	Absolute coordinates, local displacement, and unit conversions	Concepts
Task anatomy	How a complete JSON task declares its tool, poses, and work	Task scripts
Preview comparison	Connected batched plans versus independent unbatched previews	Task scripts
MoveTo target choices	Three mutually exclusive request forms and their automatic planner chains	Task reference
Module ownership	Which source areas own interfaces, coordination, stages, and perception	Module map
Robot model assembly	Geometry, semantics, control configuration, and the separate GUI model	Robot models
System architecture	Task clients, the orchestrator, child actions, MoveIt, and devices	Architecture
Task execution	A motion goal’s model preparation, execution units, and final result	Execution
Batch selection	Which task types accumulate and which create a boundary	Batching and replay
Tool exchange	Physical exchange, gripper state, model restart, and vision resets	Tool and model lifecycle
Vision pipeline	Detection, goal computation, optional motion, and results	Perception
Configuration	Explicit beamline selection and shared configuration consumers	Configuration flow
Execution states	Pause, resume, cancellation, and fault boundaries	Execution controls

Reading the figures

Tasks, coordinates, and code

The GUI guide uses application screenshots to locate the real controls. The diagrams here explain relationships and behavior: task anatomy annotates a minimal named-move task, while the preview comparison assumes the robot stays at A during both planning requests.

The frames illustration separates a base-frame position from displacement along a rotated local frame. Its numbers teach units, not calibrated robot targets. The MoveTo decision figure shows the automatic planner chains; explicit planner selection has its own behavior in the task reference.

The module map groups ownership rather than asserting a strict import hierarchy. Model assembly keeps the launch-time robot description separate from the expanded URDF selected by the GUI.

Execution and tool changes

The system figure groups clients and task servers to show the main paths. Direct action clients can bypass the orchestrator. Vision transformations, model verification, and controller details have separate explanations.

The execution sequence shows a successful motion unit with fresh planning. Batch stages execute in the orchestrator process; a single task can instead use a child action server. Pipettor device calls, cache replay, and dry-run preview do not follow every arrow in this representative sequence.

Batching preserves input order. With batching enabled, consecutive moveto and end_effector tasks share an execution unit. Other types flush the accumulated batch and become single units. There is no separate action-specific breaker parameter. A pause task is handled locally by the orchestrator rather than sent to a child server.

The tool exchange sequence has two independent optional sections:

Real-hardware docking first sets the tool voltage to 0 V.
A changed attached gripper triggers a model restart and vision resets after successful physical motion.

The manager records the new gripper before attempting the restart. A failed restart returns failure without undoing the physical exchange. Vision reset failures are logged as warnings.

Vision and configuration

The vision figure follows the unified VisionTaskStages.run path. The optional scan move happens before settling, detection, and goal computation. A goal computer can produce a Cartesian target, a joint target, a detect-only result, or a cache-only completion. Detection and computation errors stop this path. The separate vision_scan action and individual detector algorithms are outside this overview.

Configuration is parsed once per process. The top-level loader requires an explicit existing YAML file with a mapping at its root.

For relative resource paths, the resolver searches up to ten ancestors for a directory with a src/ child. If none is found, it uses the configuration directory. Some helpers provide fallback values for isolated use; the top-level loader still requires explicit configuration.

Execution states

Execution state messages describe lifecycle progress. Read the ROS action result to determine whether a goal succeeded.

IDLE appears initially and during non-faulted cleanup, including after a failed goal. The previous IDLE message can also remain visible while an accepted goal’s model starts.

Pause and cancellation operate at execution-unit boundaries. The figure shows common paths; its asterisk notes describe cancel and fault rules across active states. The current orchestrator has no reset service to clear a latched fault.

Editing and checking

Each figure is an editable HTML file under docs/diagrams/, with inline SVG, system fonts, and no network dependency. Its text remains selectable and searchable.

Keep the accessible title, description, and diagram-specific IDs. The site build embeds the SVG and links to the full-size HTML; the browser needs no diagram renderer.

The design follows Cathryn Lavery’s Diagram Design, pinned to 8d8b2993ee2256ee7dfc0eeb3b5713aba3b60792. The project-specific blue palette and system-font profile are stored in scripts/diagram-style-guide.md. The isolated upstream checkout is disposable; the authored figures and profile are the durable source.

From the root of the documentation source repository:

# First use: fetch the pinned authoring tools into .tools/.
python3 scripts/check_diagrams.py --bootstrap

# Subsequent checks work offline.
python3 scripts/check_diagrams.py

Every figure must pass the upstream accessibility/single-file check, skin lint, and geometry check. Also check label readability, connector crossings, and mobile layout in the browser. Keep full-size diagrams available.