pixel-bloom

pixel-bloom

pixel-bloom is a lightweight image filter for Node.js and the browser that adds a cinematic bloom or glow effect to images. It highlights bright areas, applies smooth blur, and blends the result back to produce soft, glowing highlights — ideal for creative, photo, or UI effects.

Features

✨ Apply threshold-based bloom/glow to any image or pixel buffer

⚡ Fast CPU implementation with separable Gaussian blur

💡 Configurable radius, intensity, blend mode, and threshold

🧠 Linear RGB aware blending for natural, filmic glow

🧩 Works with Node (Buffer), Canvas, or ImageData in browsers

🧰 Optional pipeline caching for batch or realtime processing

Installation

Using npm:

npm install pixel-bloom

Using Yarn:

yarn add pixel-bloom

Usage

Add the bloom effect to an image buffer or canvas:

import { applyBloom } from "pixel-bloom";
import { readFileSync, writeFileSync } from "node:fs";
import { decodePng, encodePng } from "some-png-lib"; // use your preferred decoder/encoder

const { data, width, height } = decodePng(readFileSync("input.png"));

const result = applyBloom(
  { data, width, height },
  {
    threshold: 0.8,      // only affect bright areas
    knee: 0.5,           // smooth transition around threshold
    intensity: 1.2,      // how strong the bloom appears
    radius: 20,          // blur radius (px)
    blendMode: "screen", // 'add' | 'screen' | 'plus-lighter'
    linearRGB: true,     // operate in linear color space
  }
);

writeFileSync("output.png", encodePng({ data: result, width, height }));

Browser Example

import { applyBloomToImageData } from "pixel-bloom";

const canvas = document.querySelector("canvas")!;
const ctx = canvas.getContext("2d")!;

const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const output = applyBloomToImageData(imageData, { radius: 16, intensity: 1.1 });

ctx.putImageData(output, 0, 0);

Configuration Options

Option	Type	Default	Description
threshold	number (0–1)	0.8	Luminance threshold for bloom extraction
knee	number (0–1)	0.5	Soft knee around threshold to avoid harsh cutoff
radius	number	16	Blur radius (px)
intensity	number	1.0	Strength of the bloom glow
blendMode	"add" | "screen" | "plus-lighter"	"screen"	Composition mode for blending bloom over base image
linearRGB	boolean	true	Enable linear RGB blending for realistic highlights
iterations	number	4	Number of blur passes (higher = smoother)
preserveAlpha	boolean	true	Keep the original alpha channel
quality	"auto" | "fast" | "best"	"auto"	Adjusts kernel size and blur precision

Example Output

[pixel-bloom] ✨ Applied bloom: radius=20, threshold=0.8, intensity=1.2
[pixel-bloom] 📷 Output image: 1920×1080, 14.8 ms

License

MIT © [nanti]

Contributing

Got ideas or improvements? Contributions are welcome! Feel free to open an issue or submit a PR.