ChunkyPNG

https://github.com/wvanbergen/chunky_png
Admin
ChunkyPNG is a pure Ruby library for reading and writing PNG files with support for all color modes,...
Tokens:15,709
Snippets:192
Trust Score:8.2
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Constraint Hash

Source: https://github.com/wvanbergen/chunky_png/wiki/Constraints

This shows an example of a hash used to specify compression constraints.

```ruby
{:compression => Zlib::BEST_COMPRESSION}
```

--------------------------------

### Saving a TRUECOLOR 24-bit Image with Transparency

Source: https://github.com/wvanbergen/chunky_png/wiki/Constraints

This example demonstrates saving a TRUECOLOR 24-bit image with a transparent pixel using specific encoding constraints. It includes setting the color mode, compression, and filtering, and manually adding a transparency chunk.

```ruby
cv = ChunkyPNG::Image.from_rgb_stream(width, height, buffer)
ds = cv.to_datastream(color_mode: ChunkyPNG::COLOR_TRUECOLOR, compression: Zlib::BEST_COMPRESSION, filtering: ChunkyPNG::FILTER_PAETH)
pixel = [0,0,0,0,0,0] # color black
ds.transparency_chunk = ChunkyPNG::Chunk::Transparency.new "tRNS", pixel.pack("C*")
ds.save("out.png")
```

--------------------------------

### Run Benchmarks Across Multiple Ruby Interpreters

Source: https://github.com/wvanbergen/chunky_png/blob/master/BENCHMARKING.rdoc

Use RVM to execute benchmarks across different Ruby interpreters. Ensure chunky_png is installed for each interpreter.

```bash
rvm 1.8.7,1.9.3,rbx bundle exec rake benchmark N=10
```

--------------------------------

### Image Resampling and Resizing with ChunkyPNG

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Demonstrates resizing images using nearest-neighbor and bilinear interpolation algorithms. Includes in-place variants and convenience aliases. Requires 'chunky_png' and an image file.

```ruby
require 'chunky_png'

img = ChunkyPNG::Image.from_file('photo.png')

# Nearest-neighbor (alias: resample, resize) — returns new canvas
thumb_nn = img.resample_nearest_neighbor(100, 100)

# Bilinear interpolation — smoother, returns new canvas
thumb_bl = img.resample_bilinear(100, 100)

# In-place variants
img.resample_nearest_neighbor!(50, 50)
img.resample_bilinear!(200, 200)

# Convenience aliases
img.resample(128, 128)   # nearest neighbor
img.resize(128, 128)     # same alias

img.save('resized.png')
```

--------------------------------

### Run All Benchmarks with Custom Iterations

Source: https://github.com/wvanbergen/chunky_png/blob/master/BENCHMARKING.rdoc

Run all benchmarks with a specified number of iterations using the N environment variable.

```bash
bundle exec rake benchmark N=10
```

--------------------------------

### Create and Save PNG Image

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Demonstrates creating a new image, setting individual pixels with different color formats, and saving the image with various encoding presets. Requires 'chunky_png' gem.

```ruby
require 'chunky_png'

# Create a 200x200 transparent canvas
img = ChunkyPNG::Image.new(200, 200, ChunkyPNG::Color::TRANSPARENT)

# Set individual pixels
img[10, 10] = ChunkyPNG::Color.rgba(255, 0, 0, 255)       # opaque red
img[11, 10] = ChunkyPNG::Color('black @ 0.5')              # 50% transparent black
img[12, 10] = ChunkyPNG::Color.from_hex('#00ff00')         # opaque green
img[13, 10] = ChunkyPNG::Color('royalblue')                # HTML named color

# Read a pixel back
pixel = img[10, 10]
puts ChunkyPNG::Color.r(pixel)  # => 255
puts ChunkyPNG::Color.g(pixel)  # => 0
puts ChunkyPNG::Color.a(pixel)  # => 255

# Save with different presets
img.save('output.png')                        # auto-detect best encoding
img.save('fast.png', :fast_rgba)              # fastest save, RGBA mode
img.save('small.png', :best_compression)      # Zlib::BEST_COMPRESSION + Paeth filter
img.save('interlaced.png', interlace: true)   # Adam7 interlaced
```

--------------------------------

### Create and Save PNG Image

Source: https://github.com/wvanbergen/chunky_png/blob/master/README.md

Demonstrates creating a new PNG image, setting pixel colors using different formats, and saving it with interlacing enabled. Requires 'chunky_png' to be required.

```ruby
require 'chunky_png'

# Creating an image from scratch, save as an interlaced PNG
png = ChunkyPNG::Image.new(16, 16, ChunkyPNG::Color::TRANSPARENT)
png[1,1] = ChunkyPNG::Color::rgba(10, 20, 30, 128)
png[2,1] = ChunkyPNG::Color('black @ 0.5')
png.save('filename.png', :interlace => true)
```

--------------------------------

### Read and Write PNG Metadata

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Demonstrates how to read existing metadata from a PNG file and how to write new or updated metadata to a PNG file. Metadata is stored as a hash.

```ruby
img = ChunkyPNG::Image.from_file('with_metadata.png')
puts img.metadata['Title']    # => "My Photo"
puts img.metadata['Author']   # => "Jane Doe"
puts img.metadata.inspect     # => {"Title"=>"My Photo", "Author"=>"Jane Doe"}
```

```ruby
img.metadata['Title']   = 'Updated Title'
img.metadata['Author']  = 'Willem van Bergen'
img.metadata['Comment'] = 'Generated by ChunkyPNG'
img.save('with_metadata.png')
```

```ruby
img2 = ChunkyPNG::Image.new(100, 100, ChunkyPNG::Color::WHITE, {
  'Title'  => 'New Image',
  'Source' => 'ChunkyPNG demo'
})
img2.save('new_with_meta.png')
```

--------------------------------

### Create and Save PNG Image

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/index.md

Demonstrates creating a new PNG image, setting pixel colors, and saving it with interlacing enabled. Supports RGBA color values and a shorthand for semi-transparent black.

```ruby
require 'chunky_png'

# Creating an image from scratch, save as an interlaced PNG
png = ChunkyPNG::Image.new(16, 16, ChunkyPNG::Color::TRANSPARENT)
png[1,1] = ChunkyPNG::Color::rgba(10, 20, 30, 128)
png[2,1] = ChunkyPNG::Color::rgba(0, 0, 0, 128)
png.save('filename.png', :interlace => true)
```

--------------------------------

### Load PNG Image from Various Sources

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Shows how to load PNG images from a file path, a binary string, or an IO stream. Includes re-exporting to a blob and basic error handling for invalid or unsupported PNGs. Requires 'chunky_png' gem.

```ruby
require 'chunky_png'

# From a file path
img = ChunkyPNG::Image.from_file('photo.png')
puts "#{img.width}x#{img.height}"   # e.g. "800x600"

# From a binary string (e.g. from HTTP response body)
png_data = File.binread('photo.png')
img = ChunkyPNG::Image.from_blob(png_data)

# From an IO stream
File.open('photo.png', 'rb') do |f|
  img = ChunkyPNG::Image.from_io(f)
end

# Re-export to a blob
blob = img.to_blob
puts blob.bytesize   # size in bytes of the re-encoded PNG

# Error handling
begin
  bad = ChunkyPNG::Image.from_file('not_a_png.jpg')
rescue ChunkyPNG::SignatureMismatch => e
  puts "Not a PNG: #{e.message}"
rescue ChunkyPNG::NotSupported => e
  puts "Unsupported PNG feature: #{e.message}"
end
```

--------------------------------

### Construct and Parse Colors

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Illustrates how to create and parse colors using `ChunkyPNG::Color` and the `ChunkyPNG.Color()` factory method. Covers RGBA, RGB, grayscale, hex strings, named colors, and component extraction. Requires 'chunky_png' gem.

```ruby
require 'chunky_png'

# Construction
rgba  = ChunkyPNG::Color.rgba(255, 128, 0, 200)   # r,g,b,a components
rgb   = ChunkyPNG::Color.rgb(0, 0, 255)            # fully opaque blue
gray  = ChunkyPNG::Color.grayscale(128)             # mid-gray, fully opaque
ga    = ChunkyPNG::Color.grayscale_alpha(128, 64)  # semi-transparent gray

# Parsing (factory shorthand)
c1 = ChunkyPNG::Color('#ff8800')          # 6-digit hex → opaque
c2 = ChunkyPNG::Color('#ff8800cc')        # 8-digit hex → with alpha
c3 = ChunkyPNG::Color('#f80')             # 3-digit hex
c4 = ChunkyPNG::Color('tomato')           # HTML named color
c5 = ChunkyPNG::Color('red @ 0.5')        # named color + opacity
c6 = ChunkyPNG::Color(255, 0, 0, 128)     # r,g,b,a

# Component extraction
puts ChunkyPNG::Color.r(c6)   # => 255
puts ChunkyPNG::Color.g(c6)   # => 0
puts ChunkyPNG::Color.b(c6)   # => 0
puts ChunkyPNG::Color.a(c6)   # => 128

# Predicates
ChunkyPNG::Color.opaque?(rgb)           # => true
ChunkyPNG::Color.fully_transparent?(ChunkyPNG::Color::TRANSPARENT)  # => true
ChunkyPNG::Color.grayscale?(gray)       # => true

# Conversions
puts ChunkyPNG::Color.to_hex(c1)          # => "#ff8800ff"
puts ChunkyPNG::Color.to_hex(c1, false)   # => "#ff8800"
hsl = ChunkyPNG::Color.to_hsl(c1)         # => [hue, saturation, lightness]
hsv = ChunkyPNG::Color.to_hsv(c1, true)   # => [hue, saturation, value, alpha]
```

--------------------------------

### Drawing Primitives with ChunkyPNG

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Illustrates drawing anti-aliased lines, rectangles, circles, polygons, and Bézier curves onto a canvas. Includes alpha blending for pixel composition. Requires 'chunky_png' and an image object.

```ruby
require 'chunky_png'

img = ChunkyPNG::Image.new(400, 400, ChunkyPNG::Color::WHITE)

red   = ChunkyPNG::Color('red')
blue  = ChunkyPNG::Color('blue')
green = ChunkyPNG::Color('green')
semi  = ChunkyPNG::Color.rgba(0, 0, 255, 128)

# Anti-aliased line (x0, y0, x1, y1, color)
img.line(10, 10, 390, 390, red)

# Rectangle with stroke and optional fill (x0, y0, x1, y1, stroke, fill)
img.rect(20, 20, 200, 100, blue, ChunkyPNG::Color('lightyellow'))

# Circle with stroke and optional fill (cx, cy, radius, stroke, fill)
img.circle(200, 200, 80, green, semi)

# Polygon: array of [x,y] pairs, or a ChunkyPNG::Vector string, stroke + fill
img.polygon([[50, 300], [150, 200], [250, 300], [200, 380], [100, 380]],
            red, ChunkyPNG::Color('lightsalmon'))

# Bézier curve: array of control points
img.bezier_curve([[10, 390], [100, 100], [300, 100], [390, 390]], blue)

# Compose a pixel with alpha blending (does not simply overwrite)
img.compose_pixel(100, 100, ChunkyPNG::Color.rgba(255, 0, 0, 128))

img.save('drawing.png')
```

--------------------------------

### Run Encoding Benchmark

Source: https://github.com/wvanbergen/chunky_png/blob/master/BENCHMARKING.rdoc

Execute the encoding benchmark for ChunkyPNG. The number of runs can be specified using the N environment variable.

```bash
bundle exec rake benchmark:encoding
```

--------------------------------

### Run Decoding Benchmark

Source: https://github.com/wvanbergen/chunky_png/blob/master/BENCHMARKING.rdoc

Execute the decoding benchmark for ChunkyPNG. The number of runs can be specified using the N environment variable.

```bash
bundle exec rake benchmark:decoding
```

--------------------------------

### Alpha Compositing and Color Blending in ChunkyPNG

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Demonstrates various color manipulation functions provided by ChunkyPNG, including alpha compositing (fast and precise), blending, color interpolation, fading, grayscale conversion, and Euclidean distance calculation. Ensure 'chunky_png' is required before use.

```ruby
require 'chunky_png'

fg = ChunkyPNG::Color.rgba(255, 0, 0, 128)   # semi-transparent red
bg = ChunkyPNG::Color.rgb(255, 255, 255)      # white

# Alpha-composite fg over bg (fast integer math)
result = ChunkyPNG::Color.compose(fg, bg)
# => equivalent to compose_quick

# High-precision float version
result_precise = ChunkyPNG::Color.compose_precise(fg, bg)

# Average blend (no alpha consideration)
blended = ChunkyPNG::Color.blend(fg, bg)

# Interpolate between two colors by alpha factor (0=bg, 255=fg)
interp = ChunkyPNG::Color.interpolate_quick(fg, bg, 64)

# Reduce opacity by a factor (0=fully transparent, 255=unchanged)
faded = ChunkyPNG::Color.fade(fg, 100)

# Convert to grayscale
gray_color = ChunkyPNG::Color.to_grayscale(result)

# Euclidean distance in RGBA space
dist = ChunkyPNG::Color.euclidean_distance_rgba(fg, bg)
puts dist   # Float, max ~441.67
```

--------------------------------

### Import PNG from Raw Pixel Streams

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Enables creating ChunkyPNG canvases directly from raw binary pixel data in various byte orders (RGB, RGBA, BGR, ABGR). Useful for interoperability.

```ruby
require 'chunky_png'

width, height = 320, 240

# From an RGB stream (3 bytes per pixel)
rgb_data = File.binread('frame.raw')
canvas = ChunkyPNG::Canvas.from_rgb_stream(width, height, rgb_data)
```

```ruby
# From an RGBA stream (4 bytes per pixel, matching ChunkyPNG's internal format)
rgba_data = File.binread('frame_rgba.raw')
canvas = ChunkyPNG::Canvas.from_rgba_stream(width, height, rgba_data)
```

```ruby
# From a BGR stream (OpenCV default order)
bgr_data = File.binread('opencv_frame.raw')
canvas = ChunkyPNG::Canvas.from_bgr_stream(width, height, bgr_data)
```

```ruby
# From an ABGR stream (some GPU/framebuffer formats)
abgr_data = File.binread('abgr_frame.raw')
canvas = ChunkyPNG::Canvas.from_abgr_stream(width, height, abgr_data)

canvas.save('from_raw.png')
```

--------------------------------

### HSL/HSV Color Construction and Distance

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Demonstrates creating colors using HSL and HSV color spaces and calculating the Euclidean distance between two RGBA colors. Ensure ChunkyPNG is required.

```ruby
orange = ChunkyPNG::Color.from_hsl(30, 1.0, 0.5)
green  = ChunkyPNG::Color.from_hsv(120, 1.0, 1.0)

dist = ChunkyPNG::Color.euclidean_distance_rgba(c1, c2)  # Float 0.0..441.67...
```

--------------------------------

### Load OilyPNG or ChunkyPNG

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2014-11-07-the-value-of-a-pure-ruby-library.md

This code block demonstrates how to conditionally load OilyPNG, falling back to ChunkyPNG if OilyPNG is not available. This allows for optional performance enhancements.

```ruby
begin
  require 'oily_png'
rescue LoadError
  require 'chunky_png'
end
```

--------------------------------

### Load RGBA Image Data with String#unpack

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-17-ode-to-array-pack-and-string-unpack.md

Use String#unpack with the 'N' format specifier for RGBA data. Ensure the width and height are known beforehand.

```ruby
pixels = rgba_pixeldata.unpack("N#{width * height}")
image = Image.new(width, height, pixels)
```

--------------------------------

### Export and Import PNG as Data URL

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Shows how to serialize a PNG image into a Base64-encoded data URL string for embedding in HTML or CSS, and how to import an image from such a URL.

```ruby
require 'chunky_png'

img = ChunkyPNG::Image.from_file('icon.png')

# Export as data URL
data_url = img.to_data_url
# => "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
```

```ruby
# Import from a data URL string
restored = ChunkyPNG::Canvas.from_data_url(data_url)
puts "#{restored.width}x#{restored.height}"
```

```ruby
# Export as raw blob string
blob = img.to_blob     # alias: to_string, to_s
# Re-import from blob
img2 = ChunkyPNG::Image.from_blob(blob)
```

--------------------------------

### Load RGB Image Data with String#unpack

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-17-ode-to-array-pack-and-string-unpack.md

For RGB data, use 'NX' to unpack and then explicitly set the alpha value for each pixel to 255. This method is efficient when the alpha channel is not present in the source data.

```ruby
pixels = rgb_pixeldata.unpack("NX" * (width * height))
pixels.map! { |pixel| pixel | 0x000000ff }
```

```ruby
image = Image.new(width, height, pixels)
```

--------------------------------

### Load and Convert BMP to PNG

Source: https://github.com/wvanbergen/chunky_png/wiki/Importing-BMP-images

This snippet loads a BMP image from a file, parses its headers to extract dimensions and color information, converts the pixel data to ChunkyPNG's format, and saves it as a PNG. It includes checks for file format and compression. Use with caution.

```ruby
require 'rubygems'
require 'chunky_png'

# get the data
data = StringIO.new(File.read('filename.bmp'))
mp_file_header = data.read(14).unpack('a2VxxV')mp_info_header = data.read(40).unpack('V3v2V6')

raise "Not a BMP file"                  unless bmp_file_header[0] == "BM"
raise "Only 24-bit BMP files supported" unless bmp_info_header[4] == 24
raise "Compression not supported"       unless bmp_info_header[5] == 0

width  = bmp_info_header[1]
height = bmp_info_header[2]
line_remainder = 4 - (width * 3) % 4

pixels = []
1.upto(height) do |i| 
  bytes = data.read(width * 3 + line_remainder).unpack("C#{width * 3}x#{line_remainder}")
  bytes.each_slice(3) { |b, g, r| pixels << ChunkyPNG::Color.rgb(r, g, b) }
end

image = ChunkyPNG::Image.new(width, height, pixels)
image.flip_horizontally!

image.save('converted_from_bmp.png')
```

--------------------------------

### Compose Images with Alpha Blending

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/index.md

Shows how to load two PNG images, compose one onto another at a specific position using alpha blending, and save the result. The `:fast_rgba` option forces a faster saving routine.

```ruby
# Compose images using alpha blending.
avatar = ChunkyPNG::Image.from_file('avatar.png')
badge  = ChunkyPNG::Image.from_file('no_ie_badge.png')
avatar.compose!(badge, 10, 10)
avatar.save('composited.png', :fast_rgba) # Force the fast saving routine.
```

--------------------------------

### Load PNG Image from File, IO, or Blob

Source: https://github.com/wvanbergen/chunky_png/wiki/Home.rdoc

Load PNG images from different sources like files, IO streams, or binary strings. Ensure files are opened in binary mode ('rb') when reading.

```ruby
image = ChunkyPNG::Image.from_file('file.png')
File.open('file.png', 'rb') { |io| image = ChunkyPNG::Image.from_io(io) }
image = ChunkyPNG::Image.from_blob(File.read('file.png'))
```

--------------------------------

### Access and Modify PNG Metadata

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/index.md

Illustrates how to read existing metadata from a PNG file and how to set new metadata. The changes are saved by overwriting the original file.

```ruby
# Accessing metadata
image = ChunkyPNG::Image.from_file('with_metadata.png')
puts image.metadata['Title']
image.metadata['Author'] = 'Willem van Bergen'
image.save('with_metadata.png') # Overwrite file
```

--------------------------------

### Geometry Helper Classes

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Introduces helper classes for geometric calculations: ChunkyPNG::Point for coordinates, ChunkyPNG::Dimension for width/height, and ChunkyPNG::Vector for directional information.

```ruby
point = ChunkyPNG::Point.new(10, 20)
dimension = ChunkyPNG::Dimension.new(100, 50)
vector = ChunkyPNG::Vector.new(5, -5)
```

--------------------------------

### Naive Pixel Representation in Ruby

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-14-memory-efficiency-when-using-ruby.md

A basic Ruby implementation for an image pixel using floating-point numbers for RGBA channels. This approach can be memory-intensive due to the size of floating-point numbers.

```ruby
class Pixel
  attr_reader :r, :g, :b, :a

  def initialize(r, g, b, a = 1.0)
    @r, @g, @b, @a = r, g, b, a
  end
end

class Image
  attr_reader :width, :height

  def initialize(width, height)
    @width, @height = width, height
    @pixels = Array.new(width * height)
  end

  def [](x,y)
    @pixels[y * width + x]
  end

  def []=(x,y, pixel)
    @pixels[y * width + x] = pixel
  end
end
```

--------------------------------

### Pixel Access and Row/Column Operations in ChunkyPNG

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Shows how to access and modify individual pixels using both bounds-checked and unchecked methods. Also demonstrates reading and replacing entire rows and columns. Requires 'chunky_png' and an image file.

```ruby
require 'chunky_png'

img = ChunkyPNG::Image.from_file('photo.png')

# Bounds-checked pixel read/write (raises ChunkyPNG::OutOfBounds if outside)
old_color = img[5, 10]
img[5, 10] = ChunkyPNG::Color('lime')

# Unchecked access (faster, no bounds check)
img.set_pixel(5, 10, ChunkyPNG::Color::WHITE)
val = img.get_pixel(5, 10)

# Read/replace an entire row
row_pixels = img.row(0)          # Array of color integers for row y=0
img.replace_row!(0, row_pixels.map { ChunkyPNG::Color::BLACK })

# Read/replace an entire column
col_pixels = img.column(0)
img.replace_column!(0, Array.new(img.height, ChunkyPNG::Color::WHITE))

# Bounds checking helpers
puts img.include_xy?(5, 10)   # => true
puts img.include_xy?(-1, 0)   # => false
puts img.include_point?(ChunkyPNG::Point.new(5, 10))  # => true
```

--------------------------------

### Color Compositing and Blending Functions

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Demonstrates the usage of various color manipulation functions provided by ChunkyPNG::Color, such as composing, blending, interpolating, fading, and calculating color distance.

```APIDOC
## ChunkyPNG::Color Functions

This section details the direct-use functions for color manipulation within the ChunkyPNG library.

### `ChunkyPNG::Color.compose(fg, bg)`

**Description**: Performs alpha compositing of a foreground color (`fg`) over a background color (`bg`) using fast integer math.

**Parameters**:
- `fg` (ChunkyPNG::Color): The foreground color (can be semi-transparent).
- `bg` (ChunkyPNG::Color): The background color.

**Returns**: ChunkyPNG::Color - The resulting color after compositing.

### `ChunkyPNG::Color.compose_precise(fg, bg)`

**Description**: Performs alpha compositing of a foreground color (`fg`) over a background color (`bg`) using high-precision floating-point math.

**Parameters**:
- `fg` (ChunkyPNG::Color): The foreground color (can be semi-transparent).
- `bg` (ChunkyPNG::Color): The background color.

**Returns**: ChunkyPNG::Color - The resulting color after precise compositing.

### `ChunkyPNG::Color.blend(fg, bg)`

**Description**: Blends two colors together without considering alpha values, effectively averaging them.

**Parameters**:
- `fg` (ChunkyPNG::Color): The first color.
- `bg` (ChunkyPNG::Color): The second color.

**Returns**: ChunkyPNG::Color - The blended color.

### `ChunkyPNG::Color.interpolate_quick(fg, bg, factor)`

**Description**: Interpolates between two colors (`fg` and `bg`) based on an alpha factor. A factor of 0 results in the background color, and 255 results in the foreground color.

**Parameters**:
- `fg` (ChunkyPNG::Color): The foreground color.
- `bg` (ChunkyPNG::Color): The background color.
- `factor` (Integer): The interpolation factor (0-255).

**Returns**: ChunkyPNG::Color - The interpolated color.

### `ChunkyPNG::Color.fade(color, factor)`

**Description**: Reduces the opacity of a given color by a specified factor. A factor of 0 makes the color fully transparent, and 255 leaves it unchanged.

**Parameters**:
- `color` (ChunkyPNG::Color): The color to fade.
- `factor` (Integer): The fading factor (0-255).

**Returns**: ChunkyPNG::Color - The faded color.

### `ChunkyPNG::Color.to_grayscale(color)`

**Description**: Converts a given color to its grayscale equivalent.

**Parameters**:
- `color` (ChunkyPNG::Color): The color to convert.

**Returns**: ChunkyPNG::Color - The grayscale color.

### `ChunkyPNG::Color.euclidean_distance_rgba(color1, color2)`

**Description**: Calculates the Euclidean distance between two colors in RGBA space.

**Parameters**:
- `color1` (ChunkyPNG::Color): The first color.
- `color2` (ChunkyPNG::Color): The second color.

**Returns**: Float - The Euclidean distance between the two colors.

### Example Usage

```ruby
require 'chunky_png'

fg = ChunkyPNG::Color.rgba(255, 0, 0, 128)   # semi-transparent red
bg = ChunkyPNG::Color.rgb(255, 255, 255)      # white

# Alpha-composite fg over bg (fast integer math)
result = ChunkyPNG::Color.compose(fg, bg)

# High-precision float version
result_precise = ChunkyPNG::Color.compose_precise(fg, bg)

# Average blend (no alpha consideration)
blended = ChunkyPNG::Color.blend(fg, bg)

# Interpolate between two colors by alpha factor (0=bg, 255=fg)
interp = ChunkyPNG::Color.interpolate_quick(fg, bg, 64)

# Reduce opacity by a factor (0=fully transparent, 255=unchanged)
faded = ChunkyPNG::Color.fade(fg, 100)

# Convert to grayscale
gray_color = ChunkyPNG::Color.to_grayscale(result)

# Euclidean distance in RGBA space
dist = ChunkyPNG::Color.euclidean_distance_rgba(fg, bg)
puts dist   # Float, max ~441.67
```
```

--------------------------------

### Load Image from Raw RGBA or RGB Streams

Source: https://github.com/wvanbergen/chunky_png/wiki/Home.rdoc

Load image data directly from RGBA or RGB formatted streams for significantly faster decoding compared to standard PNG loading. Pixels are expected in left-to-right, top-to-bottom order, with 1 byte per channel.

```ruby
image = ChunkyPNG::Image.from_rgba_stream(width, height, File.read('pixeldata.rgba')) # or
image = ChunkyPNG::Image.from_rgb_stream(width, height, File.read('pixeldata.rgb'))
```

--------------------------------

### Load ABGR Image Data with String#unpack

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-17-ode-to-array-pack-and-string-unpack.md

Utilize the 'V' format specifier with String#unpack for little-endian integers, suitable for ABGR formatted streams. This is a specialized method for specific byte orderings.

```ruby
pixels = abgr_pixeldata.unpack("V#{width * height}")
image = Image.new(width, height, pixels)
```

--------------------------------

### Image Metadata Handling in ChunkyPNG

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Explains how to add and persist image metadata (key-value string pairs) to PNG tEXt or zTXt chunks when saving. Requires 'chunky_png'.

```ruby
require 'chunky_png'
```

--------------------------------

### Low-Level PNG Chunk Access

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/index.md

Demonstrates how to access the raw PNG chunks within a file using ChunkyPNG::Datastream. This allows iterating through and inspecting each chunk's type.

```ruby
# Low level access to PNG chunks
png_stream = ChunkyPNG::Datastream.from_file('filename.png')
png_stream.each_chunk { |chunk| p chunk.type }
```

--------------------------------

### Canvas Operations: Compositing, Replacing, Cropping, Flipping, Rotating, Trimming, and Borders

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Covers various canvas manipulation techniques including alpha-compositing, direct pixel replacement, cropping, flipping, rotation, trimming transparent borders, and adding uniform borders. Bang methods mutate in-place; non-bang methods return a new canvas. Requires 'chunky_png' and image files.

```ruby
require 'chunky_png'

base   = ChunkyPNG::Image.from_file('background.png')
badge  = ChunkyPNG::Image.from_file('badge.png')   # has transparency

# Alpha-compose badge onto base at offset (10, 10) — returns new canvas
combined = base.compose(badge, 10, 10)

# Mutate base in-place
base.compose!(badge, 10, 10)

# Replace (no blending) — faster when badge has no transparency
base.replace!(badge, 10, 10)

# Crop: new canvas from region (x, y, width, height)
thumb = base.crop(0, 0, 100, 100)
base.crop!(50, 50, 200, 200)   # mutates base

# Flip and rotate
flipped = base.flip_horizontally   # alias: flip
mirrored = base.flip_vertically    # alias: mirror
rot90  = base.rotate_right         # clockwise 90°
rot180 = base.rotate_180
rot270 = base.rotate_left          # counter-clockwise 90°

# Trim transparent/uniform border (detects color of first pixel)
trimmed = base.trim
base.trim!

# Add a uniform-color border (size, color)
bordered = base.border(5, ChunkyPNG::Color::BLACK)
base.border!(10, ChunkyPNG::Color('navy'))

# Convert to grayscale
gray = base.grayscale      # new canvas
base.grayscale!            # mutates

base.save('result.png')
```

--------------------------------

### Save PNG Image to File, IO, or Blob

Source: https://github.com/wvanbergen/chunky_png/wiki/Home.rdoc

Encode an image and save it to a file, IO stream, or binary string. Ensure files are opened in binary mode ('wb') when writing.

```ruby
image.save('filename.png')
File.open('newfile.png', 'wb' ) { |io| image.write(io) }
binary_string = image.to_blob
```

--------------------------------

### Convert Between ChunkyPNG and RMagick Images

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Facilitates bidirectional conversion between ChunkyPNG::Canvas objects and RMagick::Image objects using the optional 'chunky_png/rmagick' file. Allows applying RMagick operations to ChunkyPNG images.

```ruby
require 'rmagick'
require 'chunky_png'
require 'chunky_png/rmagick'

# ChunkyPNG → RMagick
canvas = ChunkyPNG::Canvas.from_file('photo.png')
rmagick_image = ChunkyPNG::RMagick.export(canvas)

# Apply RMagick operations
rmagick_image = rmagick_image.blur_image(0, 2.0)
rmagick_image = rmagick_image.enhance
```

```ruby
# RMagick → ChunkyPNG
updated_canvas = ChunkyPNG::RMagick.import(rmagick_image)
updated_canvas.save('blurred.png')
```

--------------------------------

### Import PNG from Data URL

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Use this method to load PNG images directly from a data URL string. This is useful for embedding images in web applications or for dynamic image loading.

```ruby
canvas = ChunkyPNG::Canvas.from_data_url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==")
```

--------------------------------

### Custom Exception Classes

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Introduces custom exception classes for specific error conditions, such as `ChunkyPNG::SignatureMismatch` when a file is not a valid PNG.

```ruby
begin
  ChunkyPNG::Image.from_file('not_a_png.txt')
rescue ChunkyPNG::SignatureMismatch => e
  puts "Error: #{e.message}"
end
```

--------------------------------

### Optimized Alpha Composition with Integer Math in Ruby

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-14-memory-efficiency-when-using-ruby.md

Employ this optimized version for faster alpha composition using integer math and bitwise operations. It avoids floating-point conversions for better memory efficiency.

```ruby
def compose(fg, bg)
  return bg if fg.a == 0
  return fg if fg.a == 255

  alpha_complement = multiply(255 - fg.a, bg.a)
  new_r = multiply(fg.a, fg.r) + multiply(alpha_complement, bg.r)
  new_g = multiply(fg.a, fg.g) + multiply(alpha_complement, bg.g)
  new_b = multiply(fg.a, fg.b) + multiply(alpha_complement, bg.b)
  new_a = fg.a + alpha_complement

  Pixel.rgba(new_r, new_g, new_b, new_a)
end

# Quicker alternative for (a * b / 255.0).round
def multiply(a, b)
  t = a * b + 0x80
  ((t >> 8) + t) >> 8
end
```

--------------------------------

### Control PNG Encoding Options

Source: https://github.com/wvanbergen/chunky_png/wiki/Home.rdoc

Override automatic encoding detection to force RGB or RGBA output for faster encoding, or use best compression for smaller file sizes. Specific options like color mode, compression level, and interlacing can also be provided.

```ruby
image.save('filename.png', :fast_rgb) # for RGB only images.
png_data = image.to_blob(:fast_rgba) # or for RGBA images.
image.save('filename.png', :best_compression)
image.save('filename.png', :color_mode => ChunkyPNG::COLOR_INDEXED, 
             :compression => Zlib::NO_COMPRESSION, :interlace => true)
```

--------------------------------

### Inspect and Manipulate Raw PNG Chunks

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Provides low-level access to the PNG chunk structure using ChunkyPNG::Datastream. Allows inspection of header, iteration over all chunks, reading metadata, and accessing physical dimensions.

```ruby
require 'chunky_png'

# Load the raw datastream (not the image)
ds = ChunkyPNG::Datastream.from_file('photo.png')

# Inspect the header chunk
puts ds.header_chunk.width       # => 800
puts ds.header_chunk.height      # => 600
puts ds.header_chunk.color       # => 2 (ChunkyPNG::COLOR_TRUECOLOR)
puts ds.header_chunk.depth       # => 8
puts ds.header_chunk.interlace   # => 0
```

```ruby
# Iterate over all chunks
ds.each_chunk do |chunk|
  puts "#{chunk.type}: #{chunk.respond_to?(:data) ? chunk.data.bytesize : '-'} bytes"
end
```

```ruby
# Read text metadata from chunks
puts ds.metadata.inspect   # => {"Title"=>"...", "Author"=>"..."}
```

```ruby
# Access physical dimensions (pHYs chunk) if present
if ds.physical_chunk
  puts ds.physical_chunk.dpix    # DPI in x direction
  puts ds.physical_chunk.dpiy    # DPI in y direction
end

# Re-save the raw datastream
ds.save('copy.png')
blob = ds.to_blob
```

--------------------------------

### In-place Canvas Transformations

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Provides in-place versions of several canvas transformation methods. Appending '!' to the method name modifies the canvas directly, offering improved memory and CPU efficiency.

```ruby
canvas.crop!(x, y, width, height)
canvas.rotate_180!
canvas.flip_horizontally!
canvas.flip_vertically!
```

--------------------------------

### Convert Color to Grayscale

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Converts a ChunkyPNG color object to its grayscale equivalent. This is useful for image processing tasks that require grayscale representation.

```ruby
grayscale_color = ChunkyPNG::Color.to_grayscale(color)
```

--------------------------------

### Resample Image (Nearest Neighbor)

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Resamples the image using the nearest neighbor algorithm. This method returns a new canvas instance with the resampled image.

```ruby
new_canvas = canvas.resample(width, height)
```

--------------------------------

### Alpha Composition with Floating-Point Math in Ruby

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-14-memory-efficiency-when-using-ruby.md

Use this method for alpha composition when floating-point precision is acceptable. It converts integer pixel values to floats for calculation.

```ruby
def compose(fg, bg)
  return bg if fg.a == 0
  return fg if fg.a == 255

  fg_alpha = fg.a / 255.0
  bg_alpha = fg.a / 255.0
  alpha_complement = (1.0 - fg_alpha) * bg_alpha

  new_r = (fg_alpha * fg.r + alpha_complement * bg.r).round
  new_g = (fg_alpha * fg.g + alpha_complement * bg.g).round
  new_b = (fg_alpha * fg.b + alpha_complement * bg.b).round
  new_a = ((fg_alpha + alpha_complement) * 255).round

  Pixel.rgba(new_r, new_g, new_b, new_a)
end
```

--------------------------------

### Replace Theme Color in PNG

Source: https://context7.com/wvanbergen/chunky_png/llms.txt

Uses ChunkyPNG::Canvas::Masking to replace a specific theme color with another, preserving anti-aliasing. Supports both in-place mutation and a two-step mask extraction/recoloring process.

```ruby
require 'chunky_png'

img = ChunkyPNG::Image.from_file('button_blue.png')

blue   = ChunkyPNG::Color('steelblue')
red    = ChunkyPNG::Color('firebrick')
white  = ChunkyPNG::Color::WHITE

# One-step theme color change (mutates in place)
img.change_theme_color!(blue, red, white, 10)
# tolerance 10 = accept pixels within 10 units of the theme color

img.save('button_red.png')
```

```ruby
# Two-step approach: extract mask first, then recolor
original = ChunkyPNG::Image.from_file('button_blue.png')
base, mask = original.extract_mask(blue, white, 5)

mask.change_mask_color!(ChunkyPNG::Color('forestgreen'))
result = base.compose!(mask)
result.save('button_green.png')
```

--------------------------------

### Encode RGB Pixels with Array#pack

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-17-ode-to-array-pack-and-string-unpack.md

Encodes an RGB pixel array into PNG format, omitting the alpha channel byte for each pixel using 'NX'. This results in a smaller file size compared to RGBA encoding and offers significant speed improvements.

```ruby
pixeldata = pixels.pack(("x" + ('NX' * width)) * height)
```

--------------------------------

### Optimizing Image Class for Pixel Storage in Ruby

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-14-memory-efficiency-when-using-ruby.md

Modifications to the Image class to store pixel data as raw integer values, deferring the creation of Pixel objects until access. This avoids Ruby object overhead for each pixel.

```ruby
class Image
  # ...

  def [](x,y)
    Pixel.new(@pixels[y * width + x]) # wrap
  end

  def []=(x,y, pixel)
    @pixels[y * width + x] = pixel.to_i # unwrap
  end
end
```

--------------------------------

### Encode RGBA Pixels with Array#pack

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-17-ode-to-array-pack-and-string-unpack.md

Encodes a complete pixel array into RGBA PNG format using 'xN' for null byte and 4-byte network byte order integers. This method skips line splitting and filtering for maximum performance.

```ruby
pixeldata = pixels.pack("xN#{width}" * height)
```

--------------------------------

### Efficient RGBA Pixel Representation in Ruby

Source: https://github.com/wvanbergen/chunky_png/blob/master/docs/_posts/2010-01-14-memory-efficiency-when-using-ruby.md

An optimized Ruby Pixel class that stores RGBA values as a single integer using bitwise operations. This significantly reduces memory usage compared to individual floating-point numbers.

```ruby
class Pixel
  attr_reader :value
  alias :to_i :value

  def initialize(value)
    @value = value
  end

  def self.rgba(r, g, b, a = 255)
    self.new(r << 24 | g << 16 | b << 8 | a)
  end

  def r; (@value & 0xff000000) >> 24; end
  def g; (@value & 0x00ff0000) >> 16; end
  def b; (@value & 0x0000ff00) >>  8; end
  def a; (@value & 0x000000ff); end
end
```

--------------------------------

### Export PNG to Data URL

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

This method allows exporting a PNG canvas to a data URL string. It's convenient for embedding images inline in HTML or CSS without needing to save them to a file.

```ruby
data_url = canvas.to_data_url
```

--------------------------------

### Access HTML Named Colors

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Allows accessing HTML named colors using a symbolic or string-based lookup. Supports color names and optional alpha values.

```ruby
teal_color = ChunkyPNG::Color(:teal)
red_with_alpha = ChunkyPNG::Color('red @ 0.8')
```

--------------------------------

### Convert Canvas to Grayscale

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Applies a grayscale transformation to the entire canvas. This method modifies the canvas in place.

```ruby
canvas.grayscale!
```

--------------------------------

### API Change: Non-mutating Compose and Replace

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

The `compose` and `replace` methods no longer modify the canvas in place. They now return a new canvas instance. For in-place operations, use the newly renamed `compose!` and `replace!` methods.

```ruby
# Old behavior (mutating):
# canvas.compose(other_canvas, x, y)

# New behavior (non-mutating):
new_canvas = canvas.compose(other_canvas, x, y)

# New in-place behavior:
canvas.compose!(other_canvas, x, y)
```

--------------------------------

### Export Grayscale Pixel Data Stream

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Exports the canvas's pixel data as a grayscale stream. This is useful for processing or transmitting grayscale image data efficiently.

```ruby
grayscale_stream = canvas.to_grayscale_stream
```

--------------------------------

### Draw Circle

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Draws a circle on the canvas. This method adds a filled circle to the canvas.

```ruby
canvas.circle(x, y, radius, color)
```

--------------------------------

### Export Raw Alpha Channel Bytes

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Exports the alpha channel of the canvas as a raw byte string. This can be useful for low-level image manipulation or custom encoding.

```ruby
alpha_bytes = canvas.to_alpha_channel_bytes
```

--------------------------------

### Draw Rectangle

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Draws a simple rectangle on the canvas. This method adds a filled rectangle to the canvas.

```ruby
canvas.rect(x1, y1, x2, y2, color)
```

--------------------------------

### Draw Bezier Curve

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Adds a Bezier curve to the canvas. This method allows for drawing smooth, complex curves.

```ruby
canvas.bezier_curve(x1, y1, x2, y2, x3, y3, x4, y4, color)
```

--------------------------------

### Draw Polygon

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Draws a polygon on the canvas. This method adds a filled polygon to the canvas.

```ruby
canvas.polygon(points, color)
```

--------------------------------

### Flip Image Horizontally

Source: https://github.com/wvanbergen/chunky_png/wiki/Changelog.rdoc

Flips the image horizontally. This method returns a new canvas instance with the flipped image.

```ruby
flipped_canvas = canvas.flip_horizontally
```

--------------------------------

### Manipulate Image Pixels and Draw Shapes

Source: https://github.com/wvanbergen/chunky_png/wiki/Home.rdoc

Access and modify individual pixels, draw lines, and perform image transformations like flipping and rotating. Colors can be defined using RGBA values or hexadecimal strings.

```ruby
image = ChunkyPNG::Image.from_file('filename.png')
image[0, 0] = ChunkyPNG::Color.rgba(255, 0,0, 128)
image.line(1, 1, 10, 1, ChunkyPNG::Color.from_hex('#aa007f'))
new_image = image.flip_horizontally.rotate_right
image.compose(ChunkyPNG::Image.new(16, 16, ChunkyPNG::Color.rgba(10, 10, 10, 128)))
```
Tokens:
Raw