Raxol.Terminal.Graphics.ImageProcessor (Raxol v2.0.1)

View Source

Comprehensive image processing pipeline for terminal graphics.

Provides advanced image processing capabilities including:

  • Multi-format support (PNG, JPEG, WebP, GIF, SVG)
  • Format detection and automatic conversion
  • Intelligent resizing and cropping
  • Color space conversion and optimization
  • Dithering for limited color terminals
  • Performance-optimized caching system
  • Batch processing capabilities

Supported Formats

  • PNG - Full transparency support
  • JPEG - High compression, no transparency
  • WebP - Modern format with excellent compression
  • GIF - Animation support, limited colors
  • SVG - Vector graphics (rasterized for terminal)
  • Raw RGB/RGBA - Direct pixel data

Usage

# Basic processing
{:ok, processed} = ImageProcessor.process_image(image_data, %{
  width: 300,
  height: 200,
  format: :auto,
  quality: 90
})

# Batch processing
{:ok, results} = ImageProcessor.process_batch(images, processing_options)

# Format conversion
{:ok, converted} = ImageProcessor.convert_format(image_data, :png, :webp)

Summary

Types

color_mode()
dither_method()
image_format()
processed_image()
processing_options()
resize_method()

Functions

convert_format(image_data, source_format, target_format, options \\ %{})

Converts an image from one format to another.

detect_format(image_data)

Detects the format of image data.

get_image_metadata(image_data)

Gets comprehensive metadata about an image.

optimize_for_terminals(image_data, terminal_profiles, base_options \\ %{})

Creates optimized versions of an image for different terminal capabilities.

process_batch(images, shared_options \\ %{})

Processes multiple images in batch with shared options.

process_image(image_data, options \\ %{})

Processes an image with the given options.

Types

color_mode()

@type color_mode() :: :rgb | :rgba | :grayscale | :palette | :bilevel

dither_method()

@type dither_method() :: :none | :riemersma | :floyd_steinberg | :ordered

image_format()

@type image_format() :: :png | :jpeg | :webp | :gif | :svg | :rgb | :rgba | :auto

processed_image()

@type processed_image() :: %{
  data: binary(),
  format: image_format(),
  width: non_neg_integer(),
  height: non_neg_integer(),
  color_mode: color_mode(),
  metadata: map()
}

processing_options()

@type processing_options() :: %{
  optional(:width) => non_neg_integer(),
  optional(:height) => non_neg_integer(),
  optional(:format) => image_format(),
  optional(:quality) => 1..100,
  optional(:compression) => 1..9,
  optional(:color_mode) => color_mode(),
  optional(:dither) => dither_method(),
  optional(:resize_method) => resize_method(),
  optional(:preserve_aspect) => boolean(),
  optional(:background_color) => String.t(),
  optional(:optimize_for_terminal) => boolean(),
  optional(:max_colors) => pos_integer(),
  optional(:cache_key) => String.t()
}

resize_method()

@type resize_method() :: :nearest | :bilinear | :bicubic | :lanczos

Functions

convert_format(image_data, source_format, target_format, options \\ %{})

@spec convert_format(
  binary(),
  image_format(),
  image_format(),
  processing_options()
) :: {:ok, binary()} | {:error, term()}

Converts an image from one format to another.

Parameters

  • image_data - Source image data
  • source_format - Source image format (or :auto for detection)
  • target_format - Target image format
  • options - Conversion options

Returns

  • {:ok, converted_data} - Successfully converted image
  • {:error, reason} - Conversion failed

detect_format(image_data)

@spec detect_format(binary() | String.t()) :: {:ok, image_format()} | {:error, term()}

Detects the format of image data.

Uses both file signature detection and filename extension analysis for accurate format identification.

Parameters

  • image_data - Binary image data or file path

Returns

  • {:ok, format} - Detected image format
  • {:error, reason} - Detection failed

get_image_metadata(image_data)

@spec get_image_metadata(binary() | String.t()) :: {:ok, map()} | {:error, term()}

Gets comprehensive metadata about an image.

Parameters

  • image_data - Image data to analyze

Returns

  • {:ok, metadata} - Image metadata map
  • {:error, reason} - Analysis failed

optimize_for_terminals(image_data, terminal_profiles, base_options \\ %{})

@spec optimize_for_terminals(binary(), [map()], processing_options()) ::
  {:ok, %{required(atom()) => processed_image()}} | {:error, term()}

Creates optimized versions of an image for different terminal capabilities.

Generates multiple variants optimized for different terminal types and capabilities (color depth, animation support, etc.).

Parameters

  • image_data - Source image data
  • terminal_profiles - List of terminal capability profiles
  • base_options - Base processing options

Returns

  • {:ok, %{profile_name => processed_image}} - Map of optimized variants
  • {:error, reason} - Optimization failed

process_batch(images, shared_options \\ %{})

@spec process_batch(
  [binary() | String.t() | {binary(), processing_options()}],
  processing_options()
) :: {:ok, [processed_image()]} | {:error, term()}

Processes multiple images in batch with shared options.

Optimizes performance by reusing processing contexts and applying batch optimizations where possible.

Parameters

  • images - List of image data (binary or file paths) or tuples {data, options}
  • shared_options - Options applied to all images

Returns

  • {:ok, [processed_image]} - List of successfully processed images
  • {:error, reason} - Batch processing error

process_image(image_data, options \\ %{})

@spec process_image(binary() | String.t(), processing_options()) ::
  {:ok, processed_image()} | {:error, term()}

Processes an image with the given options.

Parameters

  • image_data - Binary image data or file path
  • options - Processing options map

Returns

  • {:ok, processed_image} - Successfully processed image
  • {:error, reason} - Processing error

Examples

# Process PNG with resizing
{:ok, processed} = ImageProcessor.process_image(png_data, %{
  width: 400,
  height: 300,
  format: :png,
  optimize_for_terminal: true
})

# Auto-detect format and optimize
{:ok, processed} = ImageProcessor.process_image(image_data, %{
  width: 200,
  height: 200,
  format: :auto,
  dither: :floyd_steinberg,
  max_colors: 64
})