@annotorious/annotorious 3.0.0-rc.1

package/src/Annotorious.ts

@@ -0,0 +1,158 @@
+import type { SvelteComponent } from 'svelte';
+import type { Annotator, DrawingStyle, User } from '@annotorious/core';
+import { createAnonymousGuest, createBaseAnnotator, createLifecyleObserver } from '@annotorious/core';
+import { registerEditor } from './annotation/editors';
+import { getTool, registerTool, listDrawingTools, type DrawingTool } from './annotation/tools';
+import { SVGAnnotationLayer } from './annotation';
+import type { DrawingToolOpts, SVGAnnotationLayerPointerEvent } from './annotation';
+import type { ImageAnnotation, ShapeType } from './model';
+import { createSvelteImageAnnotatorState } from './state';
+import { setTheme } from './themes';
+import { fillDefaults } from './AnnotoriousOpts';
+import type { AnnotoriousOpts } from './AnnotoriousOpts';
+
+import './Annotorious.css';
+import './themes/dark/index.css';
+import './themes/light/index.css';
+
+export interface ImageAnnotator<E extends unknown = ImageAnnotation> extends Annotator<ImageAnnotation, E> { 
+
+  listDrawingTools(): string[];
+
+  registerDrawingTool(name: string, tool: typeof SvelteComponent, opts?: DrawingToolOpts): void;
+
+  registerShapeEditor(shapeType: ShapeType, editor: typeof SvelteComponent): void;
+
+  setDrawingTool(tool: DrawingTool): void; 
+
+  setDrawingEnabled(enabled: boolean): void;
+
+}
+
+export const createImageAnnotator = <E extends unknown = ImageAnnotation>(
+  image: string | HTMLImageElement | HTMLCanvasElement, 
+  options: AnnotoriousOpts<ImageAnnotation, E> = {}
+): ImageAnnotator<E> => {
+
+  if (!image)
+    throw 'Missing argument: image';
+
+  const img = (typeof image === 'string' ? 
+    document.getElementById(image) : image) as HTMLImageElement | HTMLCanvasElement;
+
+  const opts = fillDefaults<ImageAnnotation, E>(options);
+
+  const state = createSvelteImageAnnotatorState(opts);
+
+  const { hover, selection, store } = state;
+
+  const lifecycle = createLifecyleObserver<ImageAnnotation, E>(
+    store, selection, hover, undefined, opts.adapter, opts.autoSave);
+
+  let currentUser: User = createAnonymousGuest();
+
+  let style = opts.style;
+
+  // We'll wrap the image in a container DIV.
+  const container = document.createElement('DIV');
+  container.style.position = 'relative';
+  container.style.display = 'inline-block';
+
+  // Wrapper div has unwanted margin at the bottom otherwise!
+  img.style.display = 'block';
+
+  img.parentNode.insertBefore(container, img);
+  container.appendChild(img);
+
+  setTheme(img, container);
+
+  const annotationLayer = new SVGAnnotationLayer({
+    target: container,
+    props: { 
+      drawingEnabled: opts.drawingEnabled, 
+      image: img, 
+      preferredDrawingMode: opts.drawingMode,
+      state, 
+      style, 
+      user: currentUser
+    }
+  });
+
+  annotationLayer.$on('click', (evt: CustomEvent<SVGAnnotationLayerPointerEvent>) => {
+    const { originalEvent, annotation } = evt.detail;
+    if (annotation)
+      selection.clickSelect(annotation.id, originalEvent);
+    else if (!selection.isEmpty())
+      selection.clear();
+  });
+
+  /*************************/
+  /*      External API     */
+  /******++++++*************/
+
+  // Most of the external API functions are covered in the base annotator
+  const base = createBaseAnnotator<ImageAnnotation, E>(store, opts.adapter);
+
+  const setStyle = (drawingStyle: DrawingStyle | ((annotation: ImageAnnotation) => DrawingStyle) | undefined) => {
+    style = drawingStyle;
+    annotationLayer.$set({ style });
+  }
+
+  const destroy = () => {
+    // Destroy Svelte annotation layer
+    annotationLayer.$destroy();
+
+    // Unwrap the image
+    container.parentNode.insertBefore(img, container);
+    container.parentNode.removeChild(container);
+  }
+
+  const getUser = () => currentUser;
+
+  const registerDrawingTool = (name: string, tool: typeof SvelteComponent, opts?: DrawingToolOpts) =>
+    registerTool(name, tool, opts);
+
+  const registerShapeEditor = (shapeType: ShapeType, editor: typeof SvelteComponent) =>
+    registerEditor(shapeType, editor);
+
+  const setDrawingTool = (t: DrawingTool) => {
+    const { tool, opts } = getTool(t);
+    // @ts-ignore
+    annotationLayer.$set({ tool, opts })
+  }
+
+  const setDrawingEnabled = (enabled: boolean) =>
+    annotationLayer.$set({ drawingEnabled: enabled });
+
+  const setSelected = (arg?: string | string[]) => {
+    if (arg) {
+      selection.setSelected(arg);
+    } else {
+      selection.clear();
+    }
+  }
+
+  const setUser = (user: User) => {
+    currentUser = user;
+    annotationLayer.$set({ user });
+  }
+
+  return {
+    ...base,
+    get style() { return style },
+    set style(s: DrawingStyle | ((annotation: ImageAnnotation) => DrawingStyle) | undefined) { setStyle(s) },
+    destroy,
+    getUser,
+    listDrawingTools,
+    on: lifecycle.on,
+    off: lifecycle.off,
+    registerDrawingTool,
+    registerShapeEditor,
+    setDrawingEnabled,
+    setDrawingTool,
+    setSelected,
+    setUser,
+    state
+  }
+
+}

package/src/AnnotoriousOpts.ts

@@ -0,0 +1,40 @@
+import { PointerSelectAction } from '@annotorious/core';
+import type { Annotation, DrawingStyle, FormatAdapter } from '@annotorious/core';
+import type { ImageAnnotation } from './model';
+
+export interface AnnotoriousOpts<I extends Annotation = ImageAnnotation, E extends unknown = ImageAnnotation> {
+
+  adapter?: FormatAdapter<I, E>;
+
+  autoSave?: boolean;
+
+  drawingEnabled?: boolean;
+
+  // 'click': starts on single click, user cannot select unless drawingEnabled = false
+  // 'drag': starts drawing on drag, single click always selects
+  drawingMode?: DrawingMode;
+
+  pointerSelectAction?: PointerSelectAction | ((a: I) => PointerSelectAction);
+
+  style?: DrawingStyle | ((annotation: I) => DrawingStyle);
+
+}
+
+export type DrawingMode = 'click' | 'drag';
+
+export const fillDefaults = <I extends ImageAnnotation = ImageAnnotation, E extends unknown = ImageAnnotation> (
+  opts: AnnotoriousOpts<I, E>
+): AnnotoriousOpts<I, E> => {
+
+  return {
+    ...opts,
+    drawingEnabled: opts.drawingEnabled === undefined ? true : opts.drawingEnabled,
+    drawingMode: opts.drawingMode || 'drag',
+    pointerSelectAction: opts.pointerSelectAction || PointerSelectAction.EDIT
+  };
+
+};
+
+
+
+

package/src/annotation/SVGAnnotationLayer.svelte

@@ -0,0 +1,169 @@
+<script type="ts">
+  import { onMount, type SvelteComponent } from 'svelte';
+  import { v4 as uuidv4 } from 'uuid';
+  import type { DrawingStyle, StoreChangeEvent, User } from '@annotorious/core';
+  import { ShapeType } from '../model';
+  import type { ImageAnnotation, Shape} from '../model';
+  import { getEditor, EditorMount } from './editors';
+  import { Ellipse, Polygon, Rectangle} from './shapes';
+  import { getTool, ToolMount } from './tools';
+  import { enableResponsive } from './utils';
+  import { createSVGTransform } from './Transform';
+  import { addEventListeners } from './SVGAnnotationLayerPointerEvent';
+  import type { SvelteImageAnnotatorState } from 'src/state';
+  import type { DrawingMode } from 'src/AnnotoriousOpts';
+
+  /** Props **/
+  export let drawingEnabled: boolean;
+  export let image: HTMLImageElement | HTMLCanvasElement;
+  export let preferredDrawingMode: DrawingMode;
+  export let state: SvelteImageAnnotatorState;
+  export let style: DrawingStyle | ((annotation: ImageAnnotation) => DrawingStyle) = undefined;
+  export let { tool, opts } = getTool('rectangle');
+  export let user: User;
+
+  $: drawingMode = opts?.drawingMode || preferredDrawingMode;
+
+  /** Drawing tool layer **/
+  let drawingEl: SVGGElement;
+
+  /** Responsive scaling **/
+  let svgEl: SVGSVGElement;
+    
+  let scale: ReturnType<typeof enableResponsive>;
+
+  onMount(() => scale = enableResponsive(image, svgEl));
+
+  $: transform = createSVGTransform(svgEl);
+
+  /** Selection tracking */
+  const { selection, store } = state;
+
+  $: ({ onPointerDown, onPointerUp } = addEventListeners(svgEl, store));
+
+  let storeObserver = null;
+
+  let editableAnnotations: ImageAnnotation[] = null;
+
+  $: isEditable = (a: ImageAnnotation) => $selection.selected.find(s => s.id === a.id && s.editable);
+
+  $: trackSelection($selection.selected);
+
+  const trackSelection = (selected: { id: string, editable?: boolean }[]) => {
+    store.unobserve(storeObserver);
+
+    // Track only editable annotations
+    const editableIds = 
+      selected.filter(({ editable }) => editable).map(({ id }) => id);
+
+    if (editableIds.length > 0) {
+      // Resolve selected IDs from the store
+      editableAnnotations = editableIds.map(id => store.getAnnotation(id));
+
+      // Track updates on the editable annotations
+      storeObserver = (event: StoreChangeEvent<ImageAnnotation>) => {
+        const { updated } = event.changes;
+        editableAnnotations = updated.map(change => change.newValue);
+      }   
+      
+      store.observe(storeObserver, { annotations: editableIds });
+    } else {
+      editableAnnotations = null;
+    }
+  }
+
+  const onSelectionCreated = <T extends Shape>(evt: CustomEvent<T>) => {
+    const id = uuidv4();
+
+    const annotation: ImageAnnotation = {
+      id,
+      bodies: [],
+      target: {
+        annotation: id,
+        selector: evt.detail,
+        creator: user,
+        created: new Date()
+      }
+    };
+
+    store.addAnnotation(annotation);
+
+    selection.setSelected(annotation.id);
+  }
+
+  const onChangeSelected = (annotation: ImageAnnotation) => (event: CustomEvent<Shape>) => {  
+    const { target } = annotation;
+
+    // We don't consider a shape edit an 'update' if it happens within 10mins
+    const GRACE_PERIOD = 10 * 60 * 1000;
+
+    const isUpdate = 
+      target.creator?.id !== user.id ||
+      !target.created ||
+      new Date().getTime() - target.created.getTime() > GRACE_PERIOD;
+
+    store.updateTarget({
+      ...target,
+      selector: event.detail,
+      created: isUpdate ? target.created : new Date(),
+      updated: isUpdate ? new Date() : null,
+      updatedBy: isUpdate ? user : null
+    });
+  }
+</script>
+
+<svg
+  bind:this={svgEl}
+  class="a9s-annotationlayer"
+  class:drawing={tool}
+  on:pointerup={onPointerUp}
+  on:pointerdown={onPointerDown}>
+  
+  <g>
+    {#each $store as annotation}
+      {#if !isEditable(annotation)}
+        {@const selector = annotation.target.selector}
+        {#key annotation.id}
+          {#if (selector.type === ShapeType.ELLIPSE)}
+            <Ellipse annotation={annotation} geom={selector.geometry} style={style} />
+          {:else if (selector.type === ShapeType.RECTANGLE)}
+            <Rectangle annotation={annotation} geom={selector.geometry} style={style} />
+          {:else if (selector.type === ShapeType.POLYGON)}
+            <Polygon annotation={annotation} geom={selector.geometry} style={style} />
+          {/if}
+        {/key}
+      {/if}
+    {/each}
+  </g>
+
+  <g 
+    bind:this={drawingEl}
+    class="drawing" >
+    {#if drawingEl}
+      {#if editableAnnotations}
+        {#each editableAnnotations as editable}
+          {#key editable.id}
+            <EditorMount
+              target={drawingEl}
+              editor={getEditor(editable.target.selector)}
+              annotation={editable}
+              style={style}
+              transform={transform}
+              viewportScale={$scale}
+              on:change={onChangeSelected(editable)} />
+          {/key}
+        {/each}
+      {:else if (tool && drawingEnabled)} 
+        {#key tool}
+          <ToolMount 
+            target={drawingEl}
+            tool={tool}
+            drawingMode={drawingMode}
+            transform={transform}
+            viewportScale={$scale}
+            on:create={onSelectionCreated} />
+        {/key}
+      {/if}
+    {/if}
+  </g>
+</svg>

package/src/annotation/SVGAnnotationLayerPointerEvent.ts

@@ -0,0 +1,55 @@
+import { createEventDispatcher } from 'svelte';
+import type { SvelteImageAnnotationStore } from '../state';
+import type { ImageAnnotation } from '../model';
+import { isTouch } from './utils';
+
+export interface SVGAnnotationLayerPointerEvent {
+    
+  originalEvent: PointerEvent;
+  
+  annotation?: ImageAnnotation;
+
+}
+
+// Maximum amount of ms between pointer down and up to make it a click
+const MAX_CLICK_DURATION = 250;
+
+export const addEventListeners = (svg: SVGSVGElement, store: SvelteImageAnnotationStore) => {
+  const dispatch = createEventDispatcher<{ click: SVGAnnotationLayerPointerEvent}>();
+
+  let lastPointerDown: number;
+
+  const onPointerDown = () =>
+    lastPointerDown = performance.now();
+
+  const onPointerUp = (evt: PointerEvent) => {
+    const duration = performance.now() - lastPointerDown;
+
+    if (duration < MAX_CLICK_DURATION) {
+      const { x, y } = getSVGPoint(evt, svg);
+
+      const annotation = store.getAt(x, y);
+
+      if (annotation)
+        dispatch('click', { originalEvent: evt, annotation });
+      else
+        dispatch('click', { originalEvent: evt });
+    }
+  }
+
+  return { onPointerDown, onPointerUp };
+}
+
+const getSVGPoint = (evt: PointerEvent, svg: SVGSVGElement) => {
+  const pt = svg.createSVGPoint();
+  const bbox = svg.getBoundingClientRect();
+
+  const x = evt.clientX - bbox.x;
+  const y = evt.clientY - bbox.y;
+
+  const { left, top } = svg.getBoundingClientRect();
+  pt.x = x + left;
+  pt.y = y + top;
+
+  return pt.matrixTransform(svg.getScreenCTM().inverse());
+}

package/src/annotation/Transform.ts

@@ -0,0 +1,24 @@
+export interface Transform { 
+
+  elementToImage: (offsetX: number, offsetY: number) => [ number, number ] 
+
+}
+
+export const IdentityTransform: Transform = {
+
+  elementToImage:  (offsetX: number, offsetY: number) => ([ offsetX, offsetY ])
+
+}
+
+export const createSVGTransform = (svg: SVGSVGElement): Transform => ({
+
+  elementToImage: (offsetX: number, offsetY: number) => {
+    const pt = svg.createSVGPoint();
+    pt.x = offsetX;
+    pt.y = offsetY;
+  
+    const { x, y } = pt.matrixTransform(svg.getCTM().inverse());
+    return [x, y];
+  }
+
+});

package/src/annotation/editors/Editor.svelte

@@ -0,0 +1,61 @@
+<script type="ts">
+  import { createEventDispatcher } from 'svelte';
+  import type { Shape } from '../../model';
+  import type { Handle } from './Handle';
+  import type { Transform } from '../Transform';
+
+  const dispatch = createEventDispatcher<{ grab: undefined, release: undefined, change: Shape }>();
+
+  /** Props */
+  export let shape: Shape;
+  export let editor: (shape: Shape, handle: Handle, delta: [number, number]) => Shape;
+  export let transform: Transform;
+
+  let grabbedHandle: Handle = null;
+
+  let origin: [number, number];
+
+  let initialShape: Shape = null;
+
+  const onGrab = (handle: Handle) => (evt: PointerEvent) => {
+    grabbedHandle = handle;
+    origin = transform.elementToImage(evt.offsetX, evt.offsetY);
+    initialShape = shape;
+
+    const target = evt.target as Element;
+    target.setPointerCapture(evt.pointerId);
+
+    dispatch('grab');
+  }
+
+  const onPointerMove = (evt: PointerEvent) => {
+    if (grabbedHandle) {
+      const [x, y] = transform.elementToImage(evt.offsetX, evt.offsetY);
+
+      const delta: [number, number] = [x - origin[0], y - origin[1]];
+
+      shape = editor(initialShape, grabbedHandle, delta);
+      
+      dispatch('change', shape);
+    }
+  }
+
+  const onRelease = (evt: PointerEvent) => {    
+    const target = evt.target as Element;
+    target.releasePointerCapture(evt.pointerId);
+
+    grabbedHandle = null;
+
+    initialShape = shape;
+    
+    dispatch('release');
+  }
+</script>
+
+<g
+  class="a9s-annotation selected"
+  on:pointerup={onRelease}
+  on:pointermove={onPointerMove}>
+
+  <slot grab={onGrab} />
+</g>

package/src/annotation/editors/EditorMount.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+  import type { DrawingStyle } from '@annotorious/core';
+  import { createEventDispatcher, onMount, type SvelteComponent } from 'svelte';
+  import type { ImageAnnotation, Shape } from '../../model';
+  import { computeStyle } from '../utils/styling';
+  import type { Transform } from '../Transform';
+
+  const dispatch = createEventDispatcher<{ grab: undefined, release: undefined, change: Shape }>();
+
+  /** Props */
+  export let annotation: ImageAnnotation;
+  export let editor: typeof SvelteComponent;
+  export let style: DrawingStyle | ((annotation: ImageAnnotation) => DrawingStyle) = undefined;
+  export let target: SVGGElement;
+  export let transform: Transform;
+  export let viewportScale: number;
+
+  let editorComponent: SvelteComponent;
+
+  $: computedStyle = computeStyle(annotation, style);
+
+  $: if (editorComponent) editorComponent.$set({ transform });
+
+  $: if (editorComponent) editorComponent.$set({ viewportScale });
+
+  onMount(() => {
+    editorComponent = new editor({
+      target,
+      props: { shape: annotation.target.selector, computedStyle, transform, viewportScale }
+    });
+
+    editorComponent.$on('change', event => {
+      editorComponent.$$set({ shape: event.detail });
+      dispatch('change', event.detail);
+    });
+
+    editorComponent.$on('grab', event => dispatch('grab', event.detail));
+    editorComponent.$on('release', event => dispatch('release', event.detail));
+
+    return () => {
+      editorComponent.$destroy();
+    }
+  });
+</script>

package/src/annotation/editors/Handle.ts

@@ -0,0 +1,21 @@
+export type Handle = string;
+
+export const Handle = (value: string | number) => `HANDLE-${value}`;
+
+Handle.SHAPE = 'SHAPE';
+
+Handle.TOP = 'TOP';
+
+Handle.RIGHT = 'RIGHT';
+
+Handle.BOTTOM = 'BOTTOM';
+
+Handle.LEFT = 'LEFT';
+
+Handle.TOP_LEFT = 'TOP_LEFT';
+
+Handle.TOP_RIGHT = 'TOP_RIGHT';
+
+Handle.BOTTOM_RIGHT = 'BOTTOM_RIGHT';
+
+Handle.BOTTOM_LEFT = 'BOTTOM_LEFT';

package/src/annotation/editors/editorsRegistry.ts

@@ -0,0 +1,14 @@
+import { ShapeType, type Shape } from '../../model';
+import type { SvelteComponent } from 'svelte';
+import { PolygonEditor } from './polygon';
+import { RectangleEditor } from './rectangle';
+
+const REGISTERED = new Map<ShapeType, typeof SvelteComponent>([
+  [ShapeType.RECTANGLE, RectangleEditor],
+  [ShapeType.POLYGON, PolygonEditor]
+]);
+
+export const getEditor = (shape: Shape) => REGISTERED.get(shape.type);
+
+export const registerEditor = (shapeType: ShapeType, editor: typeof SvelteComponent) =>
+  REGISTERED.set(shapeType, editor);

package/src/annotation/editors/index.ts

@@ -0,0 +1,7 @@
+export * from './polygon';
+export * from './rectangle';
+export * from './editorsRegistry';
+export * from './Handle';
+
+export { default as Editor } from './Editor.svelte';
+export { default as EditorMount } from './EditorMount.svelte';

package/src/annotation/editors/polygon/PolygonEditor.svelte

@@ -0,0 +1,64 @@
+<script type="ts">
+  import { boundsFromPoints } from '../../../model';
+  import type { Polygon } from '../../../model';
+  import type { Transform } from '../../Transform';
+  import { Editor, Handle } from '..';
+
+  /** Props */
+  export let shape: Polygon;
+  export let computedStyle: string = undefined;
+  export let transform: Transform;
+  export let viewportScale: number = 1;
+
+  $: geom = shape.geometry;
+
+  $: handleSize = 10 / viewportScale;
+
+  const editor = (polygon: Polygon, handle: Handle, delta: [number, number]) => {
+    let points: [number, number][];
+
+    if (handle === Handle.SHAPE) {
+      points = polygon.geometry.points.map(([x, y]) => [x + delta[0], y + delta[1]]);
+    } else {
+      points = polygon.geometry.points.map(([x, y], idx) =>
+        handle === Handle(idx) ? [x + delta[0], y + delta[1]] : [x, y]
+      );
+    }
+
+    const bounds = boundsFromPoints(points);
+
+    return {
+      ...polygon,
+      geometry: { points, bounds }
+    }
+  }
+</script>
+
+<Editor
+  shape={shape}
+  transform={transform}
+  editor={editor}
+  on:change 
+  on:grab
+  on:release
+  let:grab={grab}>
+
+  <polygon
+    class="a9s-outer"
+    style={computedStyle ? 'display:none;' : undefined}
+    on:pointerdown={grab(Handle.SHAPE)}
+    points={geom.points.map(xy => xy.join(',')).join(' ')} />
+
+  <polygon
+    class="a9s-inner a9s-shape-handle"
+    style={computedStyle}
+    on:pointerdown={grab(Handle.SHAPE)}
+    points={geom.points.map(xy => xy.join(',')).join(' ')} />
+
+  {#each geom.points as point, idx}
+    <rect 
+      class="a9s-corner-handle"
+      on:pointerdown={grab(Handle(idx))}
+      x={point[0] - handleSize / 2} y={point[1] - handleSize / 2} height={handleSize} width={handleSize} />
+  {/each}
+</Editor>

package/src/annotation/editors/polygon/index.ts

@@ -0,0 +1 @@
+export { default as PolygonEditor } from './PolygonEditor.svelte';