### Basic Annotorious Setup

Source: https://annotorious.dev/react/component-reference

A minimal setup for Annotorious using the root context component and ImageAnnotator.

```jsx
<Annotorious>
  <ImageAnnotator>
    <img src="example.jpg" />
  </ImageAnnotator>
</Annotorious>
```

--------------------------------

### React Image Annotation Setup

Source: https://annotorious.dev/

Basic setup for image annotation using Annotorious React bindings. Ensure you import the necessary CSS styles.

```jsx
import { Annotorious, ImageAnnotator } from '@annotorious/react';

import '@annotorious/react/annotorious-react.css';

export default function App() {

  return (
    <Annotorious>
      <ImageAnnotator>
        <img src="example.jpg" />
      </ImageAnnotator>
    </Annotorious>
  )

}
```

--------------------------------

### Install Annotorious React Package (npm)

Source: https://annotorious.dev/installation

Use this command to install the Annotorious React package, which includes bindings for both standard and OpenSeadragon versions.

```bash
npm install  @annotorious/react
```

--------------------------------

### Install Annotorious Standard Package (npm)

Source: https://annotorious.dev/installation

Use this command to install the standard Annotorious package for annotating JPEG or PNG images.

```bash
npm install @annotorious/annotorious
```

--------------------------------

### Basic React Image Annotation Setup

Source: https://annotorious.dev/react/image-annotation

This is the fundamental setup for using Annotorious in a React application. It requires importing the necessary components and CSS, and wrapping the application with the Annotorious context provider.

```jsx
import { Annotorious, ImageAnnotator } from '@annotorious/react';


import '@annotorious/react/annotorious-react.css';


export default function App() {
  return (
    <Annotorious>
      <ImageAnnotator>
        <img src="example.jpg" />
      </ImageAnnotator>
    </Annotorious>
  );
}
```

--------------------------------

### Install Annotorious OpenSeadragon Package (npm)

Source: https://annotorious.dev/installation

Use this command to install the Annotorious package for annotating zoomable images in OpenSeadragon.

```bash
npm install openseadragon @annotorious/openseadragon
```

--------------------------------

### Install Annotorious Svelte Package (npm)

Source: https://annotorious.dev/installation

Use this command to install the Annotorious Svelte package, which includes bindings for both standard and OpenSeadragon versions.

```bash
npm install  @annotorious/svelte
```

--------------------------------

### Image Annotation Object Example

Source: https://annotorious.dev/api-reference/image-annotation

An example of a typical Annotorious annotation object, illustrating its structure and properties.

```APIDOC
## Image Annotation Object Example

### Description
This example shows the structure of a typical Annotorious annotation object, including its ID, bodies, and target.

### Properties
- **id** (string): Unique ID. Will be auto-generated if not provided.
- **target** (ImageAnnotationTarget): Defines the annotated image region.
- **bodies** (AnnotationBody[]): List of annotation bodies. Defaults to [].
- **properties** (object): Can hold any custom properties you want to associate with the annotation.

### Example
```json
{
  "id": "97d01785-bdc3-46ec-94d6-c03700c72d7c",
  "bodies": [
    {
      "id": "5883e985-5b62-412b-b114-471b8b77c48d",
      "annotation": "97d01785-bdc3-46ec-94d6-c03700c72d7c",
      "purpose": "commenting",
      "value": "This is an interesting area!",
      "creator": {
        "id": "aboutgeo",
        "name": "Rainer"
      },
      "created": "2023-08-23T10:30:00Z"
    }
  ],
  "target": {
    "annotation": "97d01785-bdc3-46ec-94d6-c03700c72d7c",
    "selector": {
      "type": "RECTANGLE",
      "geometry": {
        "x": 100,
        "y": 100,
        "w": 100,
        "h": 50
      }
    },
    "creator": {
      "id": "aboutgeo",
      "name": "Rainer"
    },
    "created": "2023-08-23T10:30:00Z"
  }
}
```
```

--------------------------------

### Basic React Setup with OpenSeadragon Annotator

Source: https://annotorious.dev/react/openseadragon-iiif

Set up the Annotorious context and OpenSeadragon viewer in a React application. Ensure OpenSeadragon options are memoized to prevent re-renders.

```jsx
import {
  useMemo
} from 'react';
import {
  Annotorious,
  OpenSeadragonAnnotator,
  OpenSeadragonViewer
} from '@annotorious/react';


import '@annotorious/react/annotorious-react.css';


export default function App() {


  // IMPORTANT! Memo-ize your options to avoid
  // unexpected re-renders of the OSD viewer.
  const options = useMemo(() => ({
    tileSources: {
      type: 'image',
      url: '/images/sample-image.jpg'
    }
  }), []);


  return (
    <Annotorious>
      <OpenSeadragonAnnotator>
        <OpenSeadragonViewer options={options} />
      </OpenSeadragonAnnotator>
    </Annotorious>
  );
}
```

--------------------------------

### Basic OpenSeadragon and Annotorious Setup

Source: https://annotorious.dev/guides/openseadragon-iiif

Initializes an OpenSeadragon viewer, sets up Annotorious, adds an event listener, and loads annotations from a file. Ensure essential CSS is imported.

```javascript
import OpenSeadragon from 'openseadragon';
import { createOSDAnnotator } from '@annotorious/openseadragon';


// Import essential CSS styles
import '@annotorious/openseadragon/annotorious-openseadragon.css';


// Initialize OpenSeadragon viewer
const viewer = OpenSeadragon({
  element: document.getElementById('my-openseadragon-container'),
  tileSources: {
    type: 'image',
    url: '/images/sample-image.jpg'
  }
});


// Initialize annotator
const anno = createOSDAnnotator(viewer);


// Attach listeners to handle annotation events
anno.on('createAnnotation', function(annotation) {
  console.log('created', annotation);
});


// Load annotations from a JSON file
anno.loadAnnotations('./annotations.json');
```

--------------------------------

### Polygon Shape Example

Source: https://annotorious.dev/api-reference/shape

An example of a Polygon shape object. This includes its type, geometry (an array of points), and bounding box.

```javascript
const polygon = {
  type: 'POLYGON',
  geometry: {
    points: [[10, 10], [20, 20], [10, 20]],
    bounds: { minX: 10, minY: 10, maxX: 20, maxY: 20 }
  }
};
```

--------------------------------

### Basic OpenSeadragon Integration with Annotorious React

Source: https://annotorious.dev/react/component-reference

Demonstrates how to set up Annotorious with OpenSeadragon, enabling annotation on a viewer. This example shows the basic structure for integrating OpenSeadragonViewer and OpenSeadragonPopup within an OpenSeadragonAnnotator.

```jsx
import {
  Annotorious,
  OpenSeadragonAnnotator,
  OpenSeadragonPopup
  OpenSeadragonViewer
} from '@annotorious/react';


import '@annotorious/react/annotorious-react.css';


export default function App() {
  return (
    <Annotorious>
      <OpenSeadragonAnnotator
        drawingEnabled={false}
        tool="polygon">


        <OpenSeadragonViewer
          className="openseadragon"
          options={OSD_OPTIONS} />


        <OpenSeadragonPopup
          popup={props => (
            <div className="annotorious-popup">Hello World</div>
          )} />
      </OpenSeadragonAnnotator>
    </Annotorious>
  );
}
```

--------------------------------

### Initialize Annotorious with Event Listeners and Load Annotations

Source: https://annotorious.dev/guides/annotating-images

Basic example to initialize Annotorious on an image, attach an event listener for annotation creation, and load annotations from a JSON file. Requires importing the Annotorious library and its CSS.

```javascript
import { createImageAnnotator } from '@annotorious/annotorious';


// Import essential CSS styles
import '@annotorious/annotorious/annotorious.css';


// Image element ID or DOM element
const anno = createImageAnnotator('sample-image');


// Attach listeners to handle annotation events
anno.on('createAnnotation', function(annotation) {
  console.log('created', annotation);
});


// Load annotations from a JSON file
anno.loadAnnotations('./annotations.json');
```

--------------------------------

### Create ImageAnnotator with Options

Source: https://annotorious.dev/api-reference/image-annotator

Customize the annotator's behavior by providing an options object during initialization. This example shows how to set custom drawing styles.

```javascript
const anno = createImageAnnotator('sample-image', {
  style: { fill: #ff0000, fillOpacity: 0.4 }
});
```

--------------------------------

### Rectangle Shape Example

Source: https://annotorious.dev/api-reference/shape

An example of a Rectangle shape object. This includes its type, geometry (x, y, width, height), and bounding box.

```javascript
const rectangle = {
  type: 'RECTANGLE',
  geometry: {
    x: 10,
    y: 10,
    w: 100,
    h: 50,
    bounds: { minX: 10, minY: 10, maxX: 110, maxY: 60 }
  }
};
```

--------------------------------

### Basic React Image Annotation Popup

Source: https://annotorious.dev/react/custom-popups

A basic example demonstrating how to use the ImageAnnotationPopup component to display a simple 'Hello World' popup for annotations in a React application. Ensure you include the necessary CSS for styling.

```jsx
import {
  Annotorious,
  ImageAnnotationPopup,
  ImageAnnotator
} from '@annotorious/react';


import './App.css';
import '@annotorious/react/annotorious-react.css';


export default function App() {
  return (
    <Annotorious>
      <ImageAnnotator>
        <img src="example.jpg" />
      </ImageAnnotator>


      <ImageAnnotationPopup
        popup={(props: PopupProps) => (
          <div>
            Hello World
          </div>
        )} />
    </Annotorious>
  );
}
```

```css
.a9s-popup {
  background-color: #ffffff;
  border-radius: 3px;
  padding: 0.25rem 0.625rem;
}


/** SVG popup arrow style **/
.a9s-popup svg {
  fill: #fff;
}
```

--------------------------------

### getAnnotations

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Get all annotations on the image.

```APIDOC
## getAnnotations

### Description
Get all annotations on the image.

### Method
`anno.getAnnotations()`

### Returns
- **Array<ImageAnnotation>**: An array of all annotation objects.

### Request Example
```javascript
const allAnnotations = anno.getAnnotations();
```
```

--------------------------------

### Create Annotator with Options

Source: https://annotorious.dev/guides/annotating-images

Customize the annotator's behavior and appearance by passing an options object during initialization. For example, enabling drawing and setting custom styles.

```javascript
const anno = createImageAnnotator('sample-image', {
  drawingEnabled: true,
  style: {
   fill: '#ff0000',
   fillOpacity: 0.25
  }
});
```

--------------------------------

### Get All Annotations

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Fetch all annotations currently present on the image. Returns an array of annotation objects.

```javascript
const all = anno.getAnnotations();
```

--------------------------------

### getUser

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Get the the user object, if any.

```APIDOC
## getUser

### Description
Get the the user object, if any.

### Method
`anno.getUser()`

### Returns
- **User**: The user object, or `undefined` if no user is set.

### Request Example
```javascript
const currentUser = anno.getUser();
```
```

--------------------------------

### getSelected

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Get the currently selected annotations.

```APIDOC
## getSelected

### Description
Get the currently selected annotations.

### Method
`anno.getSelected()`

### Returns
- **Array<ImageAnnotation>**: An array of the currently selected annotation objects.

### Request Example
```javascript
const selectedAnnotations = anno.getSelected();
```
```

--------------------------------

### Attach Event Listener with anno.on()

Source: https://annotorious.dev/api-reference/events

Use the `anno.on()` method to attach a handler to an annotator instance for specific lifecycle events. This example shows how to log a message when an annotation is clicked.

```javascript
anno.on('clickAnnotation', (annotation) => {
  console.log('User clicked annotation: ' + annotation.id);
});
```

--------------------------------

### Get live annotation state with useAnnotations

Source: https://annotorious.dev/react/hooks-reference

Returns the live annotation state. To limit re-rendering, you can optionally debounce the state updates by providing a number of milliseconds.

```javascript
const annotations: ImageAnnotation[] = useAnnotations(debounce);
```

--------------------------------

### Dynamically Style Annotations with AnnotationState

Source: https://annotorious.dev/api-reference/annotation-state

Use the AnnotationState to dynamically style annotations based on their selection or hover status. This example shows how to set different styles for selected and non-selected annotations.

```javascript
anno.setStyle((annotation, state) => {
  if (state.selected) {
    return {
      fill: '#ff0000',
      fillOpacity: 0.3,
      stroke: '#ff0000',
      strokeOpacity: 1
    };
  }


  // Default style for non-selected annotations
  return {
    fill: '#00ff00',
    fillOpacity: 0.2,
    stroke: '#00ff00',
    strokeOpacity: 1
  };
});
```

--------------------------------

### Getting the current user

Source: https://annotorious.dev/api-reference/user

To retrieve the currently set user, you can use the getUser method.

```APIDOC
## getUser

### Description
Retrieves the current user object.

### Method
```javascript
getUser(): User
```

### Response
#### Success Response (User)
- **id** (string) - A unique identifier for the user.
- **name** (string) - User display name.
- **avatar** (string) - URL to the user’s avatar image.
- **isGuest** (boolean) - Indicates whether the user is a guest.
```

--------------------------------

### Memoized OpenSeadragon Options in Custom Viewer

Source: https://annotorious.dev/react/openseadragon-iiif

Define and memoize OpenSeadragon viewer options within a custom component to prevent unnecessary re-renders. This example also shows the usage of Annotorious hooks.

```jsx
export const MyAnnotatableViewer = () => {


  // You can use Annotorious hooks here!
  const annotations = useAnnotations();


  // ...


  // IMPORTANT! Memo-ize your options to avoid
  // unexpected re-renders of the OSD viewer.
  const options = useMemo(() => ({
   tileSources: {
     type: 'image',
     url: '/images/sample-image.jpg'
   }
  }), []);


  return (
    <OpenSeadragonAnnotator>
      <OpenSeadragonViewer options={options} />
    </OpenSeadragonAnnotator>
  );
}
```

--------------------------------

### Get Current User

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Retrieve the current user object, if it has been configured. Returns the user object or null/undefined.

```javascript
const currentUser = anno.getUser();
```

--------------------------------

### Example Annotorious Annotation Object

Source: https://annotorious.dev/api-reference/image-annotation

This object demonstrates the structure of a typical annotation created with Annotorious, including its ID, bodies, and target region.

```javascript
{
  id: '97d01785-bdc3-46ec-94d6-c03700c72d7c',
  bodies: [
    {
      id: '5883e985-5b62-412b-b114-471b8b77c48d',
      annotation: '97d01785-bdc3-46ec-94d6-c03700c72d7c',
      purpose: 'commenting',
      value: 'This is an interesting area!',
      creator: {
        id: 'aboutgeo',
        name: 'Rainer'
      },
      created: new Date('2023-08-23T10:30:00Z')
    }
  ]
  target: {
    annotation: '97d01785-bdc3-46ec-94d6-c03700c72d7c',
    selector: {
      type: 'RECTANGLE',
      geometry: {
        x: 100,
        y: 100,
        w: 100,
        h: 50
      }
    },
    creator: {
      id: 'aboutgeo',
      name: 'Rainer'
    },
    created: new Date('2023-08-23T10:30:00Z')
  }
};
```

--------------------------------

### Get viewport state with useViewportState (OpenSeadragon only)

Source: https://annotorious.dev/react/hooks-reference

OpenSeadragon only. Returns the annotations currently visible in the viewport, responding to zooming and panning. You can optionally debounce this hook to limit re-rendering.

```javascript
const annotations: ImageAnnotation[] = useViewportState(debounce);
```

--------------------------------

### Get Current User - JavaScript

Source: https://annotorious.dev/api-reference/user

Retrieve the currently set user object using getUser. The returned object contains user details such as name, which can be logged or used in the UI.

```javascript
const currentUser = anno.getUser();
console.log(currentUser.name); // Outputs: 'Rainer'
```

--------------------------------

### Initialize Annotorious with W3CImageFormat Adapter

Source: https://annotorious.dev/react/openseadragon-iiif

Use the `W3CImageFormat` adapter to enable W3C Web Annotation Data Model support within Annotorious and OpenSeadragon. This requires importing necessary components from `@annotorious/react`.

```jsx
import {
  Annotorious,
  OpenSeadragonAnnotator,
  OpenSeadragonViewer,
   W3CImageFormat
} from '@annotorious/react';


<Annotorious>
  <OpenSeadragonAnnotator adapter={W3CImageFormat('example.jpg')}> 
    <OpenSeadragonViewer options={OSD_OPTS} /> 
  </OpenSeadragonAnnotator>
</Annotorious>
```

--------------------------------

### Annotation Attribution Example - JSON

Source: https://annotorious.dev/api-reference/user

When a user is set, Annotorious automatically includes their data in the 'creator' field of annotation bodies and targets. This JSON structure shows an example of an annotation with user attribution embedded.

```json
{
  id: '7fb76422-3a8c-4c87-bbad-7c8bb68399a0',
  bodies: [{
    purpose: 'commenting',
    value: 'A comment!',
    creator: {
      id: 'aboutgeo',
      name: 'Rainer',
      avatar: 'https://example.com/lego-saruman.jpg'
    },
    created: 'Fri Aug 23 2024 13:02:44 GMT+0200'
  }],
  target: {
    selector: {
      type: 'RECTANGLE',
      geometry: {
        bounds: {
            minX: 272,
            minY: 169,
            maxX: 393,
            maxY: 259
        },
        x: 272,
        y: 169,
        w: 121,
        h: 90,
      }
    },
    creator: {
      id: 'aboutgeo',
      name: 'Rainer',
      avatar: 'https://example.com/lego-saruman.jpg'
    },
    created:  'Fri Aug 23 2024 13:02:44 GMT+0200'
  }
}
```

--------------------------------

### Import Annotorious Script and Stylesheet (HTML)

Source: https://annotorious.dev/installation

Include these links in your HTML's <head> to use the standard version of Annotorious without a bundler.

```html
<head>
  <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.css">
  <script
    src="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.js"></script>
</head>
```

--------------------------------

### Initialize Annotorious with W3C Adapter

Source: https://annotorious.dev/guides/data-model

Use the W3CImageFormat adapter to initialize Annotorious, allowing direct use of W3C Web annotations. This enables crosswalking between W3C and Annotorious models.

```javascript
import { createImageAnnotator, W3CImageFormat } from '@annotorious/annotorious';


import '@annotorious/annotorious/annotorious.css';


const anno = createImageAnnotator('sample-image', {
  adapter: W3CImageFormat('sample-image')
});
```

--------------------------------

### Initialize OpenSeadragon Viewer

Source: https://annotorious.dev/guides/openseadragon-iiif

Creates an OpenSeadragon viewer instance within a specified DIV element. Refer to OpenSeadragon documentation for more configuration options.

```javascript
const viewer = OpenSeadragon({
  element: document.getElementById('my-openseadragon-container'),
  tileSources: {
    type: 'image',
    url: '/images/sample-image.jpg'
  }
};
```

--------------------------------

### getAnnotationById

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Get the annotation with the specified ID.

```APIDOC
## getAnnotationById

### Description
Get the annotation with the specified ID.

### Method
`anno.getAnnotationById(id)`

### Parameters
#### Path Parameters
- **id** (string) - Required - The annotation ID.

### Returns
- **ImageAnnotation | undefined**: The annotation object if found, otherwise `undefined`.

### Request Example
```javascript
const annotation = anno.getAnnotationById('annotation-id');
```
```

--------------------------------

### Initialize Annotorious with W3CImageFormat Adapter

Source: https://annotorious.dev/api-reference/format-adapter

Initializes Annotorious with the W3CImageFormat adapter to use the W3C Web Annotation Data Model. Ensure the adapter is imported.

```javascript
import { createImageAnnotator, W3CImageFormat } from '@annotorious/annotorious';


const anno = createImageAnnotator('sample-image', {
  adapter: W3CImageFormat()
});
```

--------------------------------

### Get Selected Annotations

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Retrieve an array of annotations that are currently selected by the user. Returns an empty array if no annotations are selected.

```javascript
const selected = anno.getSelected();
```

--------------------------------

### Import Annotorious OpenSeadragon Script and Stylesheet (HTML)

Source: https://annotorious.dev/installation

Include these links in your HTML's <head> to use the OpenSeadragon version of Annotorious without a bundler.

```html
<head>
  <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@annotorious/openseadragon@latest/dist/annotorious-openseadragon.css">
  <script
    src="https://cdn.jsdelivr.net/npm/@annotorious/openseadragon@latest/dist/annotorious-openseadragon.js"></script>
</head>
```

--------------------------------

### Create OpenSeadragon Annotator with Options

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Customize the annotator's behavior during initialization by providing an options object. This allows for fine-tuning of styles and other functionalities.

```javascript
const anno = createOSDAnnotator(viewer, {
  style: { fill: #ff0000, fillOpacity: 0.4 }
});
```

--------------------------------

### Get Annotation by ID

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Retrieve a specific annotation using its unique ID. Returns the annotation object or undefined if not found.

```javascript
const annotation = anno.getAnnotationById(id);
```

--------------------------------

### CDN Import for OpenSeadragon and Annotorious

Source: https://annotorious.dev/guides/openseadragon-iiif

Includes OpenSeadragon and Annotorious via CDN for use without a build system. The `createOSDAnnotator` function is available globally as `AnnotoriousOSD`.

```html
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/openseadragon@latest/build/openseadragon/openseadragon.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@annotorious/openseadragon@latest/dist/annotorious-openseadragon.js"></script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@annotorious/openseadragon@latest/dist/annotorious-openseadragon.css">
  </head>
  <body>
    <div
    <script>
      window.onload = function() {
        var viewer = OpenSeadragon({
          element: document.getElementById('my-openseadragon-container'),
          tileSources: {
            type: 'image',
            url: '/images/sample-image.jpg'
          }
        };


        var anno = AnnotoriousOSD.createOSDAnnotator(viewer);
      }
    </script>
  </body>
</html>
```

--------------------------------

### Get current annotator user with useAnnotatorUser

Source: https://annotorious.dev/react/hooks-reference

Returns the current annotator user set via the `anno.setUser()` method, if any. The return type is `User`.

```javascript
const user: User = useAnnotatorUser();
```

--------------------------------

### Create Annotator with Options

Source: https://annotorious.dev/guides/openseadragon-iiif

Initializes the Annotorious annotator with custom options, such as enabling drawing and defining style properties for annotations.

```javascript
const anno = createOSDAnnotator(viewer, {
  drawingEnabled: true,
  style: {
   fill: '#ff0000',
   fillOpacity: 0.25
  }
});
```

--------------------------------

### Create Annotator Instance

Source: https://annotorious.dev/guides/openseadragon-iiif

Initializes the Annotorious annotator on an existing OpenSeadragon viewer instance.

```javascript
const anno = createOSDAnnotator(viewer);
```

--------------------------------

### Dynamic Styling with Functions

Source: https://annotorious.dev/api-reference/drawing-style

The `setStyle` method also accepts a function that returns a style object. This function receives the `ImageAnnotation` and `AnnotationState` as input, allowing for dynamic styling based on annotation data.

```APIDOC
## Dynamic Styling Function

### Description
Allows for dynamic styling of annotations based on their data and state.

### Method Signature
`setStyle((annotation: ImageAnnotation, state: AnnotationState) => StyleProperties)`

### Parameters
- **annotation** (ImageAnnotation) - The current image annotation.
- **state** (AnnotationState) - The current state of the annotation (e.g., selected).

### Returns
- **StyleProperties** - An object defining the style for the annotation.

### Request Example
```javascript
anno.setStyle((annotation, state) => {
  const label = annotation.bodies.find(b => b.purpose === 'tagging')?.value;

  // If the annotation has an 'important' label, make it red
  const color = label === 'important' ? '#ff0000' : '#ffffff';

  const opacity = state.selected ? 0.9 : 0.25;

  return {
    fill: color,
    fillOpacity: opacity,
    stroke: color,
    strokeOpacity: 1
  };
});
```
```

--------------------------------

### OpenSeadragonAnnotator Initialization

Source: https://annotorious.dev/api-reference/openseadragon-annotator

The main entry point into the Annotorious API. An object of this type is returned when you call the `createOSDAnnotator` method. You can provide an options object to customize the annotator behavior.

```APIDOC
## createOSDAnnotator

### Description
Creates an instance of the OpenSeadragonAnnotator.

### Method
`createOSDAnnotator(viewer, options?)`

### Parameters
#### Path Parameters
- **viewer** (OpenSeadragon.Viewer) - Required - The OpenSeadragon viewer instance.
- **options** (object) - Optional - Configuration options for the annotator.

### Init Options
#### Property
- **adapter** (FormatAdapter) - Optional - An optional format crosswalk adapter.
- **autoSave** (boolean) - Optional - Default: `false`. When set to `true`, annotation update events trigger instantly when the user is idle. If `false`, update events only trigger after the user actively de-selects the annotation after editing.
- **drawingEnabled** (boolean) - Optional - Default: `false`. Enables or disables drawing functionality.
- **drawingMode** (string) - Optional - Default: determined by device type ('click' for desktop, 'drag' for touch). Determines how drawing is initiated.
- **userSelectAction** (UserSelectActionExpression) - Optional - Default: `"EDIT"`. Action to perform on user selection.
- **style** (DrawingStyleExpression) - Optional - Annotation style.

### Request Example
```javascript
import { createOSDAnnotator } from '@annotorious/openseadragon';

const viewer = new OpenSeadragon.Viewer(...);
const anno = createOSDAnnotator(viewer);

// With options
const annoWithOptions = createOSDAnnotator(viewer, {
  style: { fill: '#ff0000', fillOpacity: 0.4 }
});
```
```

--------------------------------

### Configure Annotation Selection Mode

Source: https://annotorious.dev/api-reference/selection

Set the initial behavior for annotation selection. Use 'SELECT' to allow selection and trigger events without making the annotation editable.

```javascript
const anno = createImageAnnotator('sample-image', {
  userSelectAction: 'SELECT' // Allow selection, but don't make editable
});
```

--------------------------------

### W3C Web Annotation Data Model Adapter

Source: https://annotorious.dev/react/image-annotation

Integrate support for the W3C Web Annotation Data Model using the `adapter` prop on ImageAnnotator. This enables interoperability with other systems using this standard.

```javascript
import { Annotorious, ImageAnnotator, W3CImageFormat } from '@annotorious/react';
```

```jsx
<Annotorious>
  <ImageAnnotator adapter={W3CImageFormat('example.jpg')}> 
    <img src="example.jpg" />
  </ImageAnnotator>
</Annotorious>
```

--------------------------------

### ImageAnnotator Initialization

Source: https://annotorious.dev/api-reference/image-annotator

The ImageAnnotator is the main entry point into the Annotorious API. It is created using the `createImageAnnotator` method, optionally accepting an image element or selector and an options object for customization.

```APIDOC
## createImageAnnotator

### Description
Creates a new ImageAnnotator instance for a given image element or selector.

### Parameters
#### Argument 1: `element`
- **element** (string | HTMLImageElement | HTMLDivElement) - Required - The image element or a CSS selector for the image.

#### Argument 2: `options`
- **options** (object) - Optional - Configuration options for the annotator.
  - **adapter** (FormatAdapter) - An optional format crosswalk adapter.
  - **autoSave** (boolean) - Default: `false` - If `true`, annotation updates are saved instantly when the user is idle.
  - **drawingEnabled** (boolean) - Default: `true` - Enables or disables drawing functionality.
  - **drawingMode** (string) - Default: `"drag"` - Determines how drawing is initiated (`"click"` or `"drag"`).
  - **userSelectAction** (UserSelectActionExpression) - Default: `"EDIT"` - Action to perform on user selection.
  - **style** (DrawingStyleExpression) - Default: `Annotation style` - Style for annotations.

### Request Example
```javascript
import { createImageAnnotator } from '@annotorious/annotorious';

// Basic initialization
const anno = createImageAnnotator('sample-image');

// Initialization with options
const annoWithOptions = createImageAnnotator('sample-image', {
  style: { fill: '#ff0000', fillOpacity: 0.4 }
});
```
```

--------------------------------

### Get current selection state with useSelection

Source: https://annotorious.dev/react/hooks-reference

Returns the current selection state object and, optionally, the associated pointer event. The selection object contains the selected annotations and an `editable` flag.

```javascript
const { selected, event } = useSelection();
```

--------------------------------

### Editable Comment Popup in React

Source: https://annotorious.dev/react/custom-popups

An advanced example of a custom popup that allows users to view and edit comments associated with an annotation. It utilizes the `onCreateBody` and `onUpdateBody` props of ImageAnnotationPopup to manage comment bodies.

```jsx
import { useState, useEffect } from 'react';
import {
  Annotorious,
  ImageAnnotationPopup,
  ImageAnnotator,
  AnnotationBody
} from '@annotorious/react';


const CommentPopup = (props: PopupProps) => {


  const { annotation, onCreateBody, onUpdateBody } = props;


  const [comment, setComment] = useState('');


  useEffect(() => {
    const commentBody = annotation.bodies.find(body => body.purpose === 'commenting');
    setComment(commentBody ? commentBody.value : '');
  }, [annotation.bodies]);


  const onSave = () => {
    const updated = {
      purpose: 'commenting',
      value: comment
    };


    const commentBody = annotation.bodies.find(body => body.purpose === 'commenting');
    if (commentBody) {
      onUpdateBody(commentBody, updated);
    } else {
      onCreateBody(updated);
    }
  };


  return (
    <div>
      <textarea
        value={comment}
        onChange={e => setComment(e.target.value)} />


      <button onClick={onSave}>Save</button>
    </div>
  )


}


export default function App() {
  return (
    <Annotorious>
      <ImageAnnotator>
        <img src="example.jpg" />
      </ImageAnnotator>


      <ImageAnnotationPopup popup={(props: PopupProps) => (
        <CommentPopup {...props} />
      )} />
    </Annotorious>
  );
}
```

--------------------------------

### useAnnotations

Source: https://annotorious.dev/react/hooks-reference

Returns the live annotation state. To limit re-rendering, you can optionally debounce the state updates.

```APIDOC
## useAnnotations

### Description
Returns the live annotation state. To limit re-rendering, you can optionally debounce the state updates.

### Parameters
#### Query Parameters
- **debounce** (number) - Optional - Debounce the state update by the given number of milliseconds. Defaults to 0.

### Returns
- **annotations** (Array<ImageAnnotation>) - An array of ImageAnnotation objects.
```

--------------------------------

### on

Source: https://annotorious.dev/api-reference/image-annotator

Adds a listener for lifecycle events emitted by the Image Annotator.

```APIDOC
## on

### Description
Adds a lifecycle event listener to the Image Annotator.

### Method Signature
`anno.on(event, callback)`

### Parameters
#### Argument
- **event** (string) - Required - The name of the event to listen for.
- **callback** (function) - Required - The function to execute when the event is triggered.
```

--------------------------------

### OpenSeadragon Viewer with IIIF Info URL

Source: https://annotorious.dev/guides/openseadragon-iiif

Configures an OpenSeadragon viewer to display a IIIF image by providing the URL to its `info.json` file.

```javascript
const viewer = OpenSeadragon({
  element: document.getElementById('my-openseadragon-container'),
  tileSources: https://iiif.princeton.edu/loris/pudl0001%2F4609321%2Fs42%2F00000001.jp2/info.json
});
```

--------------------------------

### OpenSeadragonViewer Configuration

Source: https://annotorious.dev/react/component-reference

Integrates OpenSeadragonViewer within Annotorious, specifying viewer options for high-resolution image display.

```jsx
import { Annotorious, OpenSeadragonViewer } from '@annotorious/react';


const OSD_OPTIONS =  {
  tileSources: {
    type: 'image',
    url: '/images/sample-image.jpg'
  }
};


export default function App() {
  return (
    <Annotorious>
      <OpenSeadragonViewer
        className="openseadragon"
        options={OSD_OPTIONS} />
    </Annotorious>
  );
}
```

--------------------------------

### Set Current User for Attribution

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Sets the current user, which Annotorious uses for attribution data in annotations. Pass `undefined` to clear the current user. Note: The example shows `setStyle()` which appears to be a typo and should likely be `setUser()` based on the function name.

```javascript
anno.setUser(user);
```

```javascript
// Clear the current user
anno.setStyle();
```

--------------------------------

### useViewportState

Source: https://annotorious.dev/react/hooks-reference

OpenSeadragon only. Returns the annotations currently visible in the viewport.

```APIDOC
## useViewportState

### Description
**OpenSeadragon only.** Returns the annotations currently visible in the viewport. This hook is only available with OpenSeadragon, and will respond to zooming and panning of the OpenSeadragon image. You can optionally debounce this hook, to limit re-rendering.

### Parameters
#### Query Parameters
- **debounce** (number) - Optional - Debounce the state update by the given number of milliseconds. Defaults to 0.

### Returns
- **annotations** (Array<ImageAnnotation>) - An array of ImageAnnotation objects visible in the viewport.
```

--------------------------------

### Fit Viewer with Constraints

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Similar to `fitBounds`, this method uses OpenSeadragon's `fitBoundsWithConstraints` to adjust the viewport. It accepts an annotation or ID and optional fitting options.

```javascript
anno.fitBoundsWithConstraints(arg, opts?);
```

--------------------------------

### Create OpenSeadragon Annotator

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Instantiate the OpenSeadragonAnnotator. This is the primary object for interacting with the Annotorious API in an OpenSeadragon context. Ensure the OpenSeadragon viewer instance is available.

```javascript
import { createOSDAnnotator } from '@annotorious/openseadragon';


// ...


const anno = createOSDAnnotator(viewer);
```

--------------------------------

### Import Annotorious Components

Source: https://annotorious.dev/react/openseadragon-iiif

Import the necessary components from the '@annotorious/react' library for integrating Annotorious with OpenSeadragon.

```jsx
import { Annotorious, OpenSeadragonAnnotator, OpenSeadragonViewer } from '@annotorious/react';
```

--------------------------------

### fitBoundsWithConstraints

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Similar to `fitBounds`, but using the OpenSeadragon fitBoundsWithConstraints method underneath.

```APIDOC
## fitBoundsWithConstraints

### Description
Similar to `fitBounds`, but using the OpenSeadragon `fitBoundsWithConstraints` method underneath.

### Method
`anno.fitBoundsWithConstraints(arg, opts?)`

### Parameters
#### Path Parameters
- **arg** (ImageAnnotation | string) - Required - The annotation or annotation ID.
- **opts** (FitBoundsOptions) - Optional - Additional options. See `fitBounds` for details.

### Request Example
```javascript
anno.fitBoundsWithConstraints(annotation);
```
```

--------------------------------

### Basic OpenSeadragon Annotation Popup

Source: https://annotorious.dev/react/custom-popups

Demonstrates how to implement custom popups for annotations within an OpenSeadragon viewer using the OpenSeadragonAnnotationPopup component. This component correctly handles popup positioning during viewer zoom and pan operations.

```jsx
import {
  Annotorious,
  OpenSeadragonAnnotationPopup,
  OpenSeadragonAnnotator,
  OpenSeadragonViewer
} from '@annotorious/react';


import './App.css';
import '@annotorious/react/annotorious-react.css';


export default function App() {
  return (
    <Annotorious>
      <OpenSeadragonAnnotator>
        <OpenSeadragonViewer options={{
          tileSources: {
            type: 'image',
            url: '/images/sample-image.jpg'
          }
        }} />


        <OpenSeadragonAnnotationPopup
          popup={(props: PopupProps) => (
            <div>
              Hello World
            </div>
          )} />
      </OpenSeadragonAnnotator>
    </Annotorious>
  );
}
```

--------------------------------

### Load Annotations from URL

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Loads annotations from a JSON file at a specified URL. The optional `replace` parameter determines if new annotations should replace existing ones or be added. Returns a promise of the fetched annotations.

```javascript
const loaded = await anno.loadAnnotations(url, replace = false)
```

--------------------------------

### useAnnotator

Source: https://annotorious.dev/react/hooks-reference

Provides access to the vanilla ImageAnnotator or OpenSeadragonAnnotator instance.

```APIDOC
## useAnnotator

### Description
Provides access to the vanilla ImageAnnotator or OpenSeadragonAnnotator instance.

### Parameters
None

### Returns
- **annotator** (ImageAnnotator | OpenSeadragonAnnotator) - The annotator instance.

### Example
```javascript
const imageAnnotator = useAnnotator<AnnotoriousImageAnnotator>();
const osdAnnotator = useAnnotator<AnnotoriousOpenSeadragonAnnotator>();
```
```

--------------------------------

### HTML with CDN for Image Annotation

Source: https://annotorious.dev/

Integrate Annotorious into an HTML page using CDN links for the CSS and JavaScript files. The annotator is initialized on window load.

```html
<html>
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.css">
    <script src="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.js"></script>
  </head>
  <body>
    <img id="my-image" src="my-image.jpg" />

    <script>
      window.onload = function() {
        var anno = Annotorious.createImageAnnotator('my-image');
      }
    </script>
  </body>
</html>
```

--------------------------------

### Load Existing Annotations

Source: https://annotorious.dev/guides/annotating-images

Load a set of annotations from a JSON file into the annotator. This is useful for displaying pre-existing annotations on an image.

```javascript
anno.loadAnnotations('./annotations.json');
```

--------------------------------

### List Available Drawing Tools

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Retrieves a list of all available drawing tool names. By default, this includes 'rectangle' and 'polygon'. Additional tools may be available via plugins.

```javascript
const tools = anno.listDrawingTools();
```

--------------------------------

### createAnnotation

Source: https://annotorious.dev/api-reference/events

Fired after a new annotation is created.

```APIDOC
## createAnnotation

### Description
Fired after a new annotation is created.

### Arguments
- **annotation** (ImageAnnotation) - The new annotation.
```

--------------------------------

### Create ImageAnnotator Instance

Source: https://annotorious.dev/api-reference/image-annotator

Instantiate the ImageAnnotator. This is the primary object for interacting with Annotorious. It requires a selector for the target image.

```javascript
import { createImageAnnotator } from '@annotorious/annotorious';


const anno = createImageAnnotator('sample-image');
```

--------------------------------

### loadAnnotations

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Loads annotations from a JSON file at a specified URL. It returns a promise that resolves with the fetched annotations. The `replace` parameter determines whether to replace existing annotations or merge them.

```APIDOC
## loadAnnotations

### Description
Loads annotations from a JSON file at a given URL. The method returns a promise of the fetched annotations, in case you want to perform an action after they have loaded. The optional `replace` parameter controls whether the new annotations should replace the current annotations, erasing all existing ones, or get added to them.

### Method Signature
```javascript
const loaded = await anno.loadAnnotations(url, replace = false)
```

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to the JSON annotation file.
- **replace** (boolean) - Optional - Default: `false` - If `true`, all current annotations on the image will be cleared.
```

--------------------------------

### redo

Source: https://annotorious.dev/api-reference/image-annotator

Programmatically redoes the last undone user action.

```APIDOC
## redo

### Description
Programmatically redo the last undone user action.

### Method
`anno.redo()`

### Request Example
```javascript
anno.redo();
```
```

--------------------------------

### redo

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Programmatically redoes the last undone user action.

```APIDOC
## redo

### Description
Programmatically redo the last undone user action.

### Method Signature
```javascript
anno.redo();
```
```

--------------------------------

### getAnnotations

Source: https://annotorious.dev/api-reference/image-annotator

Retrieves all annotations currently present on the image.

```APIDOC
## getAnnotations

### Description
Get all annotations on the image.

### Method
`anno.getAnnotations()`

### Returns
- **Array<ImageAnnotation>**: An array of all annotation objects.

### Request Example
```javascript
const all = anno.getAnnotations();
```
```

--------------------------------

### Import Annotorious CSS

Source: https://annotorious.dev/guides/annotating-images

Crucial step to import the Annotorious CSS stylesheet for proper styling of annotations and the user interface.

```css
import '@annotorious/annotorious/annotorious.css';
```

--------------------------------

### Import Annotorious CSS

Source: https://annotorious.dev/guides/openseadragon-iiif

Imports the required CSS stylesheet for Annotorious to function correctly with OpenSeadragon.

```css
import '@annotorious/openseadragon/annotorious-openseadragon.css';
```

--------------------------------

### loadAnnotations

Source: https://annotorious.dev/api-reference/image-annotator

Loads annotations from a JSON file at a specified URL. Optionally replaces existing annotations.

```APIDOC
## loadAnnotations

### Description
Load annotations from a JSON file at a given URL. The method returns a promise of the fetched annotations, in case you want to perform an action after they have loaded. The optional `replace` parameter controls whether the new annotations should replace the current annotations, erasing all existing ones, or get added to them.

### Method
`await anno.loadAnnotations(url, replace = false)`

### Parameters
#### Argument 1: `url`
- **url** (string) - Required - The URL to the JSON annotation file.

#### Argument 2: `replace`
- **replace** (boolean) - Optional - Default: `false` - If `true`, all current annotations on the image will be cleared before loading new ones.

### Returns
- **Promise<ImageAnnotation[]>**: A promise that resolves with an array of the loaded annotations.

### Request Example
```javascript
const loaded = await anno.loadAnnotations('/path/to/annotations.json', true);
```
```

--------------------------------

### Import Annotorious CSS

Source: https://annotorious.dev/react/image-annotation

Import the base CSS styles for Annotorious to ensure proper rendering of annotations.

```javascript
import '@annotorious/react/annotorious-react.css';
```

--------------------------------

### viewportIntersect

Source: https://annotorious.dev/api-reference/events

**OpenSeadragon only.** Fired when the set of annotations visible in the current viewport changes. This event is only available on the OpenSeadragonAnnotator and will respond to zooming and panning of the OpenSeadragon image.

```APIDOC
## viewportIntersect

### Description
**OpenSeadragon only.** Fired when the set of annotations visible in the current viewport changes. This event is only available on the OpenSeadragonAnnotator and will respond to zooming and panning of the OpenSeadragon image.

### Arguments
- **annotations** (Array<ImageAnnotation>) - The annotations in the current viewport.
```

--------------------------------

### getSelected

Source: https://annotorious.dev/api-reference/image-annotator

Retrieves the currently selected annotations.

```APIDOC
## getSelected

### Description
Get the currently selected annotations.

### Method
`anno.getSelected()`

### Returns
- **Array<ImageAnnotation>**: An array of the currently selected annotation objects.

### Request Example
```javascript
const selected = anno.getSelected();
```
```

--------------------------------

### Set User Information

Source: https://annotorious.dev/api-reference/image-annotator

Sets the current user for attribution data. Call without arguments to clear the current user.

```javascript
anno.setUser(user);

// Clear the current user
ano.setUser();
```

--------------------------------

### useSelection

Source: https://annotorious.dev/react/hooks-reference

Returns the current selection state object and, optionally, the associated pointer event.

```APIDOC
## useSelection

### Description
Returns the current selection state object and, optionally, the associated pointer event.

### Parameters
None

### Returns
- **selected** (Array<Selection>) - The selected annotations.
- **event** (PointerEvent) - Optional. The associated user pointer event.

### Selection Object
- **annotation** (ImageAnnotation) - The selected annotation.
- **editable** (boolean) - Optional. Whether the annotation is currently editable.
```

--------------------------------

### Fit Viewer to Annotation Bounds

Source: https://annotorious.dev/api-reference/openseadragon-annotator

Adjust the OpenSeadragon viewer's viewport to fit the bounding box of a specified annotation. Options can control immediate fitting and padding.

```javascript
anno.fitBounds(arg, opts?);
```

```javascript
anno.fitBounds(arg, { immediately: true, padding: 20 });
```