Skip to main content
These are free functions that don’t require a Composition instance. They’re useful for color manipulation outside of the main image compositing workflow.

​
Color Conversion

​
hexToRgb()

Parse a hex color string to RGB.
​
hex
string
required
Hex color string (e.g., “#ff8000” or “ff8000”)
​
rgb
Promise<Uint8Array>
RGB values as Uint8Array [r, g, b]
import { hexToRgb } from '@iamkaf/kimg';

const rgb = await hexToRgb('#ff8000');
// Uint8Array [255, 128, 0]

​
rgbToHex()

Convert RGB values to a hex color string.
​
r
number
required
Red channel (0-255)
​
g
number
required
Green channel (0-255)
​
b
number
required
Blue channel (0-255)
Alternatively, pass an RGB object:
​
rgb
RgbColor
​
hex
Promise<string>
Hex color string (e.g., “#ff8000”)
import { rgbToHex } from '@iamkaf/kimg';

const hex = await rgbToHex(255, 128, 0);
// '#ff8000'

// or
const hex = await rgbToHex({ r: 255, g: 128, b: 0 });

​
WCAG Color Analysis

​
relativeLuminance()

Calculate WCAG 2.x relative luminance for a hex color.
​
hex
string
required
Hex color string
​
luminance
Promise<number>
Relative luminance value (0-1)
import { relativeLuminance } from '@iamkaf/kimg';

const lum = await relativeLuminance('#3b82f6');
// 0.2355

​
contrastRatio()

Calculate WCAG 2.x contrast ratio between two hex colors.
​
a
string
required
First hex color string
​
b
string
required
Second hex color string
​
ratio
Promise<number>
Contrast ratio (1.0-21.0)
import { contrastRatio } from '@iamkaf/kimg';

const ratio = await contrastRatio('#ffffff', '#000000');
// 21.0 (maximum contrast)

const ratio2 = await contrastRatio('#3b82f6', '#ffffff');
// 3.46
WCAG 2.1 requires:
  • AA normal text: ratio ≥ 4.5
  • AA large text: ratio ≥ 3.0
  • AAA normal text: ratio ≥ 7.0
  • AAA large text: ratio ≥ 4.5

​
Dominant Color

​
dominantRgbFromRgba()

Extract the dominant color from raw RGBA pixel data.
​
data
ByteInput
required
Raw RGBA pixel data
​
width
number
required
Image width in pixels
​
height
number
required
Image height in pixels
Alternatively, pass an options object:
​
options
GeometryOptions
​
rgb
Promise<Uint8Array>
Dominant RGB color as Uint8Array [r, g, b]
import { dominantRgbFromRgba } from '@iamkaf/kimg';

const dominant = await dominantRgbFromRgba(pixels, 128, 128);
// or
const dominant = await dominantRgbFromRgba(pixels, { width: 128, height: 128 });
// Uint8Array [r, g, b]

​
Readable Text Color

From the @iamkaf/kimg/color-utils subpath (pure JS, no WASM):

​
readableTextColor()

Determine whether black or white text is more readable on a given background color.
​
backgroundColor
string
required
Background hex color string
​
textColor
string
Either “#000000” (black) or “#ffffff” (white)
import { readableTextColor } from '@iamkaf/kimg/color-utils';

readableTextColor('#1a1a2e'); // '#ffffff'
readableTextColor('#f0f0f0'); // '#000000'
readableTextColor('#3b82f6'); // '#ffffff'

​
Base64 Helpers

From the @iamkaf/kimg/base64 subpath (pure JS, no WASM):

​
rgbaToBase64()

Encode RGBA pixel data as a base64 string.
​
rgba
Uint8Array
required
Raw RGBA pixel data
​
base64
string
Base64-encoded string
import { rgbaToBase64 } from '@iamkaf/kimg/base64';

const base64 = rgbaToBase64(pixels);

​
base64ToRgba()

Decode a base64 string to RGBA pixel data.
​
base64
string
required
Base64-encoded string
​
rgba
Uint8Array
Raw RGBA pixel data
import { base64ToRgba } from '@iamkaf/kimg/base64';

const pixels = base64ToRgba(base64String);

​
Advanced Color Utilities

​
extractPaletteFromRgba()

Extract a color palette from raw RGBA pixel data.
​
data
ByteInput
required
Raw RGBA pixel data
​
width
number
required
Image width in pixels
​
height
number
required
Image height in pixels
​
maxColors
number
required
Maximum number of colors to extract
Alternatively, pass an options object:
​
options
GeometryWithMaxColorsOptions
​
palette
Promise<Uint8Array>
Flat RGBA palette data [r, g, b, a, r, g, b, a, …]
import { extractPaletteFromRgba } from '@iamkaf/kimg';

const palette = await extractPaletteFromRgba(pixels, 128, 128, 16);
// or
const palette = await extractPaletteFromRgba(pixels, {
  width: 128,
  height: 128,
  maxColors: 16
});

​
quantizeRgba()

Quantize raw RGBA pixel data to a specific palette.
​
data
ByteInput
required
Raw RGBA pixel data
​
width
number
required
Image width in pixels
​
height
number
required
Image height in pixels
​
palette
ByteInput
required
Flat RGBA palette data
Alternatively, pass an options object:
​
options
GeometryWithPaletteOptions
​
rgba
Promise<Uint8Array>
Quantized RGBA pixel data
import { quantizeRgba } from '@iamkaf/kimg';

const quantized = await quantizeRgba(pixels, 128, 128, palette);
// or
const quantized = await quantizeRgba(pixels, {
  width: 128,
  height: 128,
  palette
});

​
histogramRgba()

Compute a per-channel histogram for raw RGBA pixel data.
​
data
ByteInput
required
Raw RGBA pixel data
​
width
number
required
Image width in pixels
​
height
number
required
Image height in pixels
Alternatively, pass an options object:
​
options
GeometryOptions
​
histogram
Promise<Uint32Array>
Flat array of 1024 u32 values: r[0..256], g[256..512], b[512..768], a[768..1024]
import { histogramRgba } from '@iamkaf/kimg';

const hist = await histogramRgba(pixels, 128, 128);
// or
const hist = await histogramRgba(pixels, { width: 128, height: 128 });

// Access channels:
const redChannel = hist.slice(0, 256);
const greenChannel = hist.slice(256, 512);
const blueChannel = hist.slice(512, 768);
const alphaChannel = hist.slice(768, 1024);

​
Image Format Utilities

​
decodeImage()

Auto-detect and decode an image from bytes to raw RGBA pixel data.
​
data
ByteInput
required
Image file bytes (supports PNG, JPEG, WebP, GIF)
​
rgba
Promise<Uint8Array>
Decoded RGBA pixel data (without width/height metadata)
import { decodeImage } from '@iamkaf/kimg';

const rgba = await decodeImage(imageBytes);
The returned RGBA data does not include width/height information. Use detectFormat() first if you need dimensions, or use the composition’s importImage() method instead.

​
detectFormat()

Detect the image format from magic bytes.
​
data
ByteInput
required
Image file bytes
​
format
Promise<string>
Detected format: “png”, “jpeg”, “webp”, “gif”, “psd”, or “unknown”
import { detectFormat } from '@iamkaf/kimg';

const format = await detectFormat(imageBytes);
// "png", "jpeg", "webp", "gif", "psd", or "unknown"

​
WASM Runtime Utilities

​
simdSupported()

Check if the current environment supports WebAssembly SIMD (simd128).
​
supported
boolean
True if SIMD is supported and available
import { simdSupported } from '@iamkaf/kimg';

if (simdSupported()) {
  console.log('SIMD-optimized WASM will be used');
} else {
  console.log('Baseline WASM will be used');
}
kimg automatically loads the appropriate WASM binary (baseline or SIMD) based on runtime support. This function is primarily useful for diagnostics and performance reporting.

Build docs developers (and LLMs) love

Get started for freeTalk to us