Skip to content

CAD Viewer and Annotation Architecture

Source file: Step CAD_Viewer_Architecture_and_Tech_Stack.md Last synthesized: March 2026 Purpose: Define how RapidDraft should render 3D CAD and drawings, attach AI findings, and phase from demo stack to production-grade review tooling.

Why This Page Exists

RapidDraft is not building a passive file viewer. The product promise is a guided engineering review session where AI findings, human decisions, and geometry context all stay connected. That means the key architectural question is not just "what viewer do we use?" but "what state and annotation model lets the viewer, chat, and review logic operate on the same object?"

The source note adds an important framing: a professional review session needs a persistent inspection surface, not a one-shot model embedded inside a chat bubble. The viewer is a durable workspace, and the chat panel is a command and explanation layer attached to it.

Core Architecture Decision

RapidDraft should use a dedicated viewer plus chat panel rather than embedding a disposable 3D viewport inside the chat stream.

Why

  • Review sessions are stateful and often last long enough that camera position, selected faces, highlighted findings, and comment threads all need to persist.
  • One persistent viewer context is cheaper and operationally cleaner than spinning up multiple WebGL contexts per message.
  • The chat panel becomes more useful when it can read what the engineer is looking at and write new highlights or actions back into the same session state.

Interaction Model

Viewer -> shared state -> chat context
Chat -> shared state -> viewer highlights / selections / annotations

For the current stage, a lightweight shared store such as Zustand is enough. The important decision is the bidirectional contract, not the library brand.

Current RapidDraft Near-Term Architecture

The active RapidDraft implementation now uses a progressive browser viewer rather than a canonical or nothing load contract.

The current sequence is:

  1. preview mesh first
  2. backend canonical manifest second
  3. lazy per-component semantic detail third

This is the important current boundary:

  • preview geometry makes the workspace visible and usable quickly
  • backend canonical data remains the only trusted source for face ids, edge ids, feature refs, and review-grade selection behavior
  • heavy assemblies are allowed to stay partially in preview mode while canonical detail keeps warming

This is the near-term production architecture for RapidDraft. A browser-side OCCT/WebAssembly runtime is still a future branch, not the current implementation.

Representation Strategy: Mesh for Display, Semantics for Review

RapidDraft can display meshes early, but the full product requires B-Rep-aware selection whenever the system needs to reason about exact faces, edges, and drawing-linked manufacturing issues.

What matters

  • Mesh-only formats such as GLB are fine for visual display, but they discard the semantic face structure needed for engineering-grade selection and downstream edits.
  • B-Rep-aware stacks keep mathematical surfaces and topology available after tessellation, which is what turns a click into a meaningful engineering reference instead of a triangle index.

Practical implication

For the current implementation, RapidDraft now explicitly splits those concerns:

  • preview mesh for immediate display
  • canonical backend scene data for exact review semantics
  • progressive swap from preview components to canonical components as detail becomes ready

That lets the viewer stay visible on heavy models without relaxing the semantic standard for exact face and feature interaction.

This fits the broader product direction already present in the wiki: deterministic review and evidence matter more than flashy rendering.

Drawings Need an Annotation Architecture More Than a Fancy Viewer

For drawing review, the annotation layer is the real product surface.

  • PDF first: Good enough for early customer workflows because engineers will send PDFs.
  • DXF to SVG later: Better long-term path when entity identity matters and RapidDraft needs cleaner coordinate handling.
  • SVG-native outputs: Best case when RapidDraft generates the drawing or controls the export path.

The source note is directionally right here: viewer choice matters less than whether AI findings can be placed precisely, remain stable during zoom and pan, and stay tied to auditable evidence.

3D Annotation Model

3D comments should be stored as world-space anchors and rendered as screen-space UI.

Rules

  • Store the anchor in model/world coordinates.
  • Reproject to screen coordinates every frame as the camera moves.
  • Render comment bubbles as HTML so threading, editing, and accessibility stay simple.
  • Keep leader lines or anchor markers in a lightweight overlay layer.

Minimal annotation shape

{
  "id": "ann_001",
  "anchor": { "x": 24.5, "y": 10.0, "z": 3.0 },
  "faceId": "face_17",
  "severity": "error",
  "status": "open",
  "source": "dfm_auto",
  "text": "Draft angle below review threshold"
}

This is the right mental model for RapidDraft because it keeps findings stable even as the camera changes.

Phase 3D viewer Drawing viewer Annotation approach Why
Immediate demo Self-hosted lightweight STEP viewer PDF.js Canvas or SVG overlay on PDF Fastest path to a believable review demo with minimal infrastructure work
Post-demo validation occt-import-js plus Three.js PDF.js, then DXF to SVG where available Shared app state plus HTML/SVG overlays Unlocks richer face selection without committing to enterprise licensing too early
Production HOOPS Communicator-class viewer HOOPS-linked or equivalent semantic 2D path Native markup plus persistent review state Best fit for multi-format enterprise review, semantic selection, and scalable professional UX

RapidDraft-Specific Recommendation

The source note points to a staged decision that fits RapidDraft well:

  1. Start with the cheapest stack that proves the review loop.
  2. Upgrade the viewer only when the product truly needs semantic geometry selection.
  3. Treat annotations, evidence, and review memory as the durable moat, not the rendering layer by itself.

That means the short-term focus should stay on:

  • persistent viewer plus chat coupling
  • stable annotation coordinates for PDFs and 3D findings
  • clean handoff between AI findings and deterministic review state

The long-term production path remains consistent with the existing TextCAD decisions around HOOPS-family enterprise infrastructure.

Current Viewer Feature Matrix (May 2026)

This matrix merges two inputs:

  • the earlier CoLab-style feature comparison work
  • the current integration-repo implementation audit

The important correction is that the active RapidDraft preview path is now further along than some older source notes imply. The browser viewer still stays React/Three.js-first, but exact-CAD preview rendering and the legacy projection endpoints are already routed through the OCCT path in the active implementation. That means the near-term roadmap is less about replacing the viewer and more about exposing the right review behaviors on top of the existing viewer plus canonical geometry stack.

Scoring:

  • ROI: 1 low leverage, 5 very high reviewer/product value
  • Coding complexity: 1 small implementation slice, 5 large or architecture-sensitive slice
Feature Status ROI score Complexity in coding score Notes
Saved view state / viewerState Partial 5 2 Camera state already exists on pins. Extend it to selected component, component visibility, section state, explode amount, and active finding so comments and links can restore the full review context.
Camera presets + Ortho/Persp Not built 4 2 A high-value reviewer feature that does not require a native OCC viewer. Pairs naturally with saved view state.
Measure tool v1 Not built 5 3 Start with client-side distance, angle, edge length, and simple dimensions. This can be approximate on mesh paths and good enough to validate demand.
Measure tool v2 exact / topology-aware Later extension 4 4 Use canonical face and edge selection plus OCC-derived values when exactness matters. Best added after a lighter first version proves useful.
Live section / clipping tool v1 Not built 5 3 Frontend clipping planes are a strong CoLab-style reviewer feature and are cheaper than a full topology-aware section workflow.
Exact section edges + section-aware comment anchors Later 3 5 Static OCC section snapshots already exist, but live topology-aware section review needs a cleaner anchor contract and more backend support.
Explode assembly view Not built 4 3 Mostly frontend transform state. The key rule is that display transforms must stay separate from real CAD coordinates so pins and comments remain trustworthy.
Manual ghost / x-ray mode Partially scaffolded 4 2 Ghosting and opacity control already exist during DFM focus. Exposing that as a general viewer mode is a relatively small, high-value improvement.
OCC orthographic + mid-section snapshot panel cleanup Live, but stale 4 2 OCC hidden-line and mid-section snapshot generation already exist. The current gap is mostly UI naming, grouping, and contract cleanup rather than new rendering work.
Component-scoped OCC snapshots Backend-ready, UI missing 3 2 The OCC view generator already supports component targeting. Exposing it would improve assembly inspection and review exports.
Revision compare, side-by-side synced Not built 4 4 Best first revision-compare slice. Safer and more achievable than true geometric diff while revision semantics are still maturing.
Geometry diff / overlay compare Later 3 5 Useful, but expensive and sensitive to topology drift across revisions. Better treated as a later architecture phase.
Rich markup layer Not built 3 3 Start as screen-space arrows, text, and simple shapes tied to saved viewer state. Do not overreach into semantic PMI or full GD&T authoring too early.
Bounded DFM edit previews Partial backend 3 4 Valuable, but this belongs more to the bounded remediation track than to the core viewer-options track. It depends on trustworthy feature localization and candidate-session flow.

Recommended order for the next viewer-value tranche:

  1. Saved view state / viewerState
  2. Camera presets plus Ortho/Persp
  3. Measure tool v1
  4. Live section / clipping v1
  5. Manual ghost / x-ray mode and OCC snapshot panel cleanup
  6. Explode assembly view
  7. Side-by-side revision compare

Open Questions

  • Is PDF-first sufficient for the first customer-facing drawing-review workflow, or does RapidDraft need DXF-level entity references earlier than expected?
  • At what point does the commercial benefit of HOOPS Communicator outweigh the cost and integration complexity of a lighter open-source stack?
  • Should geometry edits stay server-side through FreeCAD/OpenCASCADE for the foreseeable future, or does RapidDraft eventually need a tighter native-CAD edit loop for selected operations?

Sources