[LITE] Annotator - a Lightweight Annotation System for Babylon Lite

Annotator is a lightweight annotation system for Babylon Lite that provides world-space labels, dimensions, callouts, markers, and stable annotations for regular meshes and @litools/instancer instances.

Babylon Lite provides the rendering foundation required for interactive 3D applications, but application developers still need higher-level tools for presenting spatial information.

Common use cases include:

  • Displaying labels above objects.
  • Showing dimensions between points.
  • Attaching callouts to parts.
  • Placing markers in world space.
  • Keeping annotations readable on screen.
  • Hiding labels behind geometry.
  • Preventing label overlap.
  • Attaching annotations to stable Instancer IDs.
  • Making annotations interactive.

@litools/annotator provides these capabilities without becoming a general GUI framework.

Babylon Lite renders the scene. @litools/annotator explains the scene.

Annotator Demo (some of them really worth to see :slight_smile: ).

The HTML backend renders annotations as DOM elements over the canvas. It is the best choice for rich CSS styling, accessibility, familiar browser layout, and smaller annotation counts.

The fast GPU TextRenderer backend renders text, markers, backgrounds, and leader lines through Babylon Lite. It batches large annotation sets efficiently and is the better choice for dense or frequently changing 3D scenes.
Yes, it is FAST!

npm install @litools/annotator

The next steps will be further GPU TextRenderer path optimization, then DynamicTexture support.

Feedback and PRs are welcome!

10 Likes

I love this!

1 Like

Same!

Looks neat !!!

I’m going to use this right now.

Note: In the depth occlution demo, occlution detection appears to be flaky depending on the camera angle.

1 Like

The flakiness is tunable :slight_smile:
Depth occlusion is experimental at the moment. Not enough public API in Lite.
Check GPU renderer too. It is several times faster than HTML labels.

2 Likes

The next update made the fast FASTER.

  • Add stable-live-count label and marker appearance-churn benchmark cases with cache/atlas statistics, and consolidate benchmark methodology and reference results in BENCHMARK.md.
  • Bound parsed-color, marker-frame, and nine-slice background-frame caches with configurable limits, LRU/reference-aware eviction, live-frame protection, a hard logical atlas-frame cap, and cache/atlas/eviction diagnostics.
  • Clarify that animation: { type: "pulse" } always selects the GPU Sprite FX path by default; CPU-driven per-frame pulse updates remain only as a benchmark comparison workload.
  • Translate clean label position batches independently per z-index text bucket, retaining the allocation-free glyph-slot fast path for mixed-z workloads.
  • Patch compatible changing label runs directly into existing Lite glyph slots, avoiding replacement runs and positioned-glyph arrays for fixed-format numeric churn, with lifetime patch/slot/fallback diagnostics.
  • Cache per-size ASCII digit glyph metrics and reflow proportional advances so same-length numeric substitutions also bypass general text shaping.
  • Record the workload-version 2 thorough baseline: 500-label numeric churn dropped from 46.295 ms to 4.633 ms mean with no samples over 16.7 ms, while mixed-z movement dropped from 1.409 ms to 0.617 ms with zero translation fallbacks.
  • Add opt-in labelBackgroundMode: "rounded-card" GPU backgrounds using one analytic Sprite2D instance per label, while retaining nine-slice backgrounds as the default. Rounded cards batch by z-index and visual style and expose layer/draw-call statistics.
  • Add a side-by-side GPU background-mode example comparing identical nine-slice and rounded-card labels with live sprite and draw-call statistics.
  • Add a deterministic GPU label benchmark with quick and three-round thorough profiles, ten workloads through 1,000 labels, p50/p95/p99 CPU and frame metrics, fast-path/cache counters, correctness checksums, and JSON export.
  • Add guarded Babylon Lite glyph-slot translation for clean same-bucket label batches, avoiding replacement run and glyph-array allocations with a safe public replaceRun fallback.
  • Cache extracted glyph curves per GPU backend and upload only previously unseen glyphs, with installed-glyph and upload-batch statistics.
  • Read Babylon occlusion samples from the default scene render task’s private live depth texture so the queries use the exact depth buffer shown on screen.

More info here - lite-instancer/packages/annotator at main · eldinor/lite-instancer · GitHub

3 Likes

Love this!