jang2512 / openseadragonfiltering

OpenSeadragon filtering plugin

This OpenSeadragon plugin provides the capability to add filters to the images.

A demo is available here.

This plugin requires OpenSeadragon 2.1+.

Basic usage

Increase the brightness:

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: OpenSeadragon.Filters.BRIGHTNESS(50)
    }
});

Decrease the brightness and invert the image:

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: [
            OpenSeadragon.Filters.BRIGHTNESS(-50),
            OpenSeadragon.Filters.INVERT()
        ]
    }
});

Specify on which items (TiledImage) to apply the filters

Increase the brightness on item 0 and invert items 1 and 2:

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: [{
        items: viewer.world.getItemAt(0),
        processors: [
            OpenSeadragon.Filters.BRIGHTNESS(50)
        ]
    }, {
        items: [viewer.world.getItemAt(1), viewer.world.getItemAt(2)],
        processors: [
            OpenSeadragon.Filters.INVERT()
        ]
    }]
});

Note the items property. If it is not specified, the filter is applied to all items.

Load mode optimization

By default, the filters are applied asynchronously. This means that the tiles are cleared from the canvas and re-downloaded (note that the browser probably cached them though) before having the filter applied. This avoids to hang the browser if the filtering operation is slow. It also allows to use asynchronous filters like the ones provided by CamanJS.

However, if you have only fast and synchronous filters, you can force the synchronous mode by setting loadMode: 'sync':

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: OpenSeadragon.Filters.BRIGHTNESS(50)
    },
    loadMode: 'sync'
});

To visualize the difference between async and sync mode, one can compare how the brightness (sync) and contrast (async) filters load in the demo.

Provided filters

This plugin already include some filters which are accessible via OpenSeadragon.Filters:

• Thresholding

Set all pixels equals or above the specified threshold to white and the others to black. For colored images, the average of the 3 channels is compared to the threshold. The specified threshold must be between 0 and 255.

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: OpenSeadragon.Filters.THRESHOLDING(threshold)
    }
});

• Brightness

Shift the intensity of the pixels by the specified adjustment (between -255 and 255).

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: OpenSeadragon.Filters.BRIGHTNESS(adjustment)
    }
});

• Invert

Invert the colors of the image.

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: OpenSeadragon.Filters.INVERT()
    }
});

• Morphological operations

Erosion and dilation over a square kernel are supported by the generic morphological operation filter

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: [
            // Erosion over a 3x3 kernel
            OpenSeadragon.Filters.MORPHOLOGICAL_OPERATION(3, Math.min),

            // Dilation over a 5x5 kernel
            OpenSeadragon.Filters.MORPHOLOGICAL_OPERATION(5, Math.max),
        ]
    }
});

• Convolution

Apply a convolution kernel.

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: OpenSeadragon.Filters.CONVOLUTION([
            0, -1,  0,
           -1,  5, -1,
            0, -1,  0])
    }
});

• Colormap

Apply a colormap to the averaged RGB values of the image. Colormaps are defined by a series of [R,G,B] stops. Grayscale values of 0-255 are mapped to the interpolated stop values. A variable centerpoint allows adjustment of the colormap.

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: OpenSeadragon.Filters.COLORMAP([
           [0, 0,  0],
           [0, 128, 0],
           [0, 250,  0],
           [0, 255, 0]], 128)
    }
});

Integration with CamanJS

CamanJS supports a wide range of filters. They can be reused with this plugin like this:

var viewer = new OpenSeadragon.Viewer(...);
viewer.setFilterOptions({
    filters: {
        processors: function(context, callback) {
            Caman(context.canvas, function() {
                this.sepia(50);
                this.vibrance(40);
                // Do not forget to call this.render with the callback
                this.render(callback);
            });
        }
    }
});

Note: Caman is caching every canvas it processes. This causes two issues with this plugin:

1. It creates a memory leak because OpenSeadragon creates a lot of canvases which do not get garbage collected anymore.
2. Non-caman filters in between 2 camans filters get ignored.

There isn't any clean way to disable the cache system, however one can use this hack to prevent any caching:

    Caman.Store.put = function() {};

    var viewer = new OpenSeadragon.Viewer(...);
    viewer.setFilterOptions({
        filters: {
            processors: [
                function(context, callback) {
                    Caman(context.canvas, function() {
                        this.sepia(50);
                        // Do not forget to call this.render with the callback
                        this.render(callback);
                    });
                },
                OpenSeadragon.Filters.INVERT(),
                function(context, callback) {
                    Caman(context.canvas, function() {
                        this.vibrance(40);
                        // Do not forget to call this.render with the callback
                        this.render(callback);
                    });
                }
            ]
        }
    });

Implementing customs filters

To implement a custom filter, one need to create a function taking a 2D context and a callback as parameters. When that function is called by the plugin, the context will be a tile's canvas context. One should use context.getImageData to retrieve the pixels values and context.putImageData to save the modified pixels. The callback method must be called when the filtering is done. The provided filters are good examples for such implementations.

Edge effects

This plugin is working on tiles and does not currently handle tiles edges. This means that if you are using kernel based filters, you should expect edge effects around tiles.

Build the demo

To build the demo run npm install and then npm run-script build. The result of the build will be in the dist folder.

Disclaimer:

This software was developed at the National Institute of Standards and Technology by employees of the Federal Government in the course of their official duties. Pursuant to title 17 Section 105 of the United States Code this software is not subject to copyright protection and is in the public domain. This software is an experimental system. NIST assumes no responsibility whatsoever for its use by other parties, and makes no guarantees, expressed or implied, about its quality, reliability, or any other characteristic. We would appreciate acknowledgement if the software is used.