Home

Leaflet.TileLayer.Filter

Are you bored with the basic, free tile map services out there, or have you ever wanted to change their base offerings to fit in better with your app?

Do you want the appearance of custom map tiles without having to setup your own tile server? Spice up your maps by adding customizable image filters to tile images. Use one of the existing, free tile providers like MapQuest, OSM, Stamen, and others, then change up their default offerings by adjusting the colors/styling on the client end.

This plugin extends L.TileLayer based classes, adding support for tile image filters. It provides extensible canvas-based filter approaches as well as CSS3 image filters. Canvas filters can be chained together and combined with one or more CSS3 image filters, allowing for many variations. It was originally inspired by Ilya Zverev's Leaflet.TileLayer.Grayscale plug-in, but modified to be more extensible, supporting more than just a grayscale tile filter.

Basic Usage

All L.TileLayer based classes will now support passing a filter option in the constructor as well as setFilter and clearFilter methods.

var baseLayer = new L.TileLayer('http://otile1.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}.jpg', {
	filter: function () {
		new L.CSSFilter({
			filters: ['saturate(200%)']
		}).render(this);
	}
});

var baseLayer = new L.StamenTileLayer('toner');

baseLayer.setFilter(function (image, ctx) {
	new L.CanvasFilter({
		channelFilter: function (imageData) {
			return new L.ChannelFilters.Colorize({
				values: [100, 100]
			}).render(imageData);
		}
	}).render(this, image, ctx);
});

The filter option, or the argument passed to setFilter is a function that should operate on the tile data by instantiating a new L.CanvasFilter or L.CSSFilter and calling render on that filter. The context of this function (the this variable) is the Leaflet tile object.

Details

This plugin includes two main types of filters that extend a basic L.ImageFilter class: Canvas filters and CSS3 image filters. If you're supporting modern browsers, then CSS3 image filters are the preferred approach, since they're faster than using canvas-based approaches. However, there are only a select number of effects you can apply using CSS3 image filters, whereas canvas filters can be customized to do lots of things. Note that this plugin hasn't been tested and definitely won't work on browsers below IE 9 without using some sort of polyfill.

Canvas Filters

The L.CanvasFilter class provides an extensible mechanism for defining Canvas based filters. Most of the time, these filters operate on canvas channel data through the use of L.CanvasChannelFilter-based classes, but the L.CanvasFilter class can be extended directly by overriding the render method, allowing the use of external canvas libraries for canvas manipulation (e.g. Cayman JS).

var baseLayer = new L.TileLayer('http://otile1.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}.jpg', {
	filter: function (image, ctx) {
	        new L.CanvasFilter({
		        channelFilter: function (imageData) {
			        return new L.ChannelFilters.Sepia().render(imageData);
		        }
	        }).render(this, image, ctx);
	}
});

Most of the time, you will provide a predefined canvas channel filter when instantiating an L.CanvasFilter instance, by specifying a channelFilter option in the constructor. The channelFilter option expects a function that operates on the canvas imageData, which is an array of RGBA pixel channels.

Canvas Channel Filters

There are multiple predefined canvas channel filters available for use with the L.CanvasFilter class.

CSS3 Image Filters

The L.CSSFilter class provides a mechanism for applying one or more CSS3 image filters to Leaflet map tiles. Supply filters by providing an array of CSS3 image filter strings (e.g. ['saturate(200%)','hue-rotate(30deg)']).

var baseLayer = new L.TileLayer('http://otile1.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}.jpg', {
	filter: function () {
		new L.CSSFilter({
			filters: ['invert(100%)']
		}).render(this);
	}
});

Presets

The plugin includes a number of filter presets. These are listed in the L.ImageFilters.Presets object. There are both Canvas and CSS3 presets defined: L.ImageFilters.Presets.CanvasChannel and L.ImageFilters.Presets.CSS.