Repository
https://github.com/silvia-odwyer/pixels.js
Pixels.JS is an image filtering library with over 70 photo filters for use in-browser and soon with NodeJS.
Image filtering comprises vintage filters, solarizers, inverters, colour tints, and over seventy more. These filters can be applied to any image, and the filtered image is returned.
Check Out The Official Website
A complete demo of the library, as well as an interactive web app which uses the library, can be found at this library's official website: https://silvia-odwyer.github.io/pixels.js/
Technology Stack
The library is coded with ES2015, and is bundled with Webpack. It can be used with or without Webpack, and any version of JavaScript or ECMAScript.
Image filtering is done by manipulating the pixel data of each individual pixel in the image. By altering the R, G, and B values of each pixel, the image data can be manipulated as a result.
PixelsJS In Action
How To Get Started
Importing PixelsJS
Include the following script tag in your webpage's head tag:
<script src="https://cdn.jsdelivr.net/gh/silvia-odwyer/pixels.js/dist/Pixels.js"></script>
Using PixelsJS
After you've included a copy of Pixels.JS in your head tag, include an image in your HTML, and assign an ID to it so you can select it later in your JavaScript.
Then, in your JavaScript:
// Select the image you wish to filter
var img = document.getElementById("img")
// First parameter is the image object, and the second is the filter you wish to apply.
img.onload = function() {
pixelsJS.filterImg(img, "twenties");
}
Methods
PixelsJS contains three key methods:
filterImg
filterImgData
getFilterList
filterImg(imageObject, filterName)
In-Browser Only
This method takes an image object and a filter name, and it returns the filtered image as a canvas.
The original image is replaced with the filtered image in canvas format.
The list of all filters can be retrieved by using getFilterList, as described below.
Parameters
- imageObject: This consists of a HTML Image Element. If you add an image to the webpage, and select it with getElementById or querySelector,
this is the object you then pass to the filterImg method. - filterName: Name of the filter you'd like. If the filter is invalid, an error will be thrown.
Returns
A canvas object. The original image is automatically replaced by the new canvas.
filterImgData(imgData, filter) -> imgData
Every image consists of pixels, whose pixel data can be retrieved using the getImageData method, as found in the HTML5 Canvas API.
let imgData = context.getImageData(0, 0, canvas.width, canvas.height);
If you'd like to filter only the image data or work with the image data alone (and not the image), you can use this method instead.
It filters or manipulates the image data passed to it, and then returns the filtered image data array.
You can then place this image data on a canvas or replace the current image data with this data:
context.putImageData(newImgData, 0, 0)
Parameters
- imgData: This consists of an image data ndArray, as taken from the image by using the getImageData method on the image.
- filterName: Name of the filter you'd like. If the filter is invalid, an error will be thrown.
Returns
The filtered image data.
getFilterList() -> array
To get a list of all filters available in PixelJS, just call getFilterList.
An array of all filters will be returned.
Documentation
For further explanation on the available filter categories, as well as extra help and guidance in setting PixelsJS up, check out the official documentation: https://pixelsjs.readthedocs.io/en/latest/
Roadmap
I would like to add up to fifty more filters to this library in the coming weeks, as well as give more flexibility to the dev so that they can customize their own filters as they wish.
I am also going to deploy PixelsJS as a package on npm, so that it can be used by NodeJS developers.
How to Contribute?
If you'd like to contribute, just open a Pull Request on this library's official GitHub repository, or else get in touch with me via Discord, where my username is: Silvia923#9909
Each of the image filters are placed in their own respective modules or filter categories, eg: brightness adjusters, offsets, noise generators, etc., These modules are then imported into the main library and each of the filters in each module can then be applied to an image.
Contributor Guidelines
Identify which category your filter belongs in. Check the JS files found within the
libdirectory and see where your filter belongs.
If it doesn't belong in any, choose one or open an Issue and I'll create a new category.Add your filter function, ensuring it returns filtered image data.
Add the name of your filter and its associated method to the filter_dict variable in index.js. Make sure to import the category file where the filtering method belongs.