PixelsJS: An image filtering library with 70+ image filters for use in-browser

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

1. 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.
2. 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

1. imgData: This consists of an image data ndArray, as taken from the image by using the getImageData method on the image.
2. 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 lib directory 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.

GitHub Account

https://github.com/silvia-odwyer