Vue Image Annotator

A powerful Vue 3 component for image annotation with bounding boxes, supporting various annotation features and export formats.

Features

• 🎯 Draw and edit bounding boxes with precision
• 📝 Add and edit text labels for each box
• 🔄 Undo/Redo support for all operations
• 📊 Export annotations to YOLO format
• 🔍 Zoom and pan support for detailed annotation
• 📱 Responsive layout for all screen sizes
• 🎨 Customizable box styles and colors
• ⌨️ Keyboard shortcuts for quick operations
• 💾 Save and load annotation states
• 🎯 Multi-box selection and batch operations

Installation

# Using npm
npm install @iwhero/vue-image-annotator

# Using yarn
yarn add @iwhero/vue-image-annotator

# Using pnpm
pnpm add @iwhero/vue-image-annotator

Quick Start

<template>
  <image-annotator
    v-model:labels="labels"
    :img-url="imageUrl"
    @update:labels="handleLabelsUpdate"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ImageAnnotator, type LabelJsonItemProps } from '@iwhero/vue-image-annotator'

const labels = ref<LabelJsonItemProps[]>([])
const imageUrl = ref('path/to/your/image.jpg')

const handleLabelsUpdate = (newLabels: LabelJsonItemProps[]) => {
  console.log('Labels updated:', newLabels)
}
</script>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | labels | LabelJsonItemProps[] | [] | Array of label objects | | imgUrl | string | '' | URL of the image to annotate | | zoom | number | 1 | Initial zoom level | | minZoom | number | 0.1 | Minimum zoom level | | maxZoom | number | 5 | Maximum zoom level | | boxColor | string | '#ff0000' | Default color for boxes | | selectedBoxColor | string | '#00ff00' | Color for selected boxes |

Events

| Event | Parameters | Description | |-------|------------|-------------| | update:labels | LabelJsonItemProps[] | Emitted when labels are updated | | box:select | LabelJsonItemProps | Emitted when a box is selected | | box:deselect | LabelJsonItemProps | Emitted when a box is deselected |

Label Object Structure

interface LabelJsonItemProps {
  id: string;          // Unique identifier for the box
  x: number;           // X coordinate (percentage of image width)
  y: number;           // Y coordinate (percentage of image height)
  width: number;       // Width (percentage of image width)
  height: number;      // Height (percentage of image height)
  text: string;        // Label text
  selected: boolean;   // Selection state
  json?: Map<string, string>; // Additional metadata
}

Keyboard Shortcuts

• Delete - Delete selected box
• Ctrl + Z - Undo last operation
• Ctrl + Y - Redo last operation
• Space - Toggle pan/select mode
• Esc - Deselect current box

Export Format

The component supports exporting annotations in YOLO format:

// Example of exported YOLO format
{
  class: number;
  x_center: number;  // normalized center x
  y_center: number;  // normalized center y
  width: number;     // normalized width
  height: number;    // normalized height
}

Dependencies

• Vue 3
• Element Plus
• Vue Konva
• UUID

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Leon