gif-tools
Version:
A robust, zero-dependency TypeScript library for creating GIF files with support for both static and animated GIFs. Built with modern TypeScript features and designed to work in both Node.js and browser environments.
346 lines (345 loc) • 11.5 kB
TypeScript
/**
* Helper functions for common GIF creation tasks
*
* This module provides convenient, high-level functions for creating GIFs
* without needing to work with low-level GIF writing details.
*/
import { ImageData, ImageOptions, GlobalColorTableOptions, RGBColor } from './types.js';
import { GifResult } from './gif-result.js';
/**
* Creates a static GIF from image data using automatic color quantization.
*
* This is the most flexible static GIF creation function, accepting raw RGBA
* image data and automatically quantizing colors to fit GIF's palette limitations.
*
* @param imageData - The source image data in RGBA format
* @param imageData.width - Image width in pixels
* @param imageData.height - Image height in pixels
* @param imageData.data - RGBA pixel data as Uint8Array or Uint8ClampedArray
* @param options - Optional configuration
* @param options.maxColors - Maximum colors in quantized palette (default: 256)
* @param options.globalColorTable - Global color table options
* @param options.imageOptions - Image-specific options (position, delay, etc.)
* @returns A GifResult with convenient output methods
* @throws {GifValidationError} When image data is invalid
*
* @example
* ```typescript
* // Create from canvas ImageData
* const canvas = document.createElement('canvas');
* const ctx = canvas.getContext('2d');
* const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
* const gif = createStaticGif(imageData);
*
* // Save or use the result
* const dataUrl = gif.toDataURL();
* await gif.saveToFile('output.gif');
* ```
*
* @example
* ```typescript
* // Create with custom options
* const gif = createStaticGif(imageData, {
* maxColors: 128,
* imageOptions: { delay: 0 }
* });
* ```
*/
export declare function createStaticGif(imageData: ImageData, options?: {
maxColors?: number;
globalColorTable?: GlobalColorTableOptions;
imageOptions?: ImageOptions;
}): GifResult;
/**
* Creates an animated GIF from multiple image frames.
*
* Processes multiple frames into a single animated GIF with consistent color
* quantization across all frames. All frames are quantized using a unified
* palette for optimal color consistency.
*
* @param frames - Array of image frames in RGBA format
* @param options - Optional configuration
* @param options.maxColors - Maximum colors in shared palette (default: 256)
* @param options.delay - Delay between frames in milliseconds (default: 100)
* @param options.loops - Number of animation loops, 0 for infinite (default: 0)
* @param options.globalColorTable - Global color table options
* @param options.imageOptions - Per-frame image options array
* @returns A GifResult with convenient output methods
* @throws {GifValidationError} When no frames provided or frames are invalid
*
* @example
* ```typescript
* const frames = [frame1, frame2, frame3]; // ImageData objects
* const animatedGif = createAnimatedGif(frames, {
* delay: 200,
* loops: 0 // infinite loop
* });
* animatedGif.download('animation.gif');
* ```
*
* @example
* ```typescript
* // Different delay for each frame
* const gif = createAnimatedGif(frames, {
* imageOptions: [
* { delay: 100 },
* { delay: 200 },
* { delay: 150 }
* ]
* });
* ```
*/
export declare function createAnimatedGif(frames: ImageData[], options?: {
maxColors?: number;
delay?: number;
loops?: number;
globalColorTable?: GlobalColorTableOptions;
imageOptions?: ImageOptions[];
}): GifResult;
/**
* Creates a solid color GIF of the specified dimensions.
*
* This is the simplest way to create a GIF filled with a single color.
* Perfect for backgrounds, placeholders, or testing.
*
* @param width - Image width in pixels (1-65535)
* @param height - Image height in pixels (1-65535)
* @param color - RGB color values
* @param color.red - Red component (0-255)
* @param color.green - Green component (0-255)
* @param color.blue - Blue component (0-255)
* @returns A GifResult with convenient output methods
* @throws {GifValidationError} When dimensions or color values are invalid
*
* @example
* ```typescript
* // Create a red 100x100 square
* const redSquare = createSolidColorGif(100, 100, {
* red: 255,
* green: 0,
* blue: 0
* });
*
* // Use the GIF
* document.body.innerHTML = `<img src="${redSquare.toDataURL()}">`;
* ```
*
* @example
* ```typescript
* // Create a blue background
* const background = createSolidColorGif(800, 600, {
* red: 70,
* green: 130,
* blue: 180 // Steel blue
* });
* ```
*/
export declare function createSolidColorGif(width: number, height: number, color: RGBColor): GifResult;
/**
* Creates a checkerboard pattern GIF with alternating colors.
*
* Generates a classic checkerboard pattern with customizable colors and
* check size. Useful for backgrounds, patterns, or testing.
*
* @param width - Image width in pixels
* @param height - Image height in pixels
* @param color1 - First alternating color (RGB)
* @param color2 - Second alternating color (RGB)
* @param checkSize - Size of each check square in pixels (default: 10)
* @returns A GifResult with convenient output methods
* @throws {GifValidationError} When dimensions or colors are invalid
*
* @example
* ```typescript
* // Classic black and white checkerboard
* const checkerboard = createCheckerboardGif(
* 200, 200,
* { red: 0, green: 0, blue: 0 }, // Black
* { red: 255, green: 255, blue: 255 }, // White
* 20 // 20px squares
* );
* ```
*
* @example
* ```typescript
* // Colorful small checkerboard
* const colorCheck = createCheckerboardGif(
* 300, 200,
* { red: 255, green: 100, blue: 100 }, // Light red
* { red: 100, green: 100, blue: 255 }, // Light blue
* 5 // Small 5px checks
* );
* ```
*/
export declare function createCheckerboardGif(width: number, height: number, color1: RGBColor, color2: RGBColor, checkSize?: number): GifResult;
/**
* Converts an HTML Canvas element to ImageData format.
*
* Extracts pixel data from a canvas element in the format needed for GIF creation.
* This is a convenient bridge between Canvas API and GIF generation.
*
* @param canvas - HTML Canvas element to convert
* @returns ImageData object with width, height, and RGBA pixel data
* @throws {GifValidationError} When canvas context cannot be obtained
*
* @example
* ```typescript
* // Draw on canvas and convert to GIF
* const canvas = document.createElement('canvas');
* canvas.width = 200;
* canvas.height = 100;
* const ctx = canvas.getContext('2d');
*
* // Draw something
* ctx.fillStyle = 'blue';
* ctx.fillRect(0, 0, 200, 100);
* ctx.fillStyle = 'red';
* ctx.fillRect(50, 25, 100, 50);
*
* // Convert to GIF
* const imageData = canvasToImageData(canvas);
* const gif = createStaticGif(imageData);
* ```
*/
export declare function canvasToImageData(canvas: HTMLCanvasElement): ImageData;
/**
* Creates ImageData from raw RGBA pixel data.
*
* Constructs an ImageData object from raw pixel data, with validation
* to ensure data length matches dimensions.
*
* @param width - Image width in pixels
* @param height - Image height in pixels
* @param data - RGBA pixel data (4 bytes per pixel)
* @returns ImageData object ready for GIF creation
* @throws {GifValidationError} When data length doesn't match dimensions
*
* @example
* ```typescript
* // Create a simple 2x2 image
* const width = 2, height = 2;
* const data = new Uint8Array([
* 255, 0, 0, 255, // Red pixel
* 0, 255, 0, 255, // Green pixel
* 0, 0, 255, 255, // Blue pixel
* 255, 255, 0, 255 // Yellow pixel
* ]);
*
* const imageData = createImageData(width, height, data);
* const gif = createStaticGif(imageData);
* ```
*/
export declare function createImageData(width: number, height: number, data: Uint8Array | Uint8ClampedArray): ImageData;
/**
* Creates a gradient GIF with smooth color transition.
*
* Generates a linear gradient between two colors in the specified direction.
* Perfect for backgrounds, UI elements, or artistic effects.
*
* @param width - Image width in pixels
* @param height - Image height in pixels
* @param startColor - Starting gradient color (RGB)
* @param endColor - Ending gradient color (RGB)
* @param direction - Gradient direction (default: 'horizontal')
* @returns A GifResult with convenient output methods
*
* @example
* ```typescript
* // Horizontal red to blue gradient
* const gradient = createGradientGif(
* 300, 100,
* { red: 255, green: 0, blue: 0 }, // Red
* { red: 0, green: 0, blue: 255 }, // Blue
* 'horizontal'
* );
* ```
*
* @example
* ```typescript
* // Vertical sunset gradient
* const sunset = createGradientGif(
* 200, 300,
* { red: 255, green: 94, blue: 77 }, // Coral
* { red: 255, green: 154, blue: 0 }, // Orange
* 'vertical'
* );
* ```
*/
export declare function createGradientGif(width: number, height: number, startColor: RGBColor, endColor: RGBColor, direction?: 'horizontal' | 'vertical' | 'diagonal'): GifResult;
/**
* Creates an animated gradient GIF with dynamic effects.
*
* Generates an animated gradient with various animation types including
* shifting, rotating colors, pulsing, and wave effects. Perfect for
* dynamic backgrounds and eye-catching animations.
*
* @param width - Image width in pixels
* @param height - Image height in pixels
* @param startColor - Starting gradient color (RGB)
* @param endColor - Ending gradient color (RGB)
* @param options - Animation configuration
* @param options.direction - Gradient direction (default: 'horizontal')
* @param options.animationType - Type of animation (default: 'shift')
* @param options.frames - Number of animation frames (default: 20)
* @param options.delay - Delay between frames in ms (default: 100)
* @param options.loops - Animation loops, 0 for infinite (default: 0)
* @param options.intensity - Animation strength 0-1 (default: 1.0)
* @param options.maxColors - Maximum colors in palette (default: 256)
* @returns A GifResult with convenient output methods
*
* @example
* ```typescript
* // Shifting gradient animation
* const shiftingGradient = createAnimatedGradientGif(
* 200, 100,
* { red: 255, green: 0, blue: 0 },
* { red: 0, green: 0, blue: 255 },
* {
* animationType: 'shift',
* frames: 30,
* delay: 80
* }
* );
* ```
*
* @example
* ```typescript
* // Pulsing gradient with custom intensity
* const pulsingGradient = createAnimatedGradientGif(
* 150, 150,
* { red: 0, green: 255, blue: 0 },
* { red: 255, green: 0, blue: 255 },
* {
* direction: 'diagonal',
* animationType: 'pulse',
* intensity: 0.7,
* frames: 25
* }
* );
* ```
*
* @example
* ```typescript
* // Wave effect gradient
* const waveGradient = createAnimatedGradientGif(
* 300, 200,
* { red: 255, green: 255, blue: 0 },
* { red: 0, green: 255, blue: 255 },
* {
* animationType: 'wave',
* direction: 'vertical',
* frames: 40,
* delay: 60
* }
* );
* ```
*/
export declare function createAnimatedGradientGif(width: number, height: number, startColor: RGBColor, endColor: RGBColor, options?: {
direction?: 'horizontal' | 'vertical' | 'diagonal';
animationType?: 'shift' | 'rotate' | 'pulse' | 'wave';
frames?: number;
delay?: number;
loops?: number;
intensity?: number;
maxColors?: number;
}): GifResult;