openseadragon-select-plugin

plugin for openseadragon image viewer. this plugin adds the ability to select regions of the image by mouse gestures.

installation

$   npm i openseadragon-select-plugin

Working Demo

Usage

Include openseadragon-select-plugin after OpenSeadragon in your file.

    import { Viewer } from 'openseadragon';
    import 'openseadragon-select-plugin'

    const viewer = new Viewer({})

Then after you create a viewer you can call the selection method from the viewer instance:

    const selection = viewer.selection(options);

options

the options is just an object with a callback function who is called once the selecting is done:

    interface ViewerSelectionOptions {
	/**
	 * callback that will be called after the drawing is done.
	 * @param rect bounding box of the selected aria
	 * @param shape the shape object used to draw the selection
	 * @required
	 */
	onSelection: (rect: Rect, shape: BaseShape) => void;
	/**
	 * if set to true, the shape will automatically
	 * be added to the canvas after drawing is finished.
	 * @default false
	 */
	keep: boolean;
}

Selection

the selection object has two methods:

    /*
    * activate drawing mode
    */
    selection.enable();
    /*
    * deactivate drawing mode
    */
    selection.disable();

you can also add shapes to be displayed on the image by calling:

    viewer.selectionHandler.addShape(shape)

and remove them by:

    viewer.selectionHandler.removeShape(shape)

    // or remove all by:
    viewer.selectionHandler.clear()

note: if you want to add shapes without using the viewer.selection function, you need to initialize it first by calling initSelection:

    viewer.initSelection();

Advanced

you can customize the drawing process by changing the drawOptions, or evan add custom shapes to be drawn while selecting instead of default rectangle.

drawOptions

you can change the drawing options, be setting:

    viewer.selectionHandler.drawer.drawOptions = {...newOptions}

defaults to:

    const defaultDrawingOptions = {
        color: 'rgb(200, 0, 0)',
        lineWidth: 2,
        fill: 'rgba(220,220,220,0.2)',
    }

shapes

the default shape is RectShape but PolygonShape, BrushShape LineShape and PointShape are also available.

other shapes can be activated by:

    viewer.selectionHandler.drawer.setDrawerShape(ShapeNames.name)

you can add custom shapes by extending the abstract BaseShape class

    import { BaseShape } from 'openseadragon-select-plugin';

    class CustomShape extends BaseShape {
        ...
    }

or even create complex shapes by extending the abstract GroupShape class:

    class PolygonShape extends GroupShape<
        LineShape | PointShape
    > {
        get shapes (): BaseShape[] {
            return [];
        }
    }

you will need to implement these abstract methods/fields:

    class CustomShape extends BaseShape {
        readonly boundingBox: Rect;

        /*
        * this is not required in `GroupShape`
        */
        toPath2D(): Path2D;

        startDrawing(point: Point): void;
        updateDrawing(point: Point): void;
        endDrawing(point?: Point): void;
    }

once drawing is finished you need to call this.finishDrawing().

registering a custom shape:

custom shapes need to be registered manually:

    viewer.selectionHandler.drawer.addShapes(ShapeNames.name, customShapesConstructor)

and then you can select them by:

    viewer.selectionHandler.drawer.setDrawerShape(ShapeNames.name)

License

Apache 2.0