A comprehensive component for tagging images. Check out demo 1 and demo 2 for some examples.

Features

• Bounding Box (Rectangle, Square, Circle, and Ellipse), and Polygon Annotations
• Add, Edit, Drag, Rotate, and Delete Annotations
• Zoom and Pan
• Changing image on the fly
• Colorful annotations
• Raw or typed input/output

Usage

Install react-image-label using npm.

npm install react-image-label

Then you can just import the component and its hook:

import { ImageAnnotator, useImageAnnotator } from 'react-image-label';

and use it as below:

const { setHandles, annotator } = useImageAnnotator();

<ImageAnnotator
  setHandles={setHandles}
  naturalSize={true}
  imageUrl={'your-image-url'}  
  shortcut={{del: true, bksp: true }}
  onReady={annotator => { annotator.drawRectangle() }} />

Now you can draw rectangles on the image by dragging the left mouse button.

Mouse and Keyboard events

• click: Edit/Stop Edit Annotations
• Ctrl + mouse wheel: Zoom
• Ctrl + mouse drag: Pan
• mouse drag: Drag/Edit/Rotate Annotations

when using shortcut={{del: true, bksp: true }} in props (see Shortcut Settings):

• Delete/Backspace key: Delete Annotations

Props

The following props can be defined on ImageAnnotator:

| Prop | Type | Description | Default | |---|---|---|---| | imageUrl * | string | Use a state for image url if you want to change it on the fly | | | shapes | Shape[] \| any[] | Annotations being displayed on load (see shapes) | | | naturalSize | boolean | To show image in its natural size | false | | width | number | container width | image.naturalWidth | | height | number | container height | image.naturalHeight | | discRadius | number | The radius of the green discs in edit mode | 5 | | hideBorder | boolean | To hide annotation border | false | | shortcut | Shortcut | To configure shortcuts (see Shortcut Settings) | | | onAdded | Shape => any | When an annotation is drawn (see Annotations with Categories) | | | onEdited | Shape => any | When an annotation is reshaped, dragged, or rotated | | | onSelected | Shape => any | When an annotation goes into edit mode by double-clicking | | | onContextMenu | Shape => any | When an annotation is right-clicked (see Annotations with Categories) | | | onReady | AnnotatorHandles => any | When the component is mounted | |

(*) required props

Handles

You can access the handles using the annotator object as follows:

<button onClick={() => { annotator.drawCircle() }}>Draw Circle</button>

Below is a list of all handles:

| Handle | Type | Description | |---|---|---| | drawCircle | () => void | Allows drawing circles by dragging the left mouse button | | drawEllipse | () => void | Allows drawing ellipses by dragging the left mouse button | | drawRectangle | () => void | Allows drawing rectangles by dragging the left mouse button (keep the shift key to draw square) | | drawPolygon | () => void | Allows drawing polygons by clicking and double-clicking | | drawDot | () => void | Allows adding dots (points) by clicking | | stop | () => void | Stops draw/edit/drag mode | | edit | (id: number) => void | The annotation identified by id can be edited and dragged | | delete | (id: number) => void | Removes the annotation identified by id | | stopEdit | () => void | Stops editing and dragging | | updateCategories | (id: number, categories: string[], color?: string) => void | Updates the categories associated with the annotation identified by id | | zoom | (factor: number) => void | Multiplies the dimensions by factor | | getShapes | () => Shape[] | Gets all annotations (shapes) | | container | HTMLDivElement | The div wrapping the SVG |

Annotations with Categories

To attach one or more categories to an annotation, utilize onAdded and onContextMenu props being called when an annotation is drawn and right-clicked, respectively. Use shape.categories to get the previous categories as string[]:

const showCategoriesDialog = (shape) => {
  console.log(shape.id) // 1
  console.log(shape.getCenterWithOffset()) // { X: 247.5, Y: 193 }
  console.log(shape.categories) // string []
  // Show a category selection component
}

return (
  <ImageAnnotator
    onAdded={showCategoriesDialog}
    onContextMenu={showCategoriesDialog}
    ...
);

Finally, call annotator.updateCategories to update the categories of the annotation.

Shapes

The data models for all shapes are listed below:

| Shape | Data Model | type Value | |---|---|---| | Circle | { id: number, centre: [number, number], radius: number, categories: string[], type: string, color: string } | circle | | Ellipse | { id: number, centre: [number, number], radiusX: number, radiusY: number, phi: number, categories: string[], type: string, color: string } |ellipse | | Rectangle | { id: number, points: [number, number][], phi: number, categories: string[], type: string, color: string } | rectangle | | Polygon | { id: number, points: [number, number][], categories: string[], type: string, color: string } | polygon | | Dot | { id: number, position: [number, number], categories: string[], type: string, color: string } | dot |

Shortcut Settings

Below is a list of shortcuts that are configured through shortcut prop:

| Key | Type | Description | Default | |---|---|---|---| | del | boolean | To enable the Delete key to remove the annotation that is in edit mode | false | | bksp | boolean | To enable the Backspace key to remove the annotation that is in edit mode | false |

Contributing

• Fork the project.
• Make changes.
• Run the project in development mode: npm run ladle.
• Write your own tests and/or update existing ones in src/test dir.
• Check the new features and changes using annotator.stories.tsx or your own Stories (*.stories.tsx).
• Update README with appropriate docs.
• Commit and PR

Dependencies

The package is dependent on SVG.js through react-svgdotjs package. The following peer dependencies must be specified by your project in order to avoid version conflicts: react, react-dom. NPM will not automatically install these for you but it will show you a warning message with instructions on how to install them.