vikcraft-3d-annotator

A professional 3D model annotation library built on Three.js — for engineering, CAD review, and inspection workflows.

Features

• 7 annotation tools: Pin, Arrow, Callout, Measure, Text Label, Stamp, Cloud Region
• CSS2D labels that billboard-follow 3D objects at all camera angles
• 7 stamp types: APPROVED, REJECTED, FOR REVIEW, DRAFT, VOID, REVISED
• 8 categories: Note, Safety, Design, Dimension, Quality, Question, Action, Reference
• Measurement tool with live preview line and metric/imperial display
• 50-step undo / redo stack (Ctrl+Z / Ctrl+Y)
• Model Explorer — browse scene hierarchy, select/highlight meshes
• Inline comment popover (keyboard shortcut + mouse position aware)
• Post-processing outline selection (OutlinePass)
• View modes: Default, Wireframe, X-Ray
• Camera presets: Front, Top, Right, ISO, Fit to Model
• Drag-and-drop GLB / GLTF loading
• JSON annotation export + screenshot export
• AI Assistant (via Anthropic API): summarize, find issues, review annotations, suggest comments
• Keyboard shortcuts for all tools

Install

npm install vikcraft-3d-annotator three

Quick Start

HTML + Import Map

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">
<link rel="stylesheet" href="node_modules/vikcraft-3d-annotator/vikcraft-3d-annotator.css">

<script type="importmap">
{
  "imports": {
    "three":          "https://unpkg.com/[email protected]/build/three.module.js",
    "three/addons/":  "https://unpkg.com/[email protected]/examples/jsm/"
  }
}
</script>

<div id="viewer" style="width:100%;height:90vh;"></div>

<script type="module">
  import { VikCraft3DAnnotator } from 'node_modules/vikcraft-3d-annotator/vikcraft-3d-annotator.js';
  import * as THREE from 'three';
  import { OrbitControls }                      from 'three/addons/controls/OrbitControls.js';
  import { GLTFLoader }                         from 'three/addons/loaders/GLTFLoader.js';
  import { EffectComposer }                     from 'three/addons/postprocessing/EffectComposer.js';
  import { RenderPass }                         from 'three/addons/postprocessing/RenderPass.js';
  import { OutlinePass }                        from 'three/addons/postprocessing/OutlinePass.js';
  import { OutputPass }                         from 'three/addons/postprocessing/OutputPass.js';
  import { TransformControls }                  from 'three/addons/controls/TransformControls.js';
  import { CSS2DRenderer, CSS2DObject }         from 'three/addons/renderers/CSS2DRenderer.js';

  const viewer = new VikCraft3DAnnotator('viewer', {
    THREE, OrbitControls, EffectComposer, RenderPass, OutlinePass, OutputPass,
    TransformControls, CSS2DRenderer, CSS2DObject,
    gltfLoader: new GLTFLoader(),

    modelUrl:    './model.glb',
    mode:        'edit',         // 'edit' | 'comment' | 'view'
    currentUser: 'Engineer',
    sceneUnitScale: 1,           // 1 unit = 1 meter
    displayUnits: 'metric',      // 'metric' | 'imperial'

    // AI (optional)
    // ai: { apiKey: 'sk-ant-...', model: 'claude-opus-4-5' },

    onModelLoaded:       ()   => viewer.loadAnnotations(savedAnnotations),
    onAnnotationAdded:   (a)  => api.save(a),
    onAnnotationUpdated: (a)  => api.update(a),
    onAnnotationDeleted: (id) => api.delete(id),
  });
</script>

Annotation Data Shape

{
  id:           "a3d-1713000000000-abc",
  type:         "pin",           // pin|arrow|callout|measure|text|stamp|cloud
  points:       [[x, y, z], ...], // world-space coordinates
  normal:       [0, 1, 0],       // surface normal (pin/stamp)
  comment:      "Weld crack here",
  category:     "Safety",        // Note|Safety|Design|Dimension|Quality|…
  color:        "#E53935",
  opacity:      1.0,
  stampLabel:   "FOR REVIEW",    // stamp type only
  measureLabel: "12.40 cm",      // measure type only
  user:         "Engineer",
  createdAt:    "2026-04-15T10:00:00.000Z"
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | THREE | Module | — | Required. Three.js core | | OrbitControls | Class | — | Required. Camera controls | | gltfLoader | Instance | — | Required. GLTFLoader (configure DRACOLoader if needed) | | EffectComposer, RenderPass, OutlinePass, OutputPass | Classes | — | Required. Post-processing | | TransformControls | Class | — | Required. Model transform gizmo | | CSS2DRenderer, CSS2DObject | Classes | — | Required. 3D label rendering | | modelUrl | string | null | Auto-load a GLB/GLTF on init | | mode | string | 'edit' | 'edit' / 'comment' / 'view' | | currentUser | string | 'Guest' | User shown on annotation cards | | sceneUnitScale | number | 1 | Unit → meter multiplier for measurements | | displayUnits | string | 'metric' | 'metric' or 'imperial' | | ai | object | null | { apiKey, model } — enables AI panel |

Public API

viewer.loadModel(url, filename?)    // Load a model programmatically
viewer.loadAnnotations(array)       // Restore saved annotations
viewer.getAnnotations()             // → copy of annotations array
viewer.setTool(name)                // 'navigate'|'pin'|'arrow'|'callout'|'measure'|'text'|'stamp'|'cloud'|'erase'
viewer.setMode(mode)                // 'edit' | 'comment' | 'view'
viewer.setView(preset)              // 'front'|'top'|'right'|'iso'|'back'|'left'
viewer.setViewMode(mode)            // 'default' | 'wireframe' | 'xray'
viewer.fitToModel()                 // Zoom to fit loaded model
viewer.undo()                       // Undo last action (also Ctrl+Z)
viewer.redo()                       // Redo (also Ctrl+Y)
viewer.clearAllAnnotations()        // Delete all annotations
viewer.clearAllMeasurements()       // Delete only measure annotations
viewer.toggleGrid()                 // Toggle grid helper
viewer.toggleAxes()                 // Toggle axes helper
viewer.destroy()                    // Tear down renderer, remove DOM

Keyboard Shortcuts

| Key | Tool | Key | Tool | |-----|------|-----|------| | N | Navigate | M | Measure | | P | Pin | X | Text Label | | A | Arrow | S | Stamp | | C | Callout | L | Cloud Region | | E | Erase | T | Transform | | Ctrl+Z | Undo | Ctrl+Y | Redo | | Delete | Delete selected | Esc | Cancel / Navigate |

CDN

<link rel="stylesheet" href="https://unpkg.com/vikcraft-3d-annotator/vikcraft-3d-annotator.css">
<script type="module">
  import { VikCraft3DAnnotator } from 'https://unpkg.com/vikcraft-3d-annotator/vikcraft-3d-annotator.js';
</script>

License

MIT © VikCraft Pro