phenopolis/pluto

A fast and convenient image processing library

A fast and convenient image processing library

Documentation

• Main
• Stable

Currently supported

• Image formats
  • JPEG (through libjpeg-turbo)
  • PNG (through libspng)
  • PPM
  • StumpyCore
  • WebP (through libwebp)
    • WebP 1.3+ linking flags are used by default. If you have an older version installed, compile with the -Dlegacy_webp flag to skip the requirement for libsharpyuv.
• Image operations
  • Bilinear resize
  • Box blur
  • Brightness
  • Channel swap
  • Contrast
  • Crop
  • Gaussian blur
  • Horizontal blur
  • Padding
  • Rotation
  • Vertical blur

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     pluto:
       github: phenopolis/pluto

2. Run shards install.

Usage

Basic

require "pluto"

# Formats requiring linkinkg a C library must be explicitly `require`d
require "pluto/format/jpeg"
require "pluto/format/png"
require "pluto/format/webp"

image = File.open("lib/pluto_samples/desert.png") do |file|
  Pluto::ImageRGBA.from_png(file)
end

image.contrast(-100)  # Creates a new object
image.contrast!(-100) # Modifies the existing object

io = IO::Memory.new
image.to_jpeg(io)
io.rewind
File.write("output.jpeg", io)

StumpyCore

Pluto can convert to and from StumpyCore Canvas objects, so any format that Stumpy supports can be usable with Pluto as well.

require "pluto"
require "stumpy_png"

canvas = StumpyPNG.read("lib/pluto_samples/desert.png") # => StumpyCore::Canvas
image = Pluto::ImageRGBA.from_stumpy(canvas)            # => Pluto::ImageRGBA
image.to_stumpy                                         # => StumpyCore::Canvas

Note

Converting from a StumpyCore::Canvas created from a 16-bit image will result in a loss of information, since Pluto currently only supports 8 bit.

More

See the API or the spec/ folder for more examples.

Benchmarks

See BENCHMARKS.md.

Contributing

1. Fork it (https://github.com/phenopolis/pluto/fork).
2. Create your feature branch (git checkout -b my-new-feature).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin my-new-feature).
5. Create a new Pull Request.

pluto's Issues

Basic example in README.md not working

Hello.

Thank you for making this kind of library open source. I'm trying to test it to see how it works. Can you provide more example on how to use this library ? For example, Crystal lang Redis library has lot of examples that really represent in good way how to use it. Maybe you can provide set of those as well.
I'm trying to run example in README.md , but I get:

Error: undefined constant Pluto::ImageRGBA

Updating basic example would be enough for me and others to get started quickly without debugging.

Thank you 🚀 .

Simplify specs

Replace the bilinear resizing algorithm

The current one is:

• Not too fast in comparison to GraphicsMagick
• Causes exceptions on some images

Benchmark `.from_ppm` methods

If one of them is faster or uses less memory, then add comments about it.

More details: #27 (review).

Add documentation

Add a filter to change contrast

Support 16-bit images

Add benchmarks

Add lossless JPEG 2000 support

Add lossless HTJ2K support

Add lossy WebP support

Add a crop operation

Add lossy JPEG 2000 support

Arithmetic overflow with vertical and horizontal blurs with attached image

I was experimenting with some other images and came across one that fails in the vertical_blur and horizontal_blur. Through testing, it looks like the operation (c_value * multiplier).to_u8 is throwing it, where c_value ends up as -1, causing a negative number trying to be cast to_u8. I tried adding a .clamp(0, 255), but it hit the benchmark pretty hard. Making this issue to capture the problem in the meantime.

Add lossy HTJ2K support

String vs IO based API

Hi, I was intrigued by the memory consumption mentioned in https://blog.phenopolis.com/posts/our-journey-into-crystal-and-image-processing/ and made a quick look in the source code.

I see that read/write of each format requires the whole image data to be in memory more than once.

Example:

In

pluto/src/pluto/format/ppm.cr

Line 4 in 078f476

io = IO::Memory.new(image_data)

the whole image data is in string and also decoded in the arrays for each rgb.

In https://github.com/phenopolis/thumbnailer/blob/f84979ea448a43d5c531856665a5ab91db6fcbc8/src/thumbnailer.cr#L64 we see that this force consumers to read the whole file in memory.

It should be possible to change the api to:

• def self.from_ppm(io : IO) : Image
• File.open(file_path) { |f| Pluto::Image.from_jpeg(f) }

This way, the whole file does not need to be read in memory. The current from_ppm implementation even uses IO::Memory.

Similarly, for def to_ppm : String it is possible to def to_ppm(io : IO) so that consumers can pass a file handler directly.

I'm certain this will decrease the memory consumption.

Release 0.2.0

Arithmetic overflow when using box blur

Using the sample image (from unsplash):

image.box_blur(5)

Yields an Arithmetic overflow in the horizontal operations at line 34. The arguments that make it there are -137 * 0.09(...), which yields a negative number that fails the to_u8 call. I'm thinking the round should be swapped to a clamp(0, 255) to protect against this, I can set up a PR for it soon.

Unable to see logo on README

When viewing Github using light mode, the white pluto logo is invisible:

Add a (Gaussian) blur operation

Add PNG support

Unify exceptions

Options:

• Two exception types, one for error codes and one for messages.
• Two initialize overloads, one for error codes and one for messages.
• ?

Store channels separately

Add a filter to swap channels

Add WebP support

Rename `GrayscaleImage` and `RGBAImage`

Suggestions:

• GrayscaleImage -> Image::GA (GrayscaleAlpha)
• RGBAImage -> Image::RGBA (RedGreenBlueAlpha)

libspng uses this naming as well.

Add lossy JPEG XL support

Add a filter to change brightness

Add lossy AVIF support

Redo the APIs

• Document which formats are based on Bytes and IO.
• Remove the String API.
• Switch to explicit named arguments or named methods.

Add lossless AVIF support

https://github.com/AOMediaCodec/libavif

Add lossless JPEG XL support