Viewer control API¶
An agent -- a script, or later an MCP server that wraps these routes one tool per route or command --
can look at what the clash pipeline stored and drive the viewer a user has open: focus a
joint, select objects by name, move the camera, load a detail model, and read back what the viewer
shows so it can confirm. Everything is under /api and behind the same authentication as the rest
of the REST API (auth.current_user); scoped routes take the scope in the path as everywhere else
(user:me, project:<id>, shared).
Code: src/ada/comms/rest/viewer_control.py (vocabulary and session hub),
routes/viewer_control.py, clash_inspect.py (read-only clash views), and on the browser side
src/frontend/src/services/viewerControl/.
Off by default¶
Two switches: the server's, and each tab's.
The server: ADA_VIEWER_CONTROL (Settings.viewer_control), one of three modes. On a Helm
deployment, set it through the chart's extraEnv.
ADA_VIEWER_CONTROL |
Mode | What happens |
|---|---|---|
unset, false, off |
off (the default) |
Every /api/viewer/... route answers 404 ("viewer control is disabled on this server ..."), no socket is accepted, and the page shows no switch. |
true, opt-in |
opt-in |
On; each tab's switch starts off: a user turns it on for the tab they want driven. For a deployed server. |
on, auto |
auto |
On; each tab's switch starts on, so every tab takes part without being touched. For a local dev stack. |
Any other value stops the server from starting (a typo must not turn on a way to drive viewers). The
page learns the mode from /config.js (window.ADA_VIEWER_CONTROL = "opt-in" or "auto", absent when
off) and /api/config (viewerControl: "off" | "opt-in" | "auto"). The read-only clash routes below
do not depend on it.
The tab: Settings > External controls > "Let an agent drive this tab", offered only on a server
that allows it. Per tab (kept in the tab's sessionStorage): it starts as the server's mode says, and
once the user switches it, their choice holds for that tab until it is closed -- a tab switched off on
an auto server stays off. While it is off the tab asks for no ticket and opens no socket; switching
it off closes the socket. (The desktop viewer offers the same switch, off until turned on; there it
decides whether the tab answers a local client's commands.)
Whose viewer¶
A viewer tab opens a session. A session belongs to the user who opened it, and every lookup is
by (user, session id): another user's session id answers 404 exactly as an unknown one does, so no
user can see, drive or answer for another user's viewer.
Several tabs. Each open tab is one session. A command goes to the session named in
session_id, or -- when none is named -- to every live session of the caller; each tab answers
for itself. GET /api/viewer/sessions lists them, most recently heard from first, so an agent can
pick one.
Transport: the websocket envelope. Agents talk REST (below); the server relays to the tab over a
websocket carrying the same FlatBuffer Message the desktop viewer and its websocket server use
(src/flatbuffers/schemas), with three verbs (ada.comms.viewer_wire):
command_type |
Direction | request_id |
payload_json |
|---|---|---|---|
VIEWER_COMMAND (28) |
to the viewer | the command id | {"command": {...}} or {"commands": [...]} |
VIEWER_ANSWER (29) |
from the viewer | echoed | {ok, error, result, steps?, state} |
VIEWER_STATE (30) |
from the viewer | -- | ViewerState, when the tab opens and when what it shows changes |
- Hosted (REST) viewer. The tab asks
POST /api/viewer/ws-ticket(authenticated like every route; body{client?}) for a single-use ticket valid for 60 s -- a browser's websocket cannot send the bearer header -- and opensGET /api/viewer/ws?ticket=...(wss:on anhttps:page). The socket is one session of the ticket's user, for as long as it is open; it is opened again with a new ticket when it drops. A refused ticket, or a server with viewer control off, closes the handshake. - Desktop viewer. It already holds a websocket to its
adawebsocket server. A local client (a script) sendsVIEWER_COMMANDwithtarget_groupWEB and the viewer'starget_id(fromLIST_WEB_CLIENTS); the server relays it, and the viewer answersVIEWER_ANSWERto that client (target_groupLOCAL,target_idthe sender's instance id), or refuses while its external controls are off.VIEWER_STATEsent to the server is kept per viewer (ada.comms.msg_handling.viewer_control).
Deployment. The ingress in front of the API must pass websocket upgrades on /api/viewer/ws
and keep an idle connection open (uvicorn pings it every 20 s; an idle timeout of a minute or more
is enough).
One process. Sessions (open sockets) and commands' answers live in the API process's memory: the API runs as one replica. A scaled-out API would need the hub moved onto NATS, as the job queue is.
Driving the viewer¶
| Route | Body / query | Answer |
|---|---|---|
GET /api/viewer/sessions |
{sessions: [Session]} |
|
GET /api/viewer/sessions/{session_id} |
Session |
|
POST /api/viewer/commands |
{command \| commands, session_id?, wait_s?} |
CommandOutcome |
GET /api/viewer/commands/{command_id} |
wait_s? |
CommandOutcome |
GET /api/viewer/commands/schema |
that body as JSON schema (each action a branch in $defs) |
POST /api/viewer/commands takes one command, or commands: a batch of up to 20 that each tab
runs in order -- open_detail_model, then focus_joint, then camera, say -- stopping at the first
that fails. It validates them (400 with the reasons for anything outside the vocabulary, or for both
or neither of command / commands), sends them down the tabs' sockets, and waits up to wait_s seconds (default 10, at
most 60; 0 returns at once) for the tabs to answer. 404 when the caller has no such, or no,
viewer open.
A batch's answer per tab has steps, one per command in order:
{index, action, status: "done" | "error" | "skipped", error, result}. The tab's status is done
when every step was, else error, its error naming the command that failed
("command 2 of 3 (focus_joint) failed: ..."); the commands after it are skipped.
Session = {session_id, created_at, last_seen, idle_s, client: {title, path},
state: ViewerState, state_at}
CommandOutcome = {command_id, command | commands, issued_at,
results: [{session_id, status, error, result, state, answered_at, steps?}]}
status: "done" | "error" | "pending" (not answered yet) | "gone" (tab closed)
ViewerState = {scope, viewport: "three" | "native" | null,
loaded_models: [source name], active_model,
detail_models_loaded: [detail_id],
selection: {count, objects: [{model, id, node?}] (first 50), truncated,
bounds: {min, max} | null},
camera: {eye, target, up, fovDeg} | null,
clash: {run_key, joints, selected_joint}}
Every answer carries the state the command left; a tab also reports its state when the selection,
the loaded models, the scope or the open clash run change, so GET /api/viewer/sessions is current
without sending anything.
Commands¶
One object per command, discriminated by action. Unknown fields are refused.
action |
Fields | Does | result |
|---|---|---|---|
focus_joint |
joint_id, run_key?, scope?, frame (true), reveal_panel (true) |
What clicking a joint does: makes it the joints review's cursor, opens its group, selects its members in the loaded model(s), brings up Connections > Review, and fits the camera to them. run_key opens that convex-contact run first when it is not the one open. |
{joint_id, selected} |
select |
names: [str], file?, frame (true) |
Selects the objects of those names in a loaded model (file, a loaded source name; default the active one) and fits the camera to them. An error when none is found. |
{file, selected, bounds} |
clear_selection |
Clears the selection. | {selected: 0} |
|
camera |
exactly one of fit (selection | all), view (top, bottom, front, back, left, right, isometric), eye + target, box: {min, max} |
Moves the camera. eye/target keep the world's up axis up; box frames a world box keeping the viewing direction. |
{camera} |
open_detail_model |
detail_id, scope?, joint_id?, frame (true), with_source (false) |
Loads a kept detail model, as its Load button does (it must be done). With joint_id: selects that joint's connection in it and frames it; a joint the model does not hold (declined, failed) is focused in the clash run the model was made from instead, so its members are still on screen. with_source also loads the saved group the model's run was made on (load_saved_group), so the welds sit in their structure; the answer then has source_group (null when the run was not on a group). |
{detail_id, glb_key} or {detail_id, joint_id, shown_in: "detail_model", connections} or {..., shown_in: "source_model", run_key, selected} |
load_saved_group |
group_id or name, scope?, select (false), frame (false) |
Loads a saved group (the Scene panel's Groups) into the scene as its "Load into scene" does: each member's model, only the members showing. name is matched case-insensitively; an unknown or ambiguous name is an error naming the candidates. The load selects the members: select keeps that, frame fits the camera to them. |
{groupId, groupName, loaded, already, hidden, failed, selected, notFound, framed, bounds, text, tone} |
find_objects |
names: [str], file? |
Looks names up in the loaded models without changing anything (the selection is put back). | {found: [{name, file, objects, centre, bounds}], missing: [name]} |
get_state |
Nothing; the answer's state is the point. |
null |
Loading, then using what was loaded. open_detail_model and load_saved_group (and with_source) answer only once what they loaded can be found by name -- the model is in the scene, its Scene-tree rows are built and its objects indexed -- so the next command of a batch can select in it; one that does not get there within 60 s is the command's error. select, find_objects and focus_joint wait (up to 20 s) for a loaded model that is not yet selectable instead of finding nothing in it.
Coordinates are model units, in the viewer's world (up is the model's up axis).
Reading what was stored¶
Read-only, from the documents the clash pipeline already writes (a convex-contact run, a detail model's record and take-off). Nothing is recomputed.
| Route | Query / body | Answer |
|---|---|---|
GET /api/scopes/{scope}/clash-contacts/latest |
target? (a target object as JSON: {"kind": "file", "source_key"}, {"kind": "node", ...}, {"kind": "group", "group_id"}) |
{run: {run_id, key, target, label, created_at, contacts, members, ...}} -- the newest run of that target, else of the scope; 404 for none |
GET /api/scopes/{scope}/clash-contacts/joints |
key (a run key, or latest), target?, ids? (comma-separated), member? (a member name), limit? (100, at most 500) |
{run: {key, run_id, label, target, created_at, contacts}, joints: [Joint], missing: [id], truncated} |
GET /api/scopes/{scope}/saved-groups |
name? (contains, case-insensitive) |
{groups: [{id, name, members, sources, created_at, updated_at}]} -- the scope's saved groups in brief |
GET /api/scopes/{scope}/clash-detail/models |
the scope's detail models (existing route) | |
GET /api/scopes/{scope}/clash-detail/models/{detail_id} |
joint_ids? (comma-separated; default the joints it was asked to build) |
DetailView |
POST /api/scopes/{scope}/clash-contacts/detail |
{run_key, contact_ids, spec, options?, target?} -- run_key: "latest" details the newest run (of target when given) |
{job_id, detail_id, glb_key, derived_key, run_key}; poll GET /api/convert/{job_id} |
Joint = {id, members: [{index, id, name, role: "incoming" | "landing" | null, element?, part?}],
centre: [x, y, z], normal, distance, contact_area,
applicable: [{spec, capability, priority, tags?}] (highest priority first)}
DetailView = {model: <record: detail_id, status, spec, source, joint_ids, counts, glb_key, ...>,
takeoff, built_by, has_connection_records, run_found,
joints: [{joint_id,
status: "built" | "declined" | "failed" | "pending" | "not_requested" | "unknown",
connections: [{joint_id, connection, spec, member_roles, centre, plates,
welds: [{name, weld_type, throat, sided, length, members, metadata}]}],
not_built: {joint_id, kind, reason, spec?, declined: [{spec, reason}]} | null,
weld_failures: [{joint_id, connection, place, weld_type, reason}],
contact: Joint | null}]}
connections and their welds come from the take-off's connections records
(ada.clash.detail.connection_records); a detail model built before those were written has
has_connection_records: false and only the take-off's counts. A weld's metadata is whatever
scalar metadata its builder gave it (where a builder names the seam's place, side or corner, it is
there). contact is read from the run the model was detailed from while that run is stored
(run_found).
Example: a declined joint¶
A joint was declined, so it is in no detail model's GLB. The agent finds it, says which members it is, and shows them to the user in the source model:
GET /api/scopes/user:me/clash-detail/models
-> the newest model, detail_id "20260101T120000000Z-0123abcd"
GET /api/scopes/user:me/clash-detail/models/20260101T120000000Z-0123abcd?joint_ids=0123456789ab
-> joints[0].status "declined", not_built.reason "takes an incoming at 60 to 120 degrees; ...",
contact.members [column_1 (landing), brace_1 (incoming)], contact.centre [x, y, z]
POST /api/viewer/commands
{"command": {"action": "open_detail_model",
"detail_id": "20260101T120000000Z-0123abcd", "joint_id": "0123456789ab"}}
-> results[0].result.shown_in "source_model": the run was opened, the joint focused and framed
Or, without a detail model: GET .../clash-contacts/joints?key=latest&member=brace_1, then
{"action": "focus_joint", "joint_id": "...", "run_key": "<run.key>"}, or
{"action": "select", "names": ["column_1", "brace_1"]}.
And to re-run a detail for a subset of a run's joints:
POST /api/scopes/user:me/clash-contacts/detail
{"run_key": "latest", "contact_ids": ["0123456789ab"], "spec": "<spec name>"}
-> {job_id, detail_id, run_key, ...}
GET /api/convert/{job_id} (until done)
POST /api/viewer/commands {"command": {"action": "open_detail_model", "detail_id": "...",
"joint_id": "0123456789ab"}}
From the command line¶
ada viewer (ada_cli/viewer.py; the full reference is in the CLI page) wraps all of
the above: sessions, state, focus-joint, select, clear-selection, camera, open-detail,
load-group, find, run (a command or a batch from JSON, the same body as POST /api/viewer/commands),
schema, and the read-outs joints, groups and detail.
Where it goes. --via auto (the default) talks to a hosted viewer's REST API when a viewer URL
is configured -- --url, or ADAPY_API_BASE (ADAPY_BASE_URL, ADAPY_VIEWER_URL) with the token
in ADAPY_API_TOKEN, as every remote ada command reads them -- and otherwise to the desktop
viewer's websocket server (--ws-host / --ws-port, default localhost:8765): there it lists the
viewers (LIST_WEB_CLIENTS; a session is a viewer's instance id), sends VIEWER_COMMAND to them
and waits for each VIEWER_ANSWER by request id. --via remote / --via local force one. joints
and detail read stored documents and need the hosted server.
A short summary is printed by default, --json prints the raw answer. The exit code is 0 when every
targeted tab answered done, 1 when the server refused (no viewer open, viewer control disabled --
its message is printed) or any tab answered error, closed or did not answer within --wait, and 2
for a wrong invocation.
ada viewer sessions
ada viewer focus-joint 0123456789ab --run-key <run key>
ada viewer camera --eye 10,10,10 --target 0,0,0
ada viewer run batch.json --session <session id> --wait 30
ada viewer joints --run latest --member brace_1
As tools¶
Each read route and each command is meant to become one tool of an MCP server wrapping this API:
list_viewer_sessions, viewer_focus_joint, viewer_select, viewer_clear_selection,
viewer_camera, viewer_open_detail_model, viewer_find_objects, viewer_get_state (each a
POST /api/viewer/commands with that action; their input schemas are the branches of
GET /api/viewer/commands/schema), and latest_clash_run, clash_joints, detail_model,
detail_from_run for the routes above.