# annotorious-dev

**Repository Path**: witun/annotorious-dev

## Basic Information

- **Project Name**: annotorious-dev
- **Description**: 此工具类是基于Annotorious:3.8.1版本开发的通用图像标注工具，实现图像的矩形标注，样式定制、图像缩放以及图像切换等功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-07
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Annotorious, annotation

## README

# 图像标注工具类

此工具类是基于Annotorious:3.8.1版本开发的通用图像标注工具，实现图像的矩形标注，样式定制、图像缩放以及图像切换等功能。

## 1. 依赖引入

```bash
npm install @annotorious/annotorious
npm install annotorious-dev
```

## 2. 如何使用（Vue3语法）

```typescript
import ImageAnnotation from "annotorious-dev";

const imgBoxRef = ref<HTMLDivElement>();
const imgRef = ref<HTMLImageElement>();
const anno = new ImageAnnotation({
  el: imgRef.value, // 图片元素
  box: imgBoxRef.value // 图片父元素（计算缩放使用）
});
```

**注意**：为了确保缩放比例计算的准确性，建议在 onBeforeMounted 生命周期钩子中获取图像数据，并在图像的 onLoad 回调中完成注册实例、缩放比例的计算及标注数据的加载。

### 1.1 参数

| 序号 | 参数 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| 1 | `env` | `development` 或 `production` | 设定控制台日志输出级别。生产环境下仅输出错误与异常日志。 |
| 2 | `el` | `string` 或 `HTMLImageElement` | 定义需要进行图像标注的目标元素，支持传入元素 ID 或 DOM 元素。 |
| 3 | `box` | `string` 或 `HTMLImageElement` | 定义图像标注的父容器元素，用于图像缩放时的尺寸计算，支持传入元素 ID 或 DOM 元素。 |
| 4 | `opts` | `ImageAnnotationOptions` | 扩展自 Annotorious 的 `AnnotoriousOpts` 配置，并允许传入用户自定义参数。 |

### 1.2 方法

| 序号 | 方法 | 返回类型 | 说明 |
| :--- | :--- | :--- | :--- |
| 1 | `addAnnotations(annotations: Annotation[])` | `void` | 批量添加标注。若标注 ID 已存在，则覆盖原有数据；通常用于首次加载或重置数据。 |
| 2 | `getAnnotation(id: string)` | `Annotation` | 根据指定 ID 获取对应的标注对象。 |
| 3 | `getCurrentAnnotation()` | `Annotation` | 获取当前正在编辑或处于选中状态的标注。 |
| 4 | `getAnnotations()` | `Annotation[]` | 获取全部标注的数组。 |
| 5 | `clearAnnotations()` | `void` | 清空所有标注数据。 |
| 6 | `deleteAnnotation(id: string)` | `void` | 删除指定 ID 的标注。 |
| 7 | `setAnnotationsVisible(visible: boolean)` | `void` | 全局显示或隐藏所有标注。 |
| 8 | `setAnnotationsFilter(filterTags: string[], visible: boolean)` | `void` | 根据标签筛选标注：仅显示或隐藏包含指定标签的标注。 |
| 9 | `setAnnotationImageZoom(scaleType: number)` | `void` | 执行图像标注的缩放操作：`1` 表示放大（步长 0.1），`-1` 表示缩小（步长 0.1），`0` 表示复位到原始大小。 |
| 10 | `setAnnotationTags(tags: string[])` | `void` | 设定当前待标注的标签集合（后续创建的标注将使用这些标签）。 |
| 11 | `setAnnotationColor(color: string)` | `void` | 设置当前标注的样式颜色，包括边框线条色和标签文字色。 |
| 12 | `reloadAnnotationImage()` | `void` | 重新加载图像并重置标注参数，常用于切换至下一张图片时的初始化。 |

## 3. 附录

### 3.1 构造函数参数示例

```json
{
  "env": "production",
  "el": "imageId",
  "box": "imageBoxId",
  "opts": {
    "style": {
      "fill": "#FFFFFF",
      "fillOpacity": 0.25,
      "stroke": "#409EFF",
      "strokeOpacity": 0.8,
      "strokeWidth": 2
    },
    "user": {
      "id": "markUser002",
      "name": "图像标注人员",
      "isGuest": false
    }
  }
}
```

### 3.2 标注结果（Annotation）示例

```json
{
  "id": "97d01785-bdc3-46ec-94d6-c03700c72d7c",
  "bodies": [
    {
      "id": "5883e985-5b62-412b-b114-471b8b77c48d",
      "annotation": "97d01785-bdc3-46ec-94d6-c03700c72d7c",
      "purpose": "tagging",
      "value": "This is an interesting area!"
    }
  ],
  "target": {
    "annotation": "97d01785-bdc3-46ec-94d6-c03700c72d7c",
    "selector": {
      "type": "RECTANGLE",
      "geometry": {
        "x": 100,
        "y": 100,
        "w": 100,
        "h": 50,
        "rot": 0,
        "bounds": {
          "minX": 100,
          "minY": 100,
          "maxX": 200,
          "maxY": 200
        }
      }
    },
    "creator": {
      "id": "markUser002",
      "name": "图像标注人员",
      "isGuest": false
    }
  },
  "properties": {
    "color": "#409EFF"
  }
}
```

## 4. 参考

- Annotorious工具：<https://annotorious.dev/>