Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

142 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

COMPAS ThreeJS TypeScript viewer

Run the frontend in development

npm install
npm run dev

The 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.

Use the library build

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 8765

Then 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.

Plugins

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.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages