luo-image-annotator

一个基于 Vue 3 和 Canvas 的图片标注组件库，支持矩形、多边形、关键点、旋转矩形等多种标注类型，并提供批量标注和预览功能。

环境要求

• Node.js: >= 18.0.0
• npm: >= 9.0.0
• Vue: >= 3.2.0

开发与运行

如果你想本地开发或查看演示，请按照以下步骤操作：

1. 安装依赖

   npm install

2. 启动开发服务器

   npm run dev

   启动后，访问控制台显示的本地地址（通常是 http://localhost:5173/）即可查看演示页面。

3. 构建组件库

   如果你需要打包组件库以发布到 npm：

   npm run build

   构建产物将输出到 dist 目录。

发布到 npm

如果你想更新并发布这个组件库到 npm，请按照以下步骤操作：

1. 构建项目

首先确保代码已经构建为最新的发布版本：

npm run build

这会在 dist 目录下生成打包好的文件。

2. 更新版本号

在发布之前，必须更新 package.json 中的版本号，否则 npm 会拒绝发布。

# 自动更新补丁版本 (例如从 0.0.1 -> 0.0.2)
npm version patch

或者手动修改 package.json 文件中的 version 字段。

3. 登录 npm (如果未登录)

如果你还没有登录 npm，或者登录已过期：

npm login

按提示输入你的用户名、密码和邮箱。如果开启了双重验证 (2FA)，还需要输入一次性验证码。

4. 发布

执行发布命令：

npm publish

注意： 由于 npm 强制要求开启双重验证 (2FA)，发布时可能需要提供验证码。 请在命令后加上 --otp 参数，填入你手机验证器 App (如 Google Authenticator) 上的 6 位数字，或者使用 npm 提供的恢复码 (Recovery Code)：

# 示例：使用手机验证码
npm publish --otp=123456

# 示例：使用恢复码 (如果你无法使用手机 App)
npm publish --otp=你的恢复码字符串

发布成功后，你就可以在其他项目中通过 npm update luo-image-annotator 来获取最新版本了。

在其他项目中使用

1. 安装

在你的 Vue 3 项目中安装本组件库：

npm install luo-image-annotator

2. 引入样式与组件

在 main.ts 或 main.js 中引入样式和组件：

import { createApp } from 'vue'
import App from './App.vue'

// 1. 引入本组件库样式
import 'luo-image-annotator/dist/style.css'

// 2. 引入组件
import { BatchAnnotator } from 'luo-image-annotator'

const app = createApp(App)

// 全局注册 BatchAnnotator 组件
app.component('BatchAnnotator', BatchAnnotator)

app.mount('#app')

3. 平台嵌入流程（推荐）

第一步：平台下发任务与图片

平台侧准备以下数据并传入组件：

• batchImages：图片与历史标注
• labels：标签体系
• session：projectId/taskId/userId/role
• requestId：一次页面会话追踪 ID

第二步：监听标准化事件

组件会发出两类事件：

• 兼容事件：annotationChange、batchChange、labelChange
• 标准事件：annotation:add、annotation:update、annotation:delete、annotation:select、prediction:*、review:action、qa:issue

平台建议仅消费标准事件做业务编排，兼容事件用于平滑迁移。

第三步：自动标注闭环

1. 用户点击自动标注按钮，调用组件实例 requestPrediction(threshold)
2. 组件触发 prediction:request 事件
3. 平台调用算法服务，拿到候选结果后调用组件实例 loadPredictionCandidates(candidates)
4. 标注员筛选后调用 applyPredictions(ids) 或 rejectPredictions(ids, reason)
5. 平台监听 prediction:apply / prediction:reject 持久化结果

第四步：审阅质检闭环

1. 审阅员调用 reviewAction('pass'|'reject'|'revise', annotationIds, comment)
2. 组件更新标注 reviewStatus 并触发 review:action
3. 质检员调用 reportQaIssue(issueType, annotationIds, detail) 触发 qa:issue
4. 平台决定状态流转与权限校验

4. 局部引入示例

你也可以在单个 .vue 文件中局部引入：

<template>
  <div style="height: 100vh;">
    <ImageAnnotator
      ref="annotatorRef"
      :batchImages="images"
      :labels="labels"
      :annotationTypes="['rectangle', 'polygon', 'point', 'rotatedRect']"
      :session="session"
      :requestId="requestId"
      :predictionCandidates="predictionCandidates"
      @annotation:add="onAnnotationAdd"
      @annotation:update="onAnnotationUpdate"
      @annotation:delete="onAnnotationDelete"
      @prediction:request="onPredictionRequest"
      @prediction:apply="onPredictionApply"
      @prediction:reject="onPredictionReject"
      @review:action="onReviewAction"
      @qa:issue="onQaIssue"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { ImageAnnotator } from 'luo-image-annotator';
import 'luo-image-annotator/dist/style.css'; // 别忘了引入样式

const annotatorRef = ref<InstanceType<typeof ImageAnnotator> | null>(null);

// 定义标签
const labels = [
  { id: '1', name: 'Person', color: '#FF0000', visible: true },
  { id: '2', name: 'Car', color: '#00FF00', visible: true }
];

// 定义图片数据
const images = ref([
  {
    imageUrl: 'https://example.com/image1.jpg',
    annotations: [] // 初始标注为空
  },
  // ... 更多图片
]);

const session = {
  projectId: 'proj-1',
  taskId: 'task-1001',
  userId: 'u-01',
  role: 'annotator'
};

const requestId = 'req-20260318-001';
const predictionCandidates = ref([]);

const onAnnotationAdd = (payload) => {
  console.log('新增标注', payload);
};

const onAnnotationUpdate = (payload) => {
  console.log('更新标注', payload);
};

const onAnnotationDelete = (payload) => {
  console.log('删除标注', payload);
};

const onPredictionRequest = async () => {
  const fakeCandidates = [
    {
      id: 'pred-1',
      confidence: 0.92,
      modelRunId: 'run-1',
      annotation: {
        id: 'a-pred-1',
        type: 'rectangle',
        label: 'Person',
        coordinates: { x1: 120, y1: 80, x2: 260, y2: 320 }
      }
    }
  ];
  annotatorRef.value?.loadPredictionCandidates(fakeCandidates);
};

const onPredictionApply = (payload) => {
  console.log('接受预测', payload);
};

const onPredictionReject = (payload) => {
  console.log('拒绝预测', payload);
};

const onReviewAction = (payload) => {
  console.log('审阅动作', payload);
};

const onQaIssue = (payload) => {
  console.log('质检问题', payload);
};
</script>

组件 API

BatchAnnotator Props

| 属性名 | 类型 | 必填 | 描述 | | --- | --- | --- | --- | | images | Array | 是 | 图片列表，包含 imageUrl 和 annotations | | labels | Array | 是 | 标签定义列表，包含 id, name, color, visible |

BatchAnnotator Events

| 事件名 | 参数 | 描述 | | --- | --- | --- | | export | data: Array | 点击“导出”按钮时触发，返回最新的图片和标注数据 | | update:images | data: Array | 当标注数据发生变化时触发，支持 v-model:images |

ImageAnnotator Props（新增能力）

| 属性名 | 类型 | 必填 | 描述 | | --- | --- | --- | --- | | batchImages | Array | 否 | 批量图片与标注，支持为每张图传入 width/height 提升缩略图标注对齐精度 | | image | Object | 否 | 单图模式输入，结构 { id, url, meta } | | labels | Array | 否 | 标签定义 | | annotationTypes | Array | 否 | 工具类型列表 | | predictionCandidates | Array | 否 | 自动标注候选结果 | | reviewMode | string | 否 | off/reviewer/qa | | session | Object | 否 | 会话上下文 { projectId, taskId, userId, role } | | requestId | string | 否 | 平台链路追踪 ID |

ImageAnnotator 标准事件

| 事件名 | 描述 | | --- | --- | | ready | 组件初始化完成 | | tool:change | 工具切换 | | viewport:change | 画布缩放/视口变化 | | annotation:add | 新增标注 | | annotation:update | 更新标注 | | annotation:delete | 删除标注 | | annotation:select | 选中标注 | | prediction:request | 请求自动标注 | | prediction:loaded | 自动标注候选已加载 | | prediction:apply | 接受候选结果 | | prediction:reject | 拒绝候选结果 | | review:action | 审阅动作 | | qa:issue | 质检问题上报 | | error | 错误事件 |

标注交互规则

• 仅当工具切换为 select（选择）时，才能选中已有标注。
• 当工具为 rectangle、polygon、point、rotatedRect 时，点击画布不会选中已有标注，只会进入绘制流程。
• 删除按钮仅在 select 模式且存在已选中标注时显示。
• 键盘 Delete/Backspace 仅在 select 模式且存在已选中标注时生效。

ImageAnnotator 实例方法

| 方法名 | 参数 | 描述 | | --- | --- | --- | | jumpTo | (index: number) | 批量模式跳转指定图片 | | setImage | (image, annotations?) | 设置单图及标注 | | setAnnotations | (annotations) | 覆盖当前标注 | | getAnnotations | () | 获取当前标注 | | selectTool | (tool) | 切换工具 | | requestPrediction | (threshold?) | 触发自动标注请求事件 | | loadPredictionCandidates | (candidates) | 加载自动标注候选 | | applyPredictions | (candidateIds, threshold?) | 批量接受候选 | | rejectPredictions | (candidateIds, reason?) | 批量拒绝候选 | | reviewAction | (action, annotationIds, comment?) | 执行审阅动作 | | reportQaIssue | (issueType, annotationIds, detail?) | 上报质检问题 | | exportAnnotations | (format?) | 导出当前结果 |

许可证

MIT