npm install
npm run devThe viewer connects to ws://127.0.0.1:9001/ws?workspace=main by default. The host, port, and workspace can be changed with the ws_host, ws_port, and workspace URL parameters.
See the compatibility policy and COMPAS support matrix for the public 1.0 contract and current implementation status.
The public API creates an explicit viewer instance in a container. Importing the
package does not mount anything or access the DOM; browser work starts when
createViewer is called.
npm install
npm run build
python3 -m http.server 8765Then open:
http://localhost:8765/examples/embedded_box.html
See examples/embedded_box.html for the complete local-build example. Its
essential code is:
import { createViewer } from "@compas-dev/compas-threejs-ts";
import "@compas-dev/compas-threejs-ts/style.css";
import { Box, pbDumpBytes } from "@gramaziokohler/compas-pb-ts";
const viewer = createViewer(document.querySelector<HTMLElement>("#viewer")!, {
mode: "embedded",
defaultLighting: true,
showToolbar: false,
send(message) {
hostTransport.postMessage(message);
},
onError(error) {
console.error(error.code, error.message, error.details);
},
});
const box = new Box({
data: {
// frame and dimensions...
},
});
viewer.dispatch(pbDumpBytes(box));
// Later:
viewer.reset();
viewer.resize();
viewer.dispose();embedded is the default mode and does not open or retry a WebSocket. The optional
send callback receives picker and UI messages. defaultLighting adds the
standalone lighting rig, and showToolbar controls the built-in toolbar.
onError receives a CompasViewerError with a stable code and optional
details. Synchronous dispatch and lifecycle errors are thrown when no callback
is provided. Asynchronous connection and asset-loading errors are reported to
the callback, or to the console when no callback is configured. The current
codes are decode_error, invalid_message, unsupported_message,
connection_error, lifecycle_error, plugin_error, and render_error.
A failing plugin never stops the viewer: one with a taken name or a duplicate id, or
whose setup throws, is left out; a component or a channel handler that throws stays
contained. Each is reported as a plugin_error (details.plugin names it) and shown
to the user as an error notice.
pbDumpBytes is the TypeScript equivalent of Python's compas_pb.pb_dump_bts: it adds the complete COMPAS-Protobuf message envelope around any supported wrapper object.
The viewer decodes that envelope with the 2.x pbLoadBytes API. Protobuf lists
and dictionaries are materialized recursively as plain JavaScript arrays and
objects before dispatch. The npm package major and wire-format version are
independent: compas-pb-ts 2.x still targets the compas_pb 1.x wire format.
The dispatcher also walks protobuf lists and dictionaries recursively, rendering
the supported geometry objects they contain. In websocket mode the standalone
app reads ws_host, ws_port, and workspace from the URL, preserving the
Python package integration.
For a broader visual smoke test, open
examples/embedded_kitchen_sink.html. It uses the same public embedded API to
display every geometry and helper type included in the 1.0 support matrix in a
labelled 4×4 grid.
Maintainers can find the dependency policy in
docs/dependencies.md and the automated release flow in
docs/releasing.md.
The viewer has no toolbar of its own: plugins add it, each in a section of its own.
import { createViewer, definePlugin } from "@compas-dev/compas-threejs-ts";
import { FrontButton, SaveViewButton, TopButton } from "./buttons";
const camera = definePlugin({
name: "camera",
title: "Camera", // optional, shown above the section
// Groups of Vue components, by id, in toolbar order; each group is one segment.
groups: {
presets: { top: TopButton, front: FrontButton },
saved: { save_view: SaveViewButton },
},
setup(viewer) {}, // optional; may return a cleanup
});
createViewer(container, { plugins: [camera] });A plugin owns its tools' behaviour; the viewer only gives primitives. Inside a button,
useViewer() gives the selection, objects (hide, pickable, commit a transform), the
camera (get, set, view presets), the theme and image capture; viewer.three goes closer
to the scene (camera, canvas, objects, overlays, pointer rays, pausing navigation,
vetoing picks, taking over input with beginInteraction) for interactive tools like a
gizmo or drawing tools. useChannel(name) sends to and receives from the
plugin's Python half, and useShortcuts({ key: handler }) binds keys.
A plugin can also add objectActions ({ hide: HideAction }): components shown in the
FUNCTIONS panel for the selected object.
And panels, docked beside or along the view: on the right under the object panels
(the default), on the left under the toolbar, or with side: "top" or "bottom" in a
row along that edge, between the sidebars. A panel with a title gets a frame whose
title bar folds it (remembered in the browser); without one, the component draws the
whole panel.
definePlugin({
name: "timber",
panels: {
tree: { component: TreePanel, title: "Elements", side: "left" },
table: TablePanel,
timeline: { component: TimelinePanel, side: "bottom" },
},
});Plugins can use each other: a plugin's api is what others get from
viewer.plugin(name) (e.g. a drawing plugin's tool controller). viewer.notify(message, { kind }) shows the user a message for a moment; Python's Plugin.notify does the same.
A page shows one workspace (viewer.workspace, from ?workspace=). A button can open
another in a new tab with window.open(viewer.workspaceUrl(id)): open it from the click,
and let Python fill the workspace meanwhile - a tab opened after waiting for Python's
answer is blocked as a pop-up.
The Python half can hide or disable a group, a single button or a panel by its id. The
viewer applies it to any of them: a disabled one is greyed out and inert, and its
useShortcuts stand down.
ToolbarButton, Button, Popover,
Tooltip, ... make buttons look like the viewer's own.
The page the Python App serves loads its workspace's plugins at runtime from
plugins.json?workspace=<id>. It
maps vue, three and @compas-dev/compas-threejs-ts with an import map, so a plugin is
built with those three left external and shares the page's copies. See
compas_threejs_essentials, compas_threejs_views and compas_threejs_draw.