npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

img-mage

v1.0.2

Published

A node.js image processing library

Downloads

16

Readme

Img-mage

Install

npm install --save img-mage

Features

  • Chained operations
  • Support frequency domain processing
  • Provide built-in complex number library Complex.js for you to manipulate complex numbers in frequency domain
  • Provide highly flexible map function for pixel-wise manipulation
  • Support channel-wise operations to reduce execution time
  • Support node.js and browser environments
  • Currently only support jpeg format!! (Contribution is welcome) Demo

Table of content

How to use

Example 1: Chained operations

const { Image } = require('img-mage');

const { GAUSSIAN_1D, LAPLACIAN_90 } = Image.CONSTANT;
const Gaussian1D = Image.filter(GAUSSIAN_1D, 2);  // sigma=2
const Laplacian90 = Image.filter(LAPLACIAN_90);
const img = new Image().load('example.jpg');

img
.convolve1D(Gaussian1D, 'x')  // apply 1D Gaussian filter along x-direction
.convolve1D(Gaussian1D, 'y')  // apply 1D Gaussian filter along y-direction
.convolve2D(Laplacian90)  // apply Laplacian filter
.add(img)  // add back the original image
.clip()  // clip overflow pixels
.save('sharpen.jpg');

Example 2: Harris corner detection algorithm

const corners = img.detectCorners(2, 1000000);  // sigma=2, threshold=1000000
img
.plot(corners)
.save('corners.jpg');

Example 3: Channel-wise Map

We introduce a robust method called map, which enables pixel-wise manipulation. This method is designed for channel-wise processing, i.e. you can specify the index of the channels that you want to process to reduce execution time.

const height = img.getDimensions()[1];
/**
 * Channel is an 2D array,
 * The callback maps each pixel to a new pixel.
 */
const cb = (pixel, i, j, k, channel) => channel[height - 1 - i][j];

img.map(cb); // reflect the image along x-direction
img.map(cb, 0); // only reflect the red channel
img.map(cb, 0, 2); // only reflect the red and blue channels

// Equivalent operations
img.reflectX();
img.reflectX(0);
img.reflectX(0, 2);

Example 4: Frequency domain manipulation

const GLPF = Image.filter(Image.CONSTANT.GLPF);
img
.fourier() // fast fourier transform
.fourierMap(GLPF) // apply Gaussian low-pass filter
.inverseFourier()  // fast inverse fourier transform
.clip()  // clip overflow pixels
.save('blur.jpg');

Example 5: Custom filters

It is extremely easy to implement a custom filter. If the filter is linear, you can implement it as an 2D array. If the filter is non-linear, e.g. Median filter, you can implement it as a map callback. If the filter is for frequency domain, implement it as a fourierMap callback Example.

const derivativeFilter2D = [
  [1, 0, -1],
  [2, 0, -2],
  [1, 0, -1],
];
img.convolve2D(derivativeFilter);

const derivativeFilter1D = [1, 0, -1];
img.convolve1D(derivativeFilter1D, 'x');

// 3x3 max filter
const maxFilter = (pixel, i, j, k, channel) => {
  const h = channel.length;
  const w = channel[0].length;

  let max = Number.NEGATIVE_INFINITY;
  for (let x = -1; x <= 1; x++) {
    for (let y = -1; y <= 1; y++) {
      const posX = i - x;
      const posY = j - y;
      if (posX < 0 || posX >= h || posY < 0 || posY >= w) {
        continue;
      }
      max = Math.max(max, channel[posX][posY]);
    }
  }
  return max;
}
img.map(maxFilter);

// 

API

Image

const { Image } = require('img-mage');

const img = new Image().load('rgb.jpg');
const [width, height, depth] = img.getDimensions();
const bitDepth = img.getBitDepth();
const R = img.getChannel(0);
const [r, g, b] = img.getPixel(10, 10);
img.save('rgb2.jpg');

map(cb, ...channels)

Map is a robust method, it provides you a flexible way to implement most of the spatial transformations. Map applies the callback to each pixel and produce a new pixel. You can specify the channels you want to apply the map function to reduce execution time. The callback takes current pixel, pixel coordinates (i, j, k), and current channel as input.

Example 1. Invert an image

const maxIntensity = 2 ** img.getBitDepth() - 1;

const cb = (pixel) => maxIntensity - pixel;

img.map(cb); // invert whole image
img.map(cb, 0); // only invert the R channel
img.map(cb, 1, 2); // only invert the G and B channels

Example 2: Add an image

const img2 = new Image().load('img2.jpg'); // assume same size

const cb = (pixel, i, j, k) => pixel + img2.getChannel(k)[i][j];

img.map(cb); // add img2 to img
img.map(cb, 0); // add R channel of img2 to R channel of img
img.map(cb, 1, 2); // add G and B channels of img2 to G and B channels of img

Example 3: Reflect an image

const height = img.getDimensions()[1];
const cb = (pixel, i, j, k, channel) => channel[height - 1 - i][j];

img.map(cb); // reflect the image along x-direction
img.map(cb, 0); // only reflect the red channel
img.map(cb, 0, 2); // only reflect the red and blue channels

fourier(...channels)

inverseFourier()

Apply fast fourier transform to the channels of an image and convert it to frequency domain. Apply fast inverse fourier transform to all the fourier channels of an image and convert back to the spatial domain. Note that the fourier transformation is centered.

img
.fourier()
.inverseFourier()
.clip() // Suggest to clip the pixels to ignore the floating point errors

fourierMap(cb, ...channels)

Similar to map in spatial domain, fourierMap is the map in frequency domain. The only different is that the callback takes centerX and centerY as additional arguments, which are the center coordinate of the transformation. Note that all pixels in frequency domain are complex number. We provide a library Complex.js for you to manipulate complex numbers

Example: Ideal Low-Pass Filter

const { Complex } = require('img-mage');

const cb = (pixel, i, j, k, centerX, centerY, channel) => {
  const distance = Math.sqrt((i - centerX) ** 2 + (j - centerY) ** 2);
  if (distance <= 100) { // cut-off frequency
    return pixel;
  }
  return new Complex(0); // 0 in complex number
}
// apply ILPF to all channels
img
.fourier()
.fourierMap(cb)
.inverseFourier()
.clip()
.save('blur.jpg');

fourierSpectrum()

fourierPhase()

Get the fourier spectrum (or fourier phase) of an image. Fourier Spectrum

img
.fourier()
.fourierSpectrum()
.rescale()
.logTransform()
.save('fourier-spectrum.jpg');

filter(type, ...options)

We provide some common linear, non-linear, and frequency domain filters. Linear filters are in the form of 1D and 2D arrays, non-linear filters are in the form of map callback, frequency domain filters are in the form of fourierMap callback. List of the filters:

| Name | Argument(s) | Type | Remark | | ------------ | ------------ | ------------ | ------------ | | BOX_FILTER | size | Linear || | LAPLACIAN_45 | No | Linear || | LAPLACIAN_90 | No | Linear || | GAUSSIAN_1D | sigma | Linear|| | GAUSSIAN_2D | sigma | Linear || | MAX_FILTER | size | Non-linear || | MIN_FILTER | size | Non-linear || | MEDIAN_FILTER | size | Non-linear || | ILPF | Cut-off | Frequency domain | Ideal low-pass | | GLPF | Cut-off | Frequency domain | Gaussian low-pass | | BLPF | Cut-off, order | Frequency domain | Butterworth low-pass | | IHPF | Cut-off | Frequency domain | Ideal high-pass | | GHPF | Cut-off | Frequency domain | Gaussian high-pass filter | | ILPF | Cut-off | Frequency domain | Ideal low-pass filter | | BHPF | Cut-off, order | Frequency domain | Butterworth high-pass filter |

const { BOX_FILTER, MEDIAN_FILTER, GHPF } = Image.CONSTANT;

const boxFilter = Image.filter(BOX_FILTER);
const medianFilter = Image.filter(MEDIAN_FILTER, 3); // size
const gaussianHighPass = Image.filter(GHPF, 100); // cut-off frequency

img.convolve2D(BOX_FILTER); // linear filter, thus an 2D array
img.map(MEDIAN_FILTER); // non-linear, use map
img.fourier().fourierMap(gaussianHighPass); // frequency domain, use fourierMap

convolve1D(filter, direction, ...channels)

convolve2D(filter, ...channels)

Apply 1D and 2D convolution to the channels of an image. For 1D convolution, you should specify the direction of the convolution. It allows you to utilize the advantages of separating 2D filters.

const gaussian1D = Image.filter(Image.CONSTANT.GAUSSIAN_1D, 2);
const gaussian2D = Image.filter(Image.CONSTANT.GAUSSIAN_2D, 2);
const custom1D = [-1, 0, 1];
const custom2D = [
  [-1, -2, -1],
  [0, 0, 0],
  [1, 2, 1],
];

img
.convolve1D(gaussian1D, 'x') // x-direction
.convolve1D(gaussian1D, 'y'); // y-direction

img.convolve2D(gaussian2D); // equivalent but slower

img
.convolve1D(custom1D, 'x')
.convolve1D(custom1D, 'y'); // image derivative

img.convolve2D(custom2D);

detectCorners(sigma, threshold)

Apply Harris corner detection algorithm to your image.

const checkerboard = new Image().load('checkboard.jpg');

const corners = checkerboard.detectCorners(2, 1000000);
checkerboard.plot(corners);

Checkerboard

crop(x, y, w, h)

Crop an image with width w and height h at (x, y)

img.crop(0, 0, 200, 200);
img.crop(0, 0, 10000, 10000); // handle overflow for you

rotate(rotation)

Rotate an image by specifying the rotation. 1 and -3 refer to clockwise 90 degrees, 2 and -2 refer to clockwise 180 degrees, 3 and -1 refer to clockwise 270 degrees.

img.rotate(1); // clockwise 90 degrees
img.rotate(-3); // equivalent

pad(x, y)

Add zero-padding to an image. The height and width of the resulting image are h + 2x and w + 2y respectively.

img.pad(10); // 10px to 4 sides
img.pad(10, 20); // 10px to top and bottom, 20px to left and right

reflectX(...channels)

reflectY(...channels)

Reflect the channels of an image vertically (x-direction) and horizontally (y-direction).

img.reflectX(); // reflect whole image
img.reflectX(0); // only reflect the R channel
img.reflectX(1, 2); // only reflect the G and B channels

negative(...channels)

Invert the channels of an image.

img.negative(); // invert whole image
img.negative(2); // only inver the B channel
img.negavie(0, 1); // Only inver the R and G channels

logTransform(...channels)

Apply log transform to the channels of an image. It enlarges pixel intensity.

img.logTransform(); // brighter
img.logTransform(0, 1); // more green

powerLawTransform(gamma, ...channels)

Apply power law transform to the channels of an image. gamma > 1 compresses the intensity while gamma < 1 enlarge the intensity.

img.powerLawTransform(0.5); // brighter
img.powerLawTransform(2); // darker
img.powerLawTransform(2, 0); // less red

clip(...channels)

Clip the overflow and underflow pixels to max intensity and 0 respectively.

img.clip(); // clip all channels
img.clip(0); // only clip the R channel

rescale(...channels)

Rescale the pixels to the range [0, maxIntensity].

img.rescale();
img.rescale(1); // only rescale the G channel

blur(sigma, ...channels)

Blur the channels of an image using Gaussian filter. Sigma controls the standard deviation of the distribution, larger sigma produces blurrier image.

img.blur(2); // blur the whole image
img.blur(2, 1, 2); // blur the G and B channels

sharpen(sigma, ...channels)

Sharpen the channels of an image using Laplacian filter. Sigma controls the sharp level, smaller sharper.

img.sharpen(0.5); // more sharp
img.sharpen(2); // less sharp

abs(...channels)

Calculate the absolute value of each pixel in the channels of an image.

add(Image, ...channels)

Apply pixel-wise addition to the channels of an image.

const Laplacian2D = Image.filter(Image.CONSTANT.LAPLACIAN_90);

img
.convolve2D(Laplacian2D) // get the edges of an image
.add(img) // add back the original image to make it sharper

subtract(Image, ...channels)

Apply pixel-wise subtraction to the channels of an image.

const sharpen = new Image().load('sharpen.jpg'); // assume in same dimensions

img
.subtract(sharpen)
.abs() // get the absolute values
.rescale()
.logTransform() // make the difference more obvious
.save('difference.jpg');

multiply(Image, ...channels)

Apply pixel-wise multiplication to the channels of an image.

RGBtoYIQ()

YIQtoRGB()

Convert RGB to YIQ and YIQ back to RGB.

const YIQ = img.RGBtoYIQ();
YIQ.getChannel(0); // Y channel
YIQ.getChannel(1); // I channel
YIQ.getChannel(2); // Q channel
const RGB = YIQ.YIQtoRGB(); // back to RGB

Future Plans (Contribution is welcome)

  • Support more image format (Currently only support jpeg)
  • Create a playground website to experience the library
  • Add more algorithm, such as scaling
  • Optimize implementations

License

MIT