OpenSeadragon Filters

A high-performance OpenSeadragon plugin that provides real-time image filtering capabilities using WebGL acceleration.

🎨 Live Demo | 📦 NPM Package

• ⚡ WebGL-accelerated filtering for optimal performance
• 🎯 Multiple built-in filters: brightness, contrast, gamma, threshold, invert, greyscale
• 🔧 Customizable: create your own filters
• 🎭 Per-item filtering: apply different filters to different images (canvas mode)
• 🔄 Two rendering modes: tile-based (canvas) or viewport-based (WebGL overlay)
• 📦 TypeScript support: full type definitions included
• 🌐 Modern ESM/CJS: supports both module formats

• OpenSeadragon 5.0+
• Node.js 20+ (for development)

npm install openseadragon-filters

or

yarn add openseadragon-filters

import OpenSeadragon from 'openseadragon';
import { initializeFiltering, BRIGHTNESS } from 'openseadragon-filters';

const viewer = OpenSeadragon({
  id: 'viewer',
  tileSources: 'path/to/image.dzi'
});

const filterPlugin = initializeFiltering(viewer);
filterPlugin.setFilterOptions({
  filters: {
    processors: BRIGHTNESS(50)
  }
});

import OpenSeadragon from 'openseadragon';
import { initWebGLFiltering, BRIGHTNESS_WEBGL } from 'openseadragon-filters';

const viewer = OpenSeadragon({
  id: 'viewer',
  tileSources: 'path/to/image.dzi'
});

// Initialize after viewer is ready
viewer.addOnceHandler('open', () => {
  const filterPlugin = initWebGLFiltering(viewer);
  filterPlugin.setFilters([BRIGHTNESS_WEBGL(50)]);
});

This plugin provides two filtering approaches:

Filters each tile individually as it loads. Best for per-tile effects and compatibility.

import { initializeFiltering, BRIGHTNESS } from 'openseadragon-filters';

const filterPlugin = initializeFiltering(viewer);
filterPlugin.setFilterOptions({
  filters: {
    processors: BRIGHTNESS(50)
  }
});

Filters are applied in the order specified:

import { initializeFiltering, BRIGHTNESS, INVERT, CONTRAST } from 'openseadragon-filters';

filterPlugin.setFilterOptions({
  filters: {
    processors: [
      BRIGHTNESS(-50),
      CONTRAST(1.5),
      INVERT()
    ]
  }
});

Apply different filters to specific images:

import { initializeFiltering, BRIGHTNESS, INVERT } from 'openseadragon-filters';

filterPlugin.setFilterOptions({
  filters: [
    {
      items: viewer.world.getItemAt(0),
      processors: [BRIGHTNESS(50)]
    },
    {
      items: [viewer.world.getItemAt(1), viewer.world.getItemAt(2)],
      processors: [INVERT()]
    }
  ]
});

Note: If the items property is not specified, filters are applied to all items in the viewer.

The canvas-based plugin supports two rendering modes:

Tiles are progressively filtered as they load, preventing browser freezing:

filterPlugin.setFilterOptions({
  filters: { processors: BRIGHTNESS(50) },
  loadMode: 'async' // default
});

Filters are applied immediately for faster rendering with simple filters:

filterPlugin.setFilterOptions({
  filters: { processors: BRIGHTNESS(50) },
  loadMode: 'sync'
});

Tip: Use sync mode for fast, synchronous filters. Use async mode for complex or slow filters to maintain UI responsiveness.

Applies filters to the entire viewport using WebGL. Best for real-time performance and viewport-level effects.

Important: Initialize WebGL filtering after the viewer is ready using the open event.

import { initWebGLFiltering, BRIGHTNESS_WEBGL, CONTRAST_WEBGL } from 'openseadragon-filters';

viewer.addOnceHandler('open', () => {
  const filterPlugin = initWebGLFiltering(viewer);

  // Single filter
  filterPlugin.setFilters([BRIGHTNESS_WEBGL(50)]);

  // Multiple filters
  filterPlugin.setFilters([
    BRIGHTNESS_WEBGL(50),
    CONTRAST_WEBGL(1.5)
  ]);

  // Clear filters
  filterPlugin.clearFilters();
});

import { convertToWebGLFilter } from 'openseadragon-filters';

const customShader = `
precision mediump float;
uniform sampler2D u_image;
uniform float u_intensity;
varying vec2 v_texCoord;
void main() {
  vec4 color = texture2D(u_image, v_texCoord);
  gl_FragColor = vec4(color.rgb * u_intensity, color.a);
}
`;

viewer.addOnceHandler('open', () => {
  const filterPlugin = initWebGLFiltering(viewer);
  const customFilter = convertToWebGLFilter('custom', customShader, { u_intensity: 1.5 });
  filterPlugin.setFilters([customFilter]);
});

Use with initializeFiltering():

Adjusts pixel intensity.

• Range: -255 to 255
• Effect: Negative values darken, positive values brighten

BRIGHTNESS(50)  // Increase brightness
BRIGHTNESS(-50) // Decrease brightness

Adjusts image contrast.

• Range: 0 to ∞ (typically 0-3)
• Effect: Values < 1 reduce contrast, values > 1 increase contrast

CONTRAST(1.5) // Increase contrast
CONTRAST(0.5) // Decrease contrast

Applies gamma correction.

• Range: 0 to 5
• Effect: Values < 1 darken, values > 1 brighten

GAMMA(2.2) // Standard gamma correction
GAMMA(0.5) // Darken image

Converts image to black and white based on threshold.

• Range: 0 to 255
• Effect: Pixels ≥ threshold become white, others become black

THRESHOLDING(128) // Standard threshold

Converts image to greyscale.

GREYSCALE()

Inverts all colors.

INVERT()

Use with initWebGLFiltering(). Same parameters as canvas filters but with _WEBGL suffix:

import { 
  BRIGHTNESS_WEBGL, 
  CONTRAST_WEBGL, 
  GAMMA_WEBGL,
  THRESHOLDING_WEBGL,
  GREYSCALE_WEBGL,
  INVERT_WEBGL
} from 'openseadragon-filters';

// Usage
filterPlugin.setFilters([
  BRIGHTNESS_WEBGL(50),
  CONTRAST_WEBGL(1.5),
  GAMMA_WEBGL(2.2)
]);

Create custom filters by implementing a function that processes canvas context:

function customFilter(context, callback) {
  const imageData = context.getImageData(0, 0, context.canvas.width, context.canvas.height);
  const pixels = imageData.data;
  
  // Modify pixels (RGBA format)
  for (let i = 0; i < pixels.length; i += 4) {
    pixels[i] = 255 - pixels[i];     // Red
    pixels[i + 1] = 255 - pixels[i + 1]; // Green
    pixels[i + 2] = 255 - pixels[i + 2]; // Blue
    // pixels[i + 3] is alpha
  }
  
  context.putImageData(imageData, 0, 0);
  callback();
}

// Use the custom filter
filterPlugin.setFilterOptions({
  filters: {
    processors: customFilter
  }
});

1. Accept a CanvasRenderingContext2D as the first parameter
2. Accept a callback function as the second parameter
3. Call the callback when processing is complete
4. Use context.getImageData() to read pixels
5. Use context.putImageData() to write modified pixels

Initializes the filtering plugin for an OpenSeadragon viewer.

Parameters:

• viewer (OpenSeadragon.Viewer): The OpenSeadragon viewer instance

Returns: FilterPlugin instance

Configures and applies filters.

Parameters:

• options.filters (Object|Array): Filter configuration
  • processors (Function|Array): Single filter or array of filters
  • items (TiledImage|Array): Optional. Specific items to filter
• options.loadMode (String): Optional. 'async' (default) or 'sync'

Initializes WebGL viewport filtering for an OpenSeadragon viewer.

Parameters:

• viewer (OpenSeadragon.Viewer): The OpenSeadragon viewer instance

Returns: Object with methods:

• setFilters(filters): Apply WebGL filters
• clearFilters(): Remove all filters
• destroy(): Clean up resources

Applies WebGL filters to the viewport.

Parameters:

• filters (Array): Array of WebGLFilterConfig objects

Example:

filterPlugin.setFilters([
  BRIGHTNESS_WEBGL(50),
  CONTRAST_WEBGL(1.5)
]);

Creates a custom WebGL filter configuration.

Parameters:

• name (String): Filter identifier
• shader (String): GLSL fragment shader source
• uniforms (Object): Shader uniform values

Returns: WebGLFilterConfig object

Full TypeScript definitions are included:

import OpenSeadragon from 'openseadragon';
import { 
  initializeFiltering, 
  initWebGLFiltering,
  BRIGHTNESS, 
  BRIGHTNESS_WEBGL,
  FilterPlugin 
} from 'openseadragon-filters';

// Canvas-based
const viewer: OpenSeadragon.Viewer = OpenSeadragon({ id: 'viewer' });
const filterPlugin: FilterPlugin = initializeFiltering(viewer);
filterPlugin.setFilterOptions({
  filters: {
    processors: BRIGHTNESS(50)
  }
});

// WebGL-based
viewer.addOnceHandler('open', () => {
  const webglPlugin = initWebGLFiltering(viewer);
  webglPlugin.setFilters([BRIGHTNESS_WEBGL(50)]);
});

The canvas-based plugin processes tiles independently and does not handle cross-tile boundaries. Kernel-based filters may produce visible artifacts at tile edges.

git clone https://github.com/rssaini01/openseadragon-filters.git
cd openseadragon-filters
npm install

npm run build        # Build library
npm run dev          # Start demo dev server
npm run build:demo   # Build demo site

npm test             # Run tests
npm run test:watch   # Run tests in watch mode

openseadragon-filters/
├── src/                 # Source code
│   ├── index.ts        # Main entry point
│   ├── predefined-filters.ts
│   └── webgl-*.ts      # WebGL implementation
├── site/               # Demo application
├── tests/              # Test suite
└── dist/               # Built output
    ├── esm/           # ES modules
    ├── cjs/           # CommonJS
    └── types/         # TypeScript definitions

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• Tests pass (npm test)
• Code follows existing style
• TypeScript types are updated

MIT © Ravi Shankar Saini

See LICENSE for details.

• Built for OpenSeadragon
• Inspired by NIST's OpenSeadragonFiltering - completely rewritten with WebGL support and modern architecture. The original implementation was canvas-only and is no longer maintained

• Demo
• NPM Package
• GitHub Repository
• Issue Tracker
• OpenSeadragon