Skip to main content

CAD Bridge API

The CAD Bridge is an API that lets connector tools send a CAD assembly to VIZid and update it as the design changes. A connector can send added, removed and modified parts and changes to their positions.

The CAD Bridge is an API, not a supplied connector. VIZid does not include a ready-made connector for any specific CAD application. Connectors are built by customers, integrators, or with developer and AI assistance, using the CAD Bridge API. The CAD Bridge API documentation — protocol, message schemas, a conformance test tool and build plans for common CAD systems — is provided to connector developers.

Listener​

The listener is on by default. To toggle it:

  1. Open the File menu.
  2. Click CAD Bridge — the menu item is checked when the listener is on, unchecked when it is off.

When you switch the listener on, the status bar reports CAD Bridge: listening on 127.0.0.1:8765; switching it off reports CAD Bridge: off. The menu tick reflects the requested setting, so check that port 8765 is free if a connector cannot connect. VIZid binds to IPv4 address 127.0.0.1, not to other network interfaces. Only one connector can be connected at a time; a new connection evicts the previous one. Any process on the same computer can connect to this local listener.

What a Connector Sends​

A connector sends two types of update:

Full scene update — sends the connector's complete current visible parts. VIZid imports new part IDs, replaces geometry for known IDs, and deactivates that connector's parts omitted from the snapshot. Their material work remains in the document if they return. Other connectors' parts and parts authored in VIZid stay as they were. A connector can use a full scene update for the first transfer or a complete resend. Updates go one way, from the connector to VIZid; edits made in VIZid are not sent back to CAD.

Diff update — adds, removes and modifies specific parts. Use it for incremental changes without resending the full assembly.

What each part update includes​

  • Name — the display name from the CAD assembly hierarchy
  • Geometry — base64-encoded STEP data. Send one part per ID when possible; a multi-body file becomes several meshes within that part's group. AP242 import remains to be verified in the app.
  • Position — a 4×4 row-major transform matrix; translations are in millimetres. For nested hierarchy entries, use coordinates relative to the parent.
  • Material name — accepted in protocol v1 but ignored by the current importer. Apply VIZid materials in the Material editor.
  • Mesh quality — an optional 0–1 value on the message, applied to each part in that message that carries geometry. If omitted, VIZid uses its import default.

What is not overwritten​

VIZid keeps each connector part's material assignments with its import root. On a geometry update, it matches mesh slots by relative path, then by a unique mesh name. When both versions contain just one mesh, that assignment follows the sole slot even if its name and path changed. A temporarily missing slot keeps its assignment for a later return. Per-face assignments are restored only when the mesh topology matches; changed topology leaves the old face assignment dormant so it cannot paint the wrong faces. Renaming an existing group in VIZid keeps its connector part ID. Renaming a group in CAD does not rename parts VIZid already has; new part IDs can arrive under the new CAD name.

What to expect​

  • When a connector sends a part ID in diff_update.removed, VIZid deactivates that part. It remains in the document but is not rendered. A later geometry send replaces and reactivates it; a move-only update can reactivate its preserved geometry.
  • Updates address Bridge import roots by connector type and part ID. Parts authored outside those import roots are unaffected by ID removal. A part moved inside a Bridge import root follows that root when it is replaced or deactivated. Connector types have separate ID namespaces in the document. Keep a connector's client_type stable across sessions so its saved parts and baseline remain addressable. Older documents may contain Bridge roots without a connector type; full omissions leave them alone. Sending a matching ID explicitly adopts a single unowned legacy root when there is no competing import with that ID.
  • On the first receive into a document with no parts, VIZid frames the assembly and seats it on the ground. CAD positions govern subsequent part placement; VIZid keeps the floor seating it applied on first receive. Camera framing and seating still need end-to-end verification.
  • A part sent with an empty or missing step_data and a 16-value transform moves without re-meshing. A move for an unknown part ID is skipped.
  • Sending the same geometry at a different quality value uses a different mesh conversion. Change mesh_hash whenever the geometry changes; reusing a hash for changed geometry can reuse the old cached mesh for that session.

CAD Bridge Parts in the Outliner​

Parts received through the CAD Bridge appear in the Outliner under an assembly node, like imported parts. You can:

  • Rename them; the connector's stable part ID is unchanged
  • Hide them with the Visibility toggle
  • Lock them to prevent accidental moves
  • Select them and edit their position in the Object panel

Alignment​

Right-click a CAD Bridge part or assembly in the Outliner and open the Align submenu. All standard placement options are there; the CAD-specific ones are:

OptionWhat it does
Restore CAD Parent and PlacementReturns the part to its original assembly and restores the latest CAD attachment. Keeps authored animation.
Restore Initial Import PlacementRestores the first imported placement, keeping the current parent and any authored animation.
Restore Initial Parent and PlacementReturns the part to the first imported assembly and placement, keeping authored animation.
Reset to CAD PositionReturns the part to the position the connector last reported, relative to its parent assembly. Keeps any authored animation.

Standard placement options — To Floor, To Home, To Object Below, To Ground (orient) — are also in the Align submenu and work the same as for imported geometry.

The CAD-follow placement tools also include:

OptionWhat it does
Follow Original CAD AssemblyRestores the part's dependency on its original imported assembly so subsequent connector updates can drive its position. Existing animation keys remain editable.

Connection Status​

When File › CAD Bridge is checked, the listener has been requested. A connector that identifies itself briefly appears in the status bar as CAD Bridge: <client type> connected. If no connection succeeds, check the port and use 127.0.0.1 rather than a localhost name that might resolve to IPv6.

Building a Connector​

The CAD Bridge uses a JSON protocol over a local TCP connection on port 8765. The connector sends three message types; VIZid sends one baseline message back:

DirectionMessagePurpose
Connector → VIZidclient_identifyThe connector names itself with a client_type, such as the CAD system it bridges. VIZid displays the client type in the status bar.
Connector → VIZidfull_scene_updateAdds or replaces parts by stable part ID and deactivates omitted parts owned by that connector, retaining material assignments for their return.
Connector → VIZiddiff_updateSends added and modified parts, plus IDs to deactivate in removed.
VIZid → ConnectorBaseline (full_scene_update)Sent after client_identify, and again when you open a document or start a new one. Contains the current active Bridge imports known to VIZid.

Full protocol documentation — including message schemas, a conformance test tool and build plans for common CAD systems — is available to connector developers in the CAD Bridge API documentation package.