Sync Label

English

一个基于 Three.js 的高性能 3D 标注库，支持使用自定义着色器对点、多边形、线、箭头和文字进行实例化渲染。

性能分析

渲染 100 万个点元素，帧率保持 60fps，仅需 10 个 drawcall。

测试环境

• CPU: AMD Ryzen 7 5800 8-Core Processor
• GPU: NVIDIA GeForce GTX 1660 Ti

特性

• 高性能 — 基于 Three.js InstancedMesh + 自定义着色器，单实例可承载 10 万个标注元素，支持百万级标注点渲染
• 帧批量响应式 — 自定义响应式系统，同一帧内的增删改操作会自动合并去重，仅在帧刷新时统一触发渲染更新
• 可伸缩文字标签 — 点、多边形、线自带文字标签显示，支持屏幕空间偏移和缩放
• 线 & 箭头 — 支持线段（含虚线）和独立箭头实例，可在线段末端附着箭头
• 自定义着色器 — 全部使用自定义 GLSL 着色器渲染，支持屏幕空间尺寸限制、独立透明度、旋转/缩放
• 生命周期钩子 — 提供完整的帧循环生命周期：awake → beforeStart → start → (beforeUpdate → update → render → afterUpdate → nextFrame) → destroy

安装

pnpm add sync-label

快速开始

import * as SYNC_LABEL from 'sync-label';

// 1. 初始化渲染引擎
await SYNC_LABEL.init({
  engine: {
    engineType: 'THREEJS',
    camera: {
      config: { type: 'PERSPECTIVE', fov: 75, aspect: 2, near: 1, far: 100000 },
      position: { x: 0, y: 0, z: 14 },
      lookAt: { x: 0, y: 0, z: 0 },
    },
    scene: { background: '#000000' },
    renderer: { element: '#app' },
  },
});

// 2. 创建标注元素
const pointMap = SYNC_LABEL.generatePointMap();
const polygonMap = SYNC_LABEL.generatePolygonMap();
const textMap = SYNC_LABEL.generateTextMap();
const lineMap = SYNC_LABEL.generateLineMap();
const arrowMap = SYNC_LABEL.generateArrowMap();

// 3. 添加标注
pointMap.set('point-1', {
  id: 'point-1',
  position: { x: 0, y: 0, z: 0 },
  width: 10,
  height: 10,
  color: '#ff0000ff',
  showID: true,
});

polygonMap.set('poly-1', {
  id: 'poly-1',
  positions: [
    { x: -5, y: 0, z: -5 },
    { x: -5, y: 0, z: 5 },
    { x: 5, y: 0, z: 5 },
    { x: 5, y: 0, z: -5 },
  ],
  color: '#00ff0080',
  showID: true,
});

lineMap.set('line-1', {
  id: 'line-1',
  positions: [
    { x: -5, y: 0, z: -5 },
    { x: 0, y: 0, z: 0 },
    { x: 5, y: 0, z: 5 },
  ],
  color: '#ff0000ff',
  lineWidth: 2,
  arrowSize: 0.5,   // 末端箭头大小，0 为无箭头
  dashSize: 1,       // 实线长度（虚线模式）
  gapSize: 0,        // 间隙长度（0 为实线）
  showID: true,
});

arrowMap.set('arrow-1', {
  id: 'arrow-1',
  position: { x: 0, y: 0, z: 0 },
  rotation: { x: 0, y: 0, z: Math.PI / 4 },
  width: 2,          // 箭头底部宽度
  height: 6,         // 箭头长度
  color: '#00ff00ff',
});

// 4. 更新/删除元素（响应式自动触发渲染）
pointMap.delete('point-1');
pointMap.set('point-2', { ... });

API

初始化

SYNC_LABEL.init(config) — 初始化渲染引擎，接受包含 engine/textConfig 的配置对象。

标注生成器

| 函数 | 返回 | 描述 | |------|------|------| | generatePointMap() | Map<string, T_StandaloneAnnotate> | 创建点标注集合（独立实例，支持独立变换） | | generatePolygonMap() | Map<string, T_DependentAnnotate> | 创建多边形标注集合（自动三角剖分） | | generateLineMap() | Map<string, T_DependentLineAnnotate> | 创建线段标注集合（支持虚线、末端箭头） | | generateArrowMap() | Map<string, T_StandaloneAnnotate> | 创建箭头标注集合（独立实例，支持独立变换） | | generateTextMap() | Map<string, T_DependentTextAnnotate> | 创建文字标注集合 |

生成的 Map 是响应式的，标准的 set/delete/clear 操作会自动触发渲染更新。

生命周期钩子

| 函数 | 触发时机 | |------|----------| | onAwake(cb) | init 调用时 | | onBeforeStart(cb) | 引擎初始化完成后 | | onStart(cb) | 启动前 | | onBeforeUpdate(cb) | 每帧更新前 | | onUpdate(cb) | 每帧更新 | | onAfterUpdate(cb) | 每帧渲染完成后 | | onNextFrame(cb, delay?) | 指定帧数后执行 | | onResize(cb) | 容器尺寸变化时 | | onDestroy(cb) | 销毁时 |

资源访问

| 函数 | 返回 | |------|------| | getCamera() | Three.js Camera | | getRenderer() | Three.js WebGLRenderer | | getScene() | Three.js Scene |

架构

src/
├── core/          初始化、销毁、生命周期、尺寸适配
├── renderEngine/  渲染引擎抽象层 (BaseRenderEngine → ThreejsRenderEngine)
│   └── primitives/  标注原语 (StandalonePrimitive / DependentPrimitive / DependentLinePrimitive / DependentTextPrimitive)
├── annotates/     标注生成器 (point / polygon / line / arrow / text)，各包含几何体、材质、着色器
├── reactivity/    自定义帧批量响应式系统 (ref / effect / reactive / computed)
├── stores/        GlobalStore 全局单例
├── types/         基于 Zod 的类型定义和校验
├── math/          三角剖分、凸多边形判断、碰撞检测
├── utils/         工具函数
└── config/        渲染顺序常量 (polygon=1000, line=1100, point=1200, arrow=1300, text=1400)

渲染机制

标注元素基于 Three.js InstancedMesh 渲染，每个 Primitive 预分配 100,000 个 instance slot，通过座位复用机制（occupiedSeat / availableSeat）高效管理元素的增删改，避免频繁分配/释放 GPU 内存。不同类型的标注使用自定义着色器，在 GPU 中完成屏幕空间变换和尺寸限制。

开发

# 安装依赖
pnpm install

# 启动 demo
pnpm demo

# 运行测试
pnpm test

# 构建
pnpm build

许可

Mozilla Public License Version 2.0