CrystalVips
Provides Crystal language interface to the libvips image processing library.
Programs that use CrystalVips
don't manipulate images directly, instead they create pipelines of image processing operations starting from a source image. When the pipe is connected to a destination, the whole pipeline executes at once and in parallel, streaming the image from source to destination in a set of small fragments.
Because CrystalVips
is parallel, its' quick, and because it doesn't need to keep entire images in memory, its light. For example, the libvips speed and memory use benchmark:
https://github.com/libvips/libvips/wiki/Speed-and-memory-use
Pre-requisites
You need to install the libvips library. It's in the linux package managers, homebrew and MacPorts, and there are Windows binaries on the vips website. For example, on Debian:
sudo apt-get install --no-install-recommends libvips42
(--no-install-recommends
stops Debian installing a lot of extra packages)
Or macOS:
brew install vips
Installation
-
Add the dependency to your
shard.yml
:dependencies: vips: github: naqvis/crystal-vips
-
Run
shards install
Usage
require "vips"
im = Vips::Image.new_from_file("image.jpg")
# put im at position (100, 100) in a 3000 x 3000 pixel image,
# make the other pixels in the image by mirroring im up / down /
# left / right, see
# https://libvips.github.io/libvips/API/current/libvips-conversion.html#vips-embed
im = im.embed(100, 100, 3000, 3000, extend: Vips::Enums::Extend::Mirror)
# multiply the green (middle) band by 2, leave the other two alone
im *= [1, 2, 1]
# make an image from an array constant, convolve with it
mask = Vips::Image.new_from_array([
[-1, -1, -1],
[-1, 16, -1],
[-1, -1, -1]], 8)
im = im.conv(mask, precision: Vips::Enums::Precision::Integer)
# finally, write the result back to a file on disk
im.write_to_file("output.jpg")
Refer to example folder for more samples
Development
To run all tests:
crystal spec
Getting more help
The libvips website has a handy table of all the libvips operators. Each one links to the main API docs so you can see what you need to pass to it.
A simple way to see the arguments for an operation is to try running it from the command-line. For example:
$ vips embed
embed an image in a larger image
usage:
embed in out x y width height
where:
in - Input image, input VipsImage
out - Output image, output VipsImage
x - Left edge of input in output, input gint
default: 0
min: -1000000000, max: 1000000000
y - Top edge of input in output, input gint
default: 0
min: -1000000000, max: 1000000000
width - Image width in pixels, input gint
default: 1
min: 1, max: 1000000000
height - Image height in pixels, input gint
default: 1
min: 1, max: 1000000000
optional arguments:
extend - How to generate the extra pixels, input VipsExtend
default: black
allowed: black, copy, repeat, mirror, white, background
background - Color for background pixels, input VipsArrayDouble
operation flags: sequential
Contributing
- Fork it (https://github.com/naqvis/crystal-vips/fork)
- 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
- Ali Naqvi - creator and maintainer