Crystal Image (Processing)
This shard aims to provide feature rich image processing abilities, both for the purpose of image manipulation as well as feature / information extraction from those images.
The code here originated as a fork from Pluto and further takes inspiration from Stumpy, and support converting to and from both of those libraries.
All sample images used are from Unsplash.
Installation
-
Add the dependency to your
shard.yml
:dependencies: cr-image: github: vici37/cr-image
-
Run
shards install
Usage
CrImage supports the formats:
- PPM
- JPEG (requires
libturbojpeg
) - PNG (natively by default, or optionally through requires
libspng
) - WebP (requires
libwebp
)
For the formats that require a linked library, they must be require
d explicitly:
require "cr-image"
require "cr-image/jpeg"
require "cr-image/webp"
require "cr-image/png" # replaces native crystal with libspng
# Or, alternatively
require "cr-image/all_formats"
Example
Assuming an image moon.jpg
already exists
require "cr-image"
image = CrImage::RGBAImage.open("moon.jpg")
# create a mask identifying all pixels with light (i.e. the moon)
moon_mask = image
.to_gray
.threshold(8) # pixels are UInt8, with 0 as black and 255 as white
# Crop out the moon from the image, and save it to a new file
image.crop(
moon_mask.region # smallest area that encompasses all true bits in mask
).save("moon_cropped.jpg")
Yields this image:
See the tutorials for more examples.
Pluto and Stumpy Conversion
If your library or application already uses Pluto or Stumpy and you want to use some of the functionality of this library, CrImage also provides some optional conversion methods:
require "cr-image/pluto"
pluto_image # => Pluto::ImageRGBA
pluto_image.to_crimage # => CrImage::RGBAImage
cr_image # => CrImage::RGBAImage
cr_image.to_pluto # => Pluto::ImageRGBA
NOTE: Currently Pluto and CrImage share the same bindings for libturbojpeg
, libspng
, and libwebp
. If you
use Pluto, you cannot use those formats from CrImage.
require "cr-image/stumpy"
stumpy_canvas # => StumpyCore::Canvas
stumpy_canvas.to_crimage # => CrImage::RGBAImage
cr_image # => CrImage::RGBAImage
cr_image.to_stumpy # => StumpyCore::Canvas
NOTE: Stumpy uses UInt16
for its underlying raw image storage per channel per pixel, while Pluto and
CrImage uses UInt8
. Converting from a Stumpy Canvas
object to RGBAImage
may lose quality if the original
image used 16 bit color channels (i.e. 16-bit PNG). Most image formats tend to use 8-bit color channels.
Development
This requires libwebp
, libspng
, and libturbojpeg
to run. Then:
> make test
To ensure all tests run and pass.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- Troy Sornson - creator and maintainer