No release in over 3 years
Low commit activity in last 3 years
This pure Ruby library can read and write PNG images without depending on an external image library, like RMagick. It tries to be memory efficient and reasonably fast. It supports reading and writing all PNG variants that are defined in the specification, with one limitation: only 8-bit color depth is supported. It supports all transparency, interlacing and filtering options the PNG specifications allows. It can also read and write textual metadata from PNG files. Low-level read/write access to PNG chunks is also possible. This library supports simple drawing on the image canvas and simple operations like alpha composition and cropping. Finally, it can import from and export to RMagick for interoperability. Also, have a look at OilyPNG at https://github.com/wvanbergen/oily_png. OilyPNG is a drop in mixin module that implements some of the ChunkyPNG algorithms in C, which provides a massive speed boost to encoding and decoding.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 0
~> 3
~> 0.9
 Project Readme

ChunkyPNG

This library can read and write PNG files. It is written in pure Ruby for maximum portability. Let me rephrase: it does NOT require RMagick or any other memory leaking image library.

Features

  • Decodes any image that the PNG standard allows. This includes all standard color modes, all bit depths, all transparency, and interlacing and filtering options.
  • Encodes images supports all color modes (true color, grayscale, and indexed) and transparency for all these color modes. The best color mode will be chosen automatically, based on the amount of used colors.
  • R/W access to the image's pixels.
  • R/W access to all image metadata that is stored in chunks.
  • Memory efficient (uses a Fixnum, i.e. 4 or 8 bytes of memory per pixel, depending on the hardware)
  • Reasonably fast for Ruby standards, by only using integer math and a highly optimized saving routine.
  • Works on every currently supported Ruby version (2.5+)
  • Interoperability with RMagick if you really have to.

Also, have a look at OilyPNG which is a mixin module that implements some of the ChunkyPNG algorithms in C, which provides a massive speed boost to encoding and decoding.

Usage

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)

# 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.

# 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

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

Also check out the screencast on the ChunkyPNG homepage by John Davison, which illustrates basic usage of the library on the ChunkyPNG website.

For more information, see the project wiki or the RDOC documentation.

Security warning

ChunkyPNG is vulnerable to decompression bombs, which means that ChunkyPNG is vulnerable to DOS attacks by running out of memory when loading a specifically crafted PNG file. Because of the pure-Ruby nature of the library it is very hard to fix this problem in the library itself.

In order to safely deal with untrusted images, you should make sure to do the image processing using ChunkyPNG in a separate process, e.g. by using fork or a background processing library.

About

The library is written by Willem van Bergen for Floorplanner.com, and released under the MIT license (see LICENSE). Please contact me for questions or remarks.

I generally consider this library to be feature complete. I will gladly accept patches to fix bugs and improve performance, but I will generally be hesitant to accept new features or API endpoints. Before contributing, please read CONTRIBUTING.rdoc that explains this in more detail.

Please check out CHANGELOG.rdoc to see what changed in all versions.

P.S.: The name of this library is intentionally similar to Chunky Bacon and Chunky GIF. Use Google if you want to know why. :-)