ChunkyPNG Documentation

You can also load pixel streams in ABGR format by using little-endian integers with the V directive in String#unpack.

# abgr_pixeldata is the raw byte stream
# width and height are the image dimensions
pixels = abgr_pixeldata.unpack("V#{width * height}")
image = Image.new(width, height, pixels)

For RGB images (without an alpha channel), you can optimize encoding by using the X modifier in Array#pack. This allows you to pack 4-byte integers but discard the last byte (the alpha channel) for every pixel, resulting in a file size approximately 25% smaller than the RGBA method while maintaining high performance.

# pixels is an array of Fixnums representing RGB pixels
# width and height are the image dimensions
pixeldata = pixels.pack(("x" + ('NX' * width)) * height)

To achieve high-performance encoding for RGBA images, you can bypass manual scanline splitting and filtering by using Ruby's Array#pack method with the xN notation. This method treats the pixel array as a sequence of 4-byte integers in network byte order (big-endian) preceded by a null byte (filter method 0).

Note: This approach skips PNG filtering, which means the resulting file compression may not be optimal, but it provides a significant speedup.

# pixels is an array of Fixnums representing RGBA pixels
# width and height are the image dimensions
pixeldata = pixels.pack("xN#{width}" * height)

To load an RGB formatted stream, use the X modifier with String#unpack. Because the alpha channel is missing from the stream, you must manually set the alpha value for every pixel to 255 (0x000000ff) to ensure correct transparency in the resulting Image object.

# rgb_pixeldata is the raw byte stream
# width and height are the image dimensions
pixels = rgb_pixeldata.unpack("NX" * (width * height))
# Set alpha channel to 255 for every pixel
pixels.map! { |pixel| pixel | 0x000000ff }
image = Image.new(width, height, pixels)

If you have access to the raw RGBA formatted pixel stream and know the image dimensions, you can load pixels extremely quickly using String#unpack with the N (network byte order) directive.

# rgba_pixeldata is the raw byte stream
# width and height are the image dimensions
pixels = rgba_pixeldata.unpack("N#{width * height}")
image = Image.new(width, height, pixels)

ChunkyPNG is a pure Ruby library with no dependencies, making it easy to install without a compiler toolchain. However, for performance-critical tasks, you can use OilyPNG, a companion mixin library.

OilyPNG provides C-optimized implementations of specific ChunkyPNG methods. When loaded, it uses Module#include and Module#extend to overwrite ChunkyPNG's pure Ruby methods with faster versions while maintaining 100% API compatibility.

To make OilyPNG optional in your project (falling back to pure Ruby if the C extension is unavailable), use a begin/rescue block during your requirement phase.

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

ChunkyPNG is a pure Ruby library for accessing and manipulating PNG files. The library is organized under the ChunkyPNG namespace and consists of several key classes and modules:

• ChunkyPNG::Image: The primary class used to represent PNG images, including their metadata.
• ChunkyPNG::Canvas: Represents the image's canvas (the pixel data area).
• ChunkyPNG::Color: A module for working with color values.
• ChunkyPNG::Palette: Represents the color palette used by a ChunkyPNG::Canvas.
• ChunkyPNG::Datastream: Represents the internal structure of a PNG ChunkyPNG::Image.
• ChunkyPNG::Chunk: Represents individual chunks of data within a ChunkyPNG::Datastream.
• ChunkyPNG::Point, ChunkyPNG::Dimension, and ChunkyPNG::Vector: Geometry helper classes for 2D coordinates, dimensions (width x height), and series of points.

ChunkyPNG supports several ways to store metadata:

tEXt (Uncompressed Text)

Use ChunkyPNG::Chunk::Text for Latin-1 encoded keyword/value pairs.

zTXt (Compressed Text)

Use ChunkyPNG::Chunk::CompressedText for Deflate-compressed keyword/value pairs.

iTXt (International Text)

Use ChunkyPNG::Chunk::InternationalText for UTF-8 encoded metadata. This supports language tags and translated keywords.

# Example: Creating a tEXt chunk
text_chunk = ChunkyPNG::Chunk::Text.new("Author", "Jane Doe")

# Example: Creating an iTXt chunk
intl_chunk = ChunkyPNG::Chunk::InternationalText.new(
  "Description", 
  "A beautiful sunset", 
  "en", 
  "Beschreibung", 
  ChunkyPNG::UNCOMPRESSED_CONTENT
)

The ChunkyPNG::Canvas::Drawing module provides several primitive drawing methods.

Important Behaviors:

• In-place modification: All drawing methods modify the existing ChunkyPNG::Canvas instance and return self. They do not create a new canvas.
• Bounds handling: Drawing operations will not fail if they occur outside the canvas bounds; pixels outside the canvas are simply ignored.
• Color parsing: Most methods accept color values that can be parsed via ChunkyPNG::Color.parse (e.g., hex strings or integers).

ChunkyPNG is vulnerable to decompression bombs, which can lead to Denial of Service (DoS) attacks by exhausting memory when loading specially crafted PNG files.

Mitigation: When processing untrusted images, perform the ChunkyPNG operations in a separate process (e.g., using fork or a background processing library) to isolate the impact of potential memory exhaustion.