Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A Leaflet TileLayer extension which will replace RGB codes in the tiles, so as to give highlighting and masking effects.

For a quick start, check out the demos at

To download, either download one of the releases from the Github repository's Releases tab, or install via package manager:

  • npm i leaflet-tilelayer-pixelfilter

Constructor and Options

Usage is almost exactly like a typical L.TileLayer, except for a few additional options.

// after tiles load, any pure red (255,0,0) tiles will be replaced with black
// any other colors will be filled with white at 1/4 opacity
var filtered = L.tileLayerPixelFilter('https://mapbox-or-something/tiles/{z}/{x}/{y}.png', {
    matchRGBA: [ 0,  0,  0, 255  ],
    missRGBA:  [ 255, 255, 255, 64 ],
    pixelCodes: [ [255, 0, 0] ]
  • pixelCodes -- Specify which RGB codes you want to match. See setPixelCodes() for more details.
  • matchRGBA -- Specify which color to assign to pixels which match your stated pixelCodes. See setMatchRGBA() for more details.
  • missRGBA -- Specify which color to assign to pixels which do not match your stated pixelCodes. See setMissRGBA() for details.


setPixelCodes([ [r,g,b], [r,g,b], [r,g,b], ... ])

Define what RGB pixels are considered "matching". The tiles will then be re-evaluated and pixels will be reassigned the new matching or non-matching color based on this new list.

An empty set of pixel codes setPixelCodes([]) will results in all pixels being considered a match.

You can specify an impossible set of RGB codes such as setPixelCodes([ [-1,-1,-1] ]) to make sure that no pixel can match.


Set the RGBA code that will be applied to pixels which are on the provided list.

The value null may be given, to indicate that the existing pixel value should be preserved.


Set the RGBA code that will be applied to non-matching pixels.

The value null may be given, to indicate that the existing pixel value should be preserved.


  • The RGBA values in the image are very important, and must exactly match the pixel codes you set in matchRGBA Your data should be PNG files in RGBA mode (also called RGB with alpha channel). Anything else such as JPEG or indexed PNGs or JPEG files, will have antialiasing and other effects which change the pixels in your output image and cause them not to match the expected values.

  • You can use ArcMap's Composite Bands tool in order to create a three-band RGBA TIFF or PNG, so your pixels can be carefully contrived to represent not visual color but up to three separate variables. The resulting TIFF can be run through to generate the map tiles in PNG format. Your pixelCodes can then be thought of not as "255,0,0 means red" but "23,12,64 means mountainous, low feasibility, moderate cost" Basically any classified data whose value fits into the range 0-255 could be used, and up to three datasets, if you contrive it.

  • When preparing your map tiles be sure to use the nearest neighbor resampling algorithm. This causes interpolated pixels to inherit a their RGB code from the nearest pre-existing pixel using its pre-existing RGB value. Other resamplers including the default average or bilinear do not preserve pixel values, and will result in pixel values that were not in your original dataset. As such, the resulting pixels will not match your filtering needs. For example:

      gdalwarp -t_srs esg:3857 -r near input.tif output.tif -r near input.tif tiles
  • Canvas is paranoid about cross-origin tiles, in the same way as AJAX calls are weird about cross-domain JSON data. If the URL of your tiles starts with http or https, see the Cross Domain section for some advice.

  • Using null masks makes for really neat masking/visibility effects. Check out the demo.

Cross Domain

Like AJAX with cross-domain data, the Canvas is paranoid about cross-origin image content. If your tiles are hosted somewhere other than the rest of your website, then Canvas will refuse to do its thing. You basically have two options:

  • Move the tiles onto the same the website. If you think they already are, check the L.TileLayer URL and make sure.

  • Set up CORS for the map tile service, so the tile service explicitly includes the Access-Control-Allow-Origin "*" header. If you're not sure, use your browser's F12 debugger and make sure that the header is present.

For more information:


Leaflet TileLayer extension which can filter out pixels to provide a mask or color-swapping







No packages published