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

pixel-getter

v2.0.1

Published

A powerful tool for retrieving image pixel information in Node.js. It supports various image formats and provides both Promise-based and callback-based APIs for flexibility.

Downloads

231

Readme

Pixel Getter

npm version npm downloads Build Status Coverage Status

Pixel Getter is a powerful Node.js tool designed to extract pixel information from images. It offers support for various image formats and provides both Promise-based and callback-style APIs to cater to diverse programming preferences.

Important Notice: Breaking Changes

Version 2 introduces significant updates and breaking changes. If you're upgrading from v1, please carefully review the new usage instructions.

Installation

To incorporate Pixel Getter into your project, execute the following command:

$ npm install --save pixel-getter

Usage

Pixel Getter currently supports the following image formats: JPG, PNG, and GIF.

Basic Usage

Begin by importing the Pixel Getter module:

const pixelGetter = require('pixel-getter');

You can retrieve pixel information by providing an image buffer, local filename, or remote URL.

Promise-based Approach

const result = await pixelGetter.get("example.jpg");
const result = await pixelGetter.get(Buffer.from(...));
const result = await pixelGetter.get("https://nodejs.org/images/logo-light.png");

Callback-based Approach

pixelGetter.get("example.jpg", (err, pixels) => {
  if (err) {
    console.error(err);
  } else {
    console.log(pixels);
  }
});

pixelGetter.get(Buffer.from(...), (err, pixels) => {
  if (err) {
    console.error(err);
  } else {
    console.log(pixels);
  }
});

pixelGetter.get("https://nodejs.org/images/logo-light.png", (err, pixels) => {
  if (err) {
    console.error(err);
  } else {
    console.log(pixels);
  }
});

Options

Pixel Getter allows you to customize its behavior using an options object. Here's the structure of the options object:

interface PixelGetterOptions<Type extends PixelType = PixelType.AUTO> {
  pixelType?: Type;
  frames?: number | [number, number];
  timeout?: number;
}
  • pixelType: Specifies the desired pixel type (RGB or RGBA) for the returned data.
  • frames: For GIF images, specifies which frame(s) to process. Can be a single number or an array of two numbers representing the start and end frames.
  • timeout: Sets a timeout (in milliseconds) for remote image retrieval.

You can pass the options object as the second argument in both Promise-based and callback-based approaches:

// Promise-based with options
const result = await pixelGetter.get('example.jpg', {
  pixelType: pixelGetter.PixelType.RGB,
  timeout: 5000,
});

// Callback-based with options
pixelGetter.get(
  'animation.gif',
  {
    frames: [0, 5],
    pixelType: pixelGetter.PixelType.RGBA,
  },
  (err, pixels) => {
    if (err) {
      console.error(err);
    } else {
      console.log(pixels);
    }
  }
);

Pixel Information Structure

The returned pixels object contains the following information:

interface PixelInfo {
  width: number;
  height: number;
  pixelsCount: number;
  pixels: (RGB[] | RGBA[])[];
  pixelType: PixelType.RGB | PixelType.RGBA;
}
  • pixels[0] represents the pixel array of the first frame.
  • JPG and PNG files always contain a single frame.

GIF Support

When working with GIF files, you can specify an optional frames parameter in the options object. This can be either a single number or an array containing the start and end frame indices.

Promise-based GIF Processing

const result = await pixelGetter.get('animation.gif', { frames: 0 });
const result = await pixelGetter.get('animation.gif', { frames: [0, 1] });

Callback-based GIF Processing

pixelGetter.get('animation.gif', { frames: 0 }, (err, pixels) => {
  if (err) {
    console.error(err);
  } else {
    console.log(pixels);
  }
});

pixelGetter.get('animation.gif', { frames: [0, 1] }, (err, pixels) => {
  if (err) {
    console.error(err);
  } else {
    console.log(pixels);
  }
});

Timeout Configuration

For remote image retrieval, you can set a timeout duration using the timeout option:

pixelGetter.get(
  'http://example.com/image.jpg',
  { timeout: 10000 },
  (err, pixels) => {
    if (err) {
      console.error(err);
    } else {
      console.log(pixels);
    }
  }
);

Pixel Type Specification

You can specify the desired pixel type (RGB or RGBA) for the returned data using the pixelType option:

const result = await pixelGetter.get('example.jpg', {
  pixelType: pixelGetter.PixelType.RGB,
});

Raw Pixel Data Retrieval

In addition to the get function, Pixel Getter also provides a getRaw function that returns raw pixel data as a Buffer. This can be useful for more advanced image processing tasks or when you need to work with the raw binary data directly.

Promise-based Raw Data Retrieval

const rawResult = await pixelGetter.getRaw("example.jpg");
const rawResult = await pixelGetter.getRaw(Buffer.from(...));
const rawResult = await pixelGetter.getRaw("https://nodejs.org/images/logo-light.png");

Callback-based Raw Data Retrieval

pixelGetter.getRaw('example.jpg', (err, rawPixels) => {
  if (err) {
    console.error(err);
  } else {
    console.log(rawPixels);
  }
});

The getRaw function accepts the same options as the get function:

const rawResult = await pixelGetter.getRaw('example.jpg', {
  pixelType: pixelGetter.PixelType.RGB,
  timeout: 5000,
});

The returned rawPixels object has the following structure:

interface RawPixelInfo {
  width: number;
  height: number;
  pixelsCount: number;
  pixels: Buffer[];
  pixelType: PixelType.RGB | PixelType.RGBA;
}

Note that pixels is an array of Buffers, where each Buffer represents the raw pixel data for a frame.

Contributing

We warmly welcome contributions to Pixel Getter! Feel free to fork the repository and submit pull requests to help improve this tool.