|
| 1 | +> This is documentation for the upcoming v3 of Annotorious. For the latest official v2.x release see the [Annotorious project website](_https://annotorious.github.io_) |
| 2 | +
|
| 3 | +# Getting Started |
| 4 | + |
| 5 | +This guide is for the vanilla JavaScript version of Annotorious. For React documentation, [see here](react/image-annotator) |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +```sh |
| 10 | +npm install --save @annotorious/annotorious |
| 11 | +``` |
| 12 | + |
| 13 | +Create an annotator instance on an existing Image element. |
| 14 | + |
| 15 | +```js |
| 16 | +import { createImageAnnotator } from '@annotorious/annotorious'; |
| 17 | + |
| 18 | +// Import essential CSS styles |
| 19 | +import '@annotorious/annotorious/annotorious.css'; |
| 20 | + |
| 21 | +// Image element ID or DOM element |
| 22 | +const anno = createImageAnnotator('sample-image'); |
| 23 | + |
| 24 | +// Load annotations in W3C Web Annotation format |
| 25 | +anno.loadAnnotations('./annotations.w3c.json'); |
| 26 | + |
| 27 | +// Attach listeners to handle annotation events |
| 28 | +anno.on('createAnnotation', function(annotation) { |
| 29 | + console.log('created', annotation); |
| 30 | +}); |
| 31 | +``` |
| 32 | + |
| 33 | +### Script Import via CDN |
| 34 | + |
| 35 | +```html |
| 36 | +<html> |
| 37 | + <head> |
| 38 | + <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.css"> |
| 39 | + <script src="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.js"></script> |
| 40 | + </head> |
| 41 | + <body> |
| 42 | + <img id="my-image" src="my-image.jpg" /> |
| 43 | + |
| 44 | + <script> |
| 45 | + window.onload = function() { |
| 46 | + var anno = Annotorious.createImageAnnotator('my-image'); |
| 47 | + } |
| 48 | + </script> |
| 49 | + </body> |
| 50 | +</html> |
| 51 | +``` |
| 52 | + |
| 53 | +## API |
| 54 | + |
| 55 | +### `createImageAnnotator(image, options?)` |
| 56 | + |
| 57 | +Create a new image annotator instance on an image. Returns [ImageAnnotator](api/imageannotator). |
| 58 | + |
| 59 | +| Arg | Type | Description | |
| 60 | +|---------|---------------------------------------|---------------------------| |
| 61 | +| `image` | `string` \| `HTMLImageElement` | DOM element ID or element | |
| 62 | +| `options` | [AnnotoriousOpts](#annotoriousopts) | Init options (optional) | |
| 63 | + |
| 64 | +### AnnotoriousOpts |
| 65 | + |
| 66 | +| Arg | Type | Default | |
| 67 | +|-----------------------|-------------------------------------------------|---------------| |
| 68 | +| `adapter` | [FormatAdapter](#formatadapter) | - | |
| 69 | +| `autoSave` | `boolean` | `false` | |
| 70 | +| `drawingEnabled` | `boolean` | `true` | |
| 71 | +| `drawingMode` | `'click'` \| `'drag'` | `'drag'` | |
| 72 | +| `pointerSelectAction` | [PointerSelectDefinition](#pointerselectaction) | `'EDIT'` | |
| 73 | +| `style` | [StyleDefinition](#style) | - | |
| 74 | +| `theme` | `'dark'` \| `'light'` \| `'auto'` | `'light'` | |
| 75 | + |
| 76 | +### FormatAdapter |
| 77 | + |
| 78 | +The `adapter` prop is an optional object that introduces crosswalk functionality between Annotorious' internal annotation data model and different standards. This allows seamless integration of external annotation standards, such as the [W3C Web Annotation standard](https://www.w3.org/TR/annotation-model/), into Annotorious. The adapter will handle the process of parsing and serializing annotations between Annotorious' internal format and the chosen external standard for you. |
| 79 | + |
| 80 | +When using a format adapter, it impacts all methods of the vanilla `anno` ImageAnnotator instance. Currently, the W3C adapter is only available adapter for Annotorious. |
| 81 | + |
| 82 | +```js |
| 83 | +import { createImageAnnotator, W3CImageFormat } from '@annotorious/annotorious'; |
| 84 | + |
| 85 | +const anno = createImageAnnotator('sample-image', { |
| 86 | + adapter: W3CImageFormat() |
| 87 | +}); |
| 88 | +``` |
| 89 | + |
| 90 | +### PointerSelectAction |
| 91 | + |
| 92 | +The `pointerSelectAction` prop controls the behavior when a user clicks or taps on an annotation. Valid values for pointerSelectAction are `EDIT`, `SELECT`, and `NONE`. |
| 93 | + |
| 94 | +- __EDIT__ makes the annotation editable, allowing the users to modify its shape. |
| 95 | + |
| 96 | +- __SELECT__ ensures that clicking an annotation will trigger the relevant selection lifecycle events of the API. However, the annotation will not become editable. |
| 97 | + |
| 98 | +- __NONE__ renders the annotation inert. Clicking on it will have no effect. |
| 99 | + |
| 100 | +You can directly assign one of these values to pointerSelectAction. For example: |
| 101 | + |
| 102 | +```ts |
| 103 | +import { createImageAnnotator, PointerSelectionAction, W3CImageFormat } from '@annotorious/annotorious'; |
| 104 | + |
| 105 | +const anno = createImageAnnotator('sample-image', { |
| 106 | + pointerSelectAction: PointerSelectAction.EDIT |
| 107 | +}); |
| 108 | +``` |
| 109 | + |
| 110 | +Alternatively, you can use a function that dynamically determines the `pointerSelectAction`` based on annotation properties or other conditions: |
| 111 | + |
| 112 | +```ts |
| 113 | +import { createImageAnnotator, PointerSelectionAction, W3CImageFormat } from '@annotorious/annotorious'; |
| 114 | + |
| 115 | +const dynamicSelectAction = (annotation: Annotation) => { |
| 116 | + const isMine = annotation.target.creator.id == 'me'; |
| 117 | + return isMine ? PointerSelectAction.EDIT : PointerSelectAction.SELECT; |
| 118 | +}; |
| 119 | + |
| 120 | +const anno = createImageAnnotator('sample-image', { |
| 121 | + pointerSelectAction: dynamicSelectAction |
| 122 | +}); |
| 123 | +``` |
| 124 | + |
| 125 | +__Note:__ |
| 126 | + |
| 127 | +For TypeScript users, the valid values for `pointerSelectAction` are provided as enums for type safety. However, in plain JavaScript, you can use the string values ('EDIT', 'SELECT', 'NONE') directly. |
| 128 | + |
| 129 | +### Style |
| 130 | + |
| 131 | +The `style` argument allows you to customize the visual appearance of annotations. You can define a style as either an object or a function. |
| 132 | + |
| 133 | +The object should have the following shape: |
| 134 | + |
| 135 | +```js |
| 136 | +const style = { |
| 137 | + fill: '#ff2222', // Fill color in hex format |
| 138 | + fillOpacity: 0.25, // Fill opacity (0 to 1) |
| 139 | + stroke: '#ff0000', // Stroke color in hex format |
| 140 | + strokeOpacity: 0.9, // Stroke opacity (0 to 1) |
| 141 | + strokeWidth: 2 // Stroke width in pixels |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +Alternatively, you can use a function that takes the annotation as input and returns a style object: |
| 146 | + |
| 147 | +```ts |
| 148 | +const dynamicStyle = (annotation) => { |
| 149 | + const isImportant = annotation.bodies.some(b => b.purpose === 'highlighting'); |
| 150 | + |
| 151 | + return { |
| 152 | + fill: '#ffff00', |
| 153 | + fillOpacity: isImportant ? 0.5 : 0, |
| 154 | + stroke: '#000000', |
| 155 | + strokeOpacity: 1, |
| 156 | + strokeWidth: 2 |
| 157 | + }; |
| 158 | +}; |
| 159 | +``` |
0 commit comments