-
Notifications
You must be signed in to change notification settings - Fork 84
Documentation
PaintbrushJS is a lightweight, browser-based image processing library that can apply various visual filters to images within a web page.
You use it by applying a class to an element on the page and setting a few parameters with some extra HTML attributes. If the element is an img or it has a background-image set in your CSS, PaintbrushJS will create a temporary canvas element and manipulate the image there, before finally saving it back out to the original element.
See the PaintbrushJS demo for an idea of how it works, and you can also see a timed version to see how quick it’ll render a bunch of different filters (listed in milliseconds down at the bottom of the page)
PaintbrushJS is meant to stay out of your way as much as possible, so the setup is simple. First, you include two Javascript files at the top of your page, in between <head> and </head>:
<script type="text/javascript" src="common.js"></script>
<script type="text/javascript" src="paintbrush.js"></script>
Then within the body of the page, you apply a class to any element you’d like to filter:
<img src="image.jpg" class="filter-blur">
But you’ll probably want a little more control than that, so there are some filter-specific attributes you can set as well:
<img src="image.jpg" class="filter-blur" data-pb-blur-amount="0.5">
That
data-pb-blur-amount thing is a new part of HTML5, but the important thing to know is that all PaintbrushJS parameters start with data-pb-; that’s ‘pb’ as in Paintbrush, of course. The only bit that changes between filters is the second half, the blur-amount part. See the filters list below for more on these.
You can also apply filters to background images set by your CSS. Provided the following div had a valid background-image value, the syntax would be pretty much the same to blur the background image as it would the img above:
<div class="filter-blur" data-pb-blur-amount="0.5"></div>
Currently, the list of filters and their respective classes and data-* parameters are as follows:
-
Blur,
.filter-blur— blurs the image with Gaussian Blur
data-pb-blur-amount, a value greater than 0 that controls how much blur will be applied. Decimals work, so a value like 0.3 is totally valid. (defaults to 1)
example: <img src="image.jpg" class="filter-blur" data-pb-blur-amount="0.5">
-
Edges,
.filter-edges— detects the edges internally within the image. Works best in conjunction with greyscale, and mainly intended to be used with a value of 1.
data-pb-edges-amount, a value between 0 and 1 that controls the amount of the emboss effect that will be applied. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 1)
example: <img src="image.jpg" class="filter-edges" data-pb-edges-amount="0.5">
-
Emboss,
.filter-emboss— applies an embossed effect to the image. Works best in conjunction with greyscale.
data-pb-emboss-amount, a value between 0 and 1 that controls the amount of the emboss effect that will be applied. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 0.25)
example: <img src="image.jpg" class="filter-emboss" data-pb-emboss-amount="0.5">
-
Greyscale,
.filter-greyscale— converts the image to greyscale
data-pb-greyscale-opacity, a value between 0 and 1 that controls the greyscale effect’s transparency. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 1)
example: <div class="filter-greyscale" data-pb-greyscale-opacity="0.45">
-
Mosaic,
.filter-mosaic— pixellates the image to a specified size of blocks
data-pb-mosaic-opacity, a value between 0 and 1 that controls the matrix effect’s transparency. Most useful at 1, but there may be instances where a combination of the pixellated + original image is desired. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 1)
data-pb-mosaic-size, the size, in pixels, of each block in the resulting mosaic. A value of 1 would return the original image, 2 would be slight pixellation, and 15 would be big chunky pixel blocks.
example: <img src="image.jpg" class="filter-mosaic" data-pb-mosaic-opacity="0.5" data-pb-mosaic-size="5">
-
Noise,
.filter-noise— applies a random noise overlay
data-pb-noise-amount, a value greater than 0 that controls how much noise will be applied. While there’s no theoretical limit, values over 100 don’t tend to be terribly useful. Decimals work, so a value like 0.3 is totally valid. (defaults to 30)
data-pb-noise-type, can be either “mono” / “monochrome”, or “color” / “colour”. Controls whether the noise is rendered in colour or not. (defaults to mono)
example: <div class="filter-noise" data-pb-noise-amount="25" data-pb-noise-type="mono">
-
Posterize,
.filter-posterize— applies a reduced-tone posterization filter
data-pb-posterize-amount, a value between 0 and 255 that controls how many levels of tones to incorporate. Values less than 2 are more or less useless.
data-pb-posterize-opacity, a value between 0 and 1 that controls the posterize effect’s transparency. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 1)
example: <img src="image.jpg" class="filter-posterize" data-pb-posterize-amount="8" data-pb-posterize-opacity="0.5">
-
Sepia,
.filter-sepia— returns a sepia-toned version of the image
data-pb-sepia-opacity, a value between 0 and 1 that controls the sepia effect’s transparency. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 1)
example: <img src="image.jpg" class="filter-sepia" data-pb-sepia-opacity="0.6">
-
Sharpen,
.filter-sharpen— sharpens the image.
data-pb-sharpen-amount, a value between 0 and 1 that controls the amount of the sharpen effect that will be applied. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 0.25)
example: <img src="image.jpg" class="filter-sharpen" data-pb-sharpen-amount="0.5">
-
Tint,
.filter-tint— tints the image with a specific hex colour overlay
data-pb-tint-opacity, a value between 0 and 1 that controls the tint effect’s transparency. Think of it as a percentage, with 1 being 100% and 0.5 being 50%. (defaults to 1)
data-pb-tint-colour, a hex value specifying the colour to tint the image with. Can be spelled ‘color’ too.
example: <div class="filter-tint" data-pb-tint-opacity="0.5" data-pb-tint-colour="#F69023">