Author: | recogito |
---|---|
Views Total: | 115 views |
Official Page: | Go to website |
Last Update: | January 3, 2021 |
License: | BSD-3-Clause |
Preview:

Description:
Annotorious is a simple yet feature-rich JavaScript image annotation library that adds custom comments, notes, tags to a specific part of an image.
Features:
- Load pre-defined annotations from a JSON file.
- Drag and drop to create new annotations from an editor popup.
- Based on W3C WebAnnotation model.
How to use it:
1. Install and import the Annotorious as a module.
# NPM $ npm install @recogito/annotorious --save
import { Annotorious } from '@recogito/annotorious';
2. Or download the package and insert the annotorious.min.js
into the HTML document.
<link rel="annotorious.min.css" href="styles.css" /> <script src="annotorious.min.js"></script>
3. Initialize the Annotorious on the image and we’re ready to go.
<img id="example" src="example.jpg" />
var anno = Annotorious.init({ image: 'example' });
4. Define your annotations in a w3c.json file and load it on page load.
// annotations.w3c.json [ { "@context": "http://www.w3.org/ns/anno.jsonld", "id": "#unique-ID-Here", "type": "Annotation", "body": [{ "type": "TextualBody", "value": "Comments Here" }, { "type": "TextualBody", "purpose": "tagging", "value": "Tag 1" }, { "type": "TextualBody", "purpose": "tagging", "value": "Tag 2" }], "target": { "selector": [{ "type": "FragmentSelector", "conformsTo": "http://www.w3.org/TR/media-frags/", "value": "xywh=pixel:270,120,90,170" }] } } ]
anno.loadAnnotations('annotations.w3c.json');
3. Enable read-only mode. Defaults to false.
var anno = Annotorious.init({ image: 'example', readOnly: true });
4. Disable the editor popup. Defaults to false.
var anno = Annotorious.init({ image: 'example', headless: true });
5. Add a new annotation to the image following the structure you’ve seen in the annotations.w3c.json
.
// add an annotation anno.addAnnotation(annotation [, readOnly]); // add an array of annotations anno.setAnnotations(annotations);
6. Remove an annotation from the image.
anno.removeAnnotation(ID);
7. Get all annotations.
anno.getAnnotations();
8. Select an annotation.
// select the current annotation anno.selectAnnotation(); // select a specific annotation anno.selectAnnotation(ID);
9. Show/hide the annotations.
anno.setAnnotationsVisible(TRUE/FALSE);
10. Apply a custom template to the annotation.
anno.applyTemplate(template, openEditor[TRUE/FALSE]);
11. Set & get author info.
// set anno.setAuthInfo({ id: 'https://cssscript.com', displayName: 'CSSScript' }); // clear anno.clearAuthInfo();
12. Switch between drawing tools: ‘rect’ or ‘polygon’.
anno.setDrawingTool(toolName);
13. Show or hide the annotation layer.
anno.setAnnotationsVisible(boolean);
14. Set a server time timestamp.
anno.setServerTime(timestamp);
15. Destroy the instance.
anno.destroy();
16. Event handlers.
anno.on('changeSelectionTarget', function(target) { // when the shape of a newly created selection }); anno.on('createSelection', function(selection) { // when a new selection shape is drawn on the image }); anno.on('cancelSelection', function(selection) { // do something }); anno.on('selectAnnotation', function(annotation) { console.log('selected', annotation); }); anno.on('createAnnotation', function(a) { console.log('created', a); }); anno.on('updateAnnotation', function(annotation, previous) { console.log('updated', previous, 'with', annotation); }); anno.on('deleteAnnotation', function(annotation) { console.log('deleted', annotation); }); anno.on('mouseEnterAnnotation', function(annotation, event) { console.log('mouseEnter', annotation); }); anno.on('mouseLeaveAnnotation', function(annotation, event) { console.log('mouseLeave', annotation); });
17. Use custom formater function:
// String Example var formatter = function(annotation) { var longComments = annotation.bodies.filter(function(body) { var isComment = body.type === 'TextualBody' && (body.purpose === 'commenting' || body.purpose === 'replying'); var isLong = body.value.length > 100; return isComment && isLong; }); if (longComments.length > 0) { // This annotation contains long comments - add CSS class return 'long'; } } var anno = Annotorious.init({ formatter: formatter }); // Object Example var formatter = function(annotation) { var contributors = []; annotation.bodies.forEach(function(body) { if (body.creator) contributors.push(body.creator.id); }); if (contributors.length > 1) { return { 'data-users': contributors.join(', '), 'style': 'stroke-width:2; stroke: red' } } } var anno = Annotorious.init({ formatter: formatter });
Changelog:
v2.2.0 (01/03/2021)
- Added Dutch UI translation
- New API method clearAnnotations
- Added cancelSelection event, when user hits ‘cancel’ on a newly created shape
- Revised headless API
- New API method saveSelected to save changes to an annotation programmatically
- New API method cancelSelected to cancel programmatically
- Removed support for applyTemplate API function in favor of new headless API. Example: to apply a tag automatically in headless mode
v2.1.7 (12/27/2020)
- Editor bugfixes
- Added getSelectedImageSnippet API method
v2.1.6 (12/20/2020)
- Bugfixes
- Preparations/compatibility plumbing for editable shapes in OpenSeadragon
v2.1.5 (11/30/2020)
- Fixes a regression bug that broke shape editing in v2.1.4
v2.1.4 (11/30/2020)
- UI/behavior: clicking outside the selected shape cancels editing and closes the editor
- Proper handling of multi-line comments in the Comment Widget
- Localized text labels for time expressions (“2 minutes ago”), when using
authInfo
- Added missing Spanish labels for ‘Edit’ and ‘Delete’
v2.1.3 (10/14/2020)
- Dim mask now also available for the polygon drawing tool
- Czech UI translation
- Tag widget: fixed broken autosuggest behavior
- Editor plugins: config params are now properly forwarded to plugin args
v2.1.2 (09/22/2020)
- Environment is no longer a global object, meaning that it is now safe to use multiple Recogito/Annotorious instances on the same page
- All CSS classes are now properly prefixed to avoid clashes with other styles on the page (either with a9s for Annotorious-specific elements or r6o for elements imported from Recogito core
- Small bugfixes to the dim mask
v2.1.1 (09/20/2020)
- CSS styles are no longer embedded in the JavaScript file, but now have to be imported separately.
- Editor widgets are becoming more flexible. This release is the first to include beta support for a plugin API. As a consequence, this version introduces a minimal change to how the tag widget is configured with a controlled vocabulary.
v2.0.8 (09/13/2020)
- Minor bugfix
v2.0.7 (08/29/2020)
- IE11 support bugfixes
v2.0.6 (08/29/2020)
- IE11 compatibility
- Editable polygon shapes
- Bugfixes concerning the behavior of the tag autosuggest component
- Security fixes for library dependencies
v2.0.5 (07/12/2020)
- Added babel polyfill (IE11 compat)
v2.0.4 (07/12/2020)
- Beta support for rendering any SVG shape contained in W3C Web Annotations
- Beta support for polygon drawing
- Various bugfixes
- Portuguese UI translation
- Tag widget: controlled vocabulary autosuggest
- Selecting an annotation now adds a selected CSS class
v2.0.3 (06/12/2020)
- Various smaller bugfixes
- Microsoft Edge compatibility
- Experimental support for responsive images
- Web Annotation standard compliance: target now includes a source property with the image source URL
- Minor API changes: selectAnnotation method now returns selected annotation object and does not fire the selectAnnotation event
- Added support for internationalization
- Ability to handle user information for UI display and when creating/updating annotations
- Ability to add created and modified timestamps, with an option for the host application to sync with the server time
v2.0.2 (05/21/2020)
- Minor bugfixes
- Enabling readOnly annotations
v2.0.2 (05/21/2020)
- Minor bugfixes
The code snippets really helps a lot.