Palette

Generate various RGBA color palettes based on image pixel data

Installing

npm i @jayimbee/palette

Example

import palette from @jaimbee/palette;


const imgData = palette.extractImageDataFromSrc('https://some.site.com/godzilla.png', 3);

const imageColorPalette = palette.quantize(imgData);

console.log(imageColorPalette);
//
//     [
//      {
//        r: 123,
//        g: 145,
//        b: 12,
//        a: 255
//       }
//       ...
//     ]

Methods

🎨 blend

Type: Function

Description: returns a single blend of all pixel color values

⚙️ Params

• d <Uint8ClampedArray>: value returned from a canvas context calling .getImageData().data

📦 Returns

<RGBARecord>;

interface RGBARecord {
  r: number;
  g: number;
  b: number;
  a: number;
}

🛠️ Usage

const imgData = palette.extractImageDataFromSrc(imgURL, 3);

palette.blend(imgData);

🎨 dominant

Type: Function

Description: returns the most reoccurring pixel color

⚙️ Params

• d <Uint8ClampedArray>: value returned from a canvas context calling .getImageData().data

🛠️ Usage

const imgData = palette.extractImageDataFromSrc(imgURL, 3);

palette.dominant(imgData);

📦 Returns

<RGBARecord>;

interface RGBARecord {
  r: number;
  g: number;
  b: number;
  a: number;
}

🎨 quantize

Type: Function

Description: using the median cut algorithm, this returns an array of colors selected through finding the dominant color range and quantizing the color sets until the provided max depth is reached

⚙️ Params

• d <Uint8ClampedArray>
  • value returned from a canvas context calling .getImageData().data
• startingDepth <number>
  • default set to 0
• maxDepth <number>
  • default set to 2

🛠️ Usage

const imgData = palette.extractImageDataFromSrc(imgURL, 3);

palette.quantize(imgData);

📦 Returns

<RGBARecord>[];

interface RGBARecord {
  r: number;
  g: number;
  b: number;
  a: number;
}

🎨 extractImageDataFromSrc

Type: Function

Description: a utility function that extracts image data through writing an image source into a canvas context

⚙️ Params

• src <string>

  • an image src

• sizeDividend <number>

  • default set to 1
  • this is primarily for making the median cut algorithm more performant by reducing image size while keeping aspect ration in tact. Very large images require a lot of processing, so supplying a size dividend can speed up this palette generating process while keeping the final palette that is generated mostly unaffected within reason.
  • A custom implementation can utilize a size dividend by dividing the CANVAS.width and CANVAS.height by some number:

  const IMAGE = new Image();
  const CANVAS = document.createElement("canvas");
  
  IMAGE.src = src;
  
  await IMAGE.decode();
  
  CANVAS.width = IMAGE.width / sizeDividend;
  CANVAS.height = IMAGE.height / sizeDividend;

🚨 Calling getImageData on an Image that's loaded with a source that is cross-origin is known to create CORS issues via the tainted canvas error. This helper is here to simplify the process of getting image data, but a custom implementation of this may be a better solution for some. Things to note with this function is the resource server handling the requested image must include the response header: Access-Control-Allow-Origin.

🛑 If .quantize() is running too slow, reduce the size of the image as show above

🛠️ Usage

palette.extractImageDataFromSrc(imgData);

📦 Returns

<Uint8ClampedArray>;

🎨 monochromatic

Type: Function

Description:returns a monochromatic object with colors ranginng in a spectrum from dark to light

⚙️ Params

• d <Uint8ClampedArray>

  • value returned from a canvas context calling .getImageData().data

• numOfColors:

  • default set to 4
  • the amount of returned monochromatic colors

• rgb: {r: number, g: number, b: number}

  • an object containing the fields r, g, b

🛠️ Usage

const imgData = palette.extractImageDataFromSrc(imgURL, 3);

palette.monochromatic(imgData);

📦 Returns

<MonoChromatic>;

interface RGBARecord {
  r: number;
  g: number;
  b: number;
  a: number;
};

interface MonoChromatic {
  light: RGBARecord[];
  dark: RGBARecord[];
  original: RGBARecord;
};