ruby-vips 0.3.14 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 089ea1c945c987de705749f712762e4ed5f74aa3
-  data.tar.gz: 6feeff8d78b3ca3e8e3ee63a65d9384787b327d0
+  metadata.gz: a944b8cabe34780ee544fb8504a6618efd94c674
+  data.tar.gz: b5740fa6840ce9905fa30870a6100b49b9adc1f2
 SHA512:
-  metadata.gz: d9c675ca4def94a475f0578e856dc130b56484688aa3b2751eda49e2a68050eb63f9442b07d69f4cf757905f7801e32fe21eaf130b5fd2117e96778427bcc8e8
-  data.tar.gz: 865652f25e10add687e72e2596e013bf56b114b7dae1966a9b388c71adbd9188fbbed8b31497c4d9ad5070dede456263b8d99a38718100f2464cbcdb20e12dd7
+  metadata.gz: f1b926ab064590c3f67ce2f346af93696d413c05787e56263ef1d46ef89d8a16f0f705c9edd6d85e1560a660cbae644f456eab17c4f8df81da2844781b221438
+  data.tar.gz: 3c337597296afec5e3464fd12052823780a0cde94774dbc2bb39cc289be21230604d3774d72d85fc2498d9acb1ac7e17c7ebca4567b7d1a961b36829e30eb757

data/.travis.yml

@@ -0,0 +1,22 @@
+env:
+  global:
+    - NOKOGIRI_USE_SYSTEM_LIBRARIES=true
+
+sudo: false
+cache: bundler
+
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0
+  - 2.1
+
+script: "rake"
+
+gemfile:
+  - Gemfile
+
+before_install:
+  - uname -a
+  - apt-get update
+  - apt-get install libvips-dev

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # master 
 
+# Version 1.0.0
+
+* complete rewrite, API break [John Cupitt]
+
 # Version 0.3.14
 
 * more GC tuning [felixbuenemann]

data/Gemfile

@@ -0,0 +1,15 @@
+source 'http://rubygems.org'
+
+# runtime deps
+gem "gobject-introspection", "~> 3.0"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+    gem "rspec", "~> 3.3"
+    gem "yard", "~> 0.8"
+    gem "redcarpet", "~> 3.3"
+    gem "github-markup", "~> 1.4"
+    gem "bundler", "~> 1.0"
+    gem "jeweler", "~> 2.0"
+end

data/Gemfile.lock

@@ -1,51 +1,60 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.3.6)
+    addressable (2.4.0)
     builder (3.2.2)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.2.5)
-    faraday (0.8.9)
-      multipart-post (~> 1.2.0)
-    git (1.2.7)
-    github_api (0.10.1)
-      addressable
-      faraday (~> 0.8.1)
-      hashie (>= 1.2)
-      multi_json (~> 1.4)
-      nokogiri (~> 1.5.2)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    git (1.3.0)
+    github-markup (1.4.0)
+    github_api (0.14.0)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
       oauth2
-    hashie (3.2.0)
-    highline (1.6.21)
-    jeweler (1.8.8)
+    glib2 (3.0.8)
+      pkg-config
+    gobject-introspection (3.0.8)
+      glib2 (= 3.0.8)
+    hashie (3.4.4)
+    highline (1.7.8)
+    jeweler (2.1.1)
       builder
-      bundler (~> 1.0)
+      bundler (>= 1.0)
       git (>= 1.2.5)
-      github_api (= 0.10.1)
+      github_api
       highline (>= 1.6.15)
-      nokogiri (= 1.5.10)
+      nokogiri (>= 1.5.10)
       rake
       rdoc
+      semver
     json (1.8.3)
-    jwt (1.0.0)
-    multi_json (1.10.1)
+    jwt (1.5.1)
+    multi_json (1.12.1)
     multi_xml (0.5.5)
-    multipart-post (1.2.0)
-    nokogiri (1.5.10)
-    oauth2 (1.0.0)
+    multipart-post (2.0.0)
+    nokogiri (1.6.7.2)
+    oauth2 (1.1.0)
       faraday (>= 0.8, < 0.10)
-      jwt (~> 1.0)
+      jwt (~> 1.0, < 1.5.2)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
-      rack (~> 1.2)
-    rack (1.5.2)
-    rake (10.2.2)
-    rdoc (3.12.2)
+      rack (>= 1.2, < 3)
+    pkg-config (1.1.7)
+    rack (1.6.4)
+    rake (11.1.2)
+    rdoc (4.2.2)
       json (~> 1.4)
+    redcarpet (3.3.4)
     rspec (3.4.0)
       rspec-core (~> 3.4.0)
       rspec-expectations (~> 3.4.0)
       rspec-mocks (~> 3.4.0)
-    rspec-core (3.4.1)
+    rspec-core (3.4.4)
       rspec-support (~> 3.4.0)
     rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -54,15 +63,21 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.4.0)
     rspec-support (3.4.1)
+    semver (1.0.1)
+    thread_safe (0.3.5)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.0)
-  jeweler (~> 1.8)
-  rdoc (~> 3.12)
-  rspec (~> 3.4)
+  github-markup (~> 1.4)
+  gobject-introspection (~> 3.0)
+  jeweler (~> 2.0)
+  redcarpet (~> 3.3)
+  rspec (~> 3.3)
+  yard (~> 0.8)
 
 BUNDLED WITH
-   1.10.6
+   1.11.2

data/{LICENSE → LICENSE.txt}

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Timothy Elliott
+Copyright (c) 2014 John Cupitt
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,30 +1,35 @@
-# ruby-vips : A fast image processing extension for Ruby.
+# ruby-vips
 
-[![Build Status](https://secure.travis-ci.org/jcupitt/ruby-vips.png)](http://travis-ci.org/jcupitt/ruby-vips)
+*API break:* version 1.0 of this gem is an API break, see below for some notes
+on why there is a break and how to update your code. 
+The older `ruby-vips` is still here and still maintained in branch 
+`0.3-stable`.
 
-This is `ruby-vips`, a gem for the 
-[libvips](http://www.vips.ecs.soton.ac.uk) image processing library. 
-This gem is still being maintained, but for new projects you should look at
-the newer [ruby-vips8](https://rubygems.org/gems/ruby-vips8) gem. 
+This gem provides a Ruby binding for the [vips image processing
+library](http://www.vips.ecs.soton.ac.uk). 
 
-ruby-vips is fast and it can work without needing the 
-entire image to be loaded into memory. For example, the benchmark at 
+`ruby-vips` is fast and it can work without needing to have the 
+entire image loaded into memory. Programs that use `ruby-vips` don't
+manipulate images directly, instead they create pipelines of image processing
+operations building on a source image. When the end of the pipe is connected
+to a destination, the whole pipline executes at once, streaming the image
+in parallel from source to destination a section at a time. 
+
+For example, the benchmark at 
 [vips-benchmarks](https://github.com/stanislaw/vips-benchmarks) loads a large
-image, crops, shrinks, sharpens and saves again:
+image, crops, shrinks, sharpens and saves again, and repeats 10 times. 
 
 ```text
 real time in seconds, fastest of three runs
 benchmark       tiff	jpeg
-ruby-vips.rb    2.77	2.98	
-ruby-vips8.rb   2.97	3.29	
+ruby-vips.rb    2.97	3.29	
 image-magick    8.18	9.71	
 rmagick.rb      9.22	10.06	
 image_sci.rb    9.39	7.20	
 
 peak memory use in bytes
 benchmark       peak RSS
-ruby-vips.rb    107340
-ruby-vips8.rb   117604
+ruby-vips.rb    117604
 image_sci.rb    146536
 rmagick.rb      3352020
 ```
@@ -35,83 +40,39 @@ There's a handy blog post explaining [how libvips opens
 files](http://libvips.blogspot.co.uk/2012/06/how-libvips-opens-file.html)
 which gives some more background.
 
-ruby-vips allows you to set up pipelines that don't get executed until you
-output the image to disk or to a string. This means you can create,
-manipulate, and pass around Image objects without incurring any memory or CPU
-costs. The image is not actually processed until you write the image to memory
-or to disk.
-
-*note*: ruby-vips will work with versions of libvips as far back as 7.12, but
-with missing features and with reduced performance. For best results, use the 
-latest libvips you can.
-
-## Requirements.
+## Requirements
 
   * OS X or Linux
-  * MRI 1.8.7, 1.9.3
-  * libvips 7.24 and later (it will work with earlier libvips, but some
-    features may not be functional)
+  * libvips 8.2 and later
 
 ## Installation prerequisites
 
-### Ubuntu 
-
-```bash
-$ apt-get install libvips-dev
-```
-
 ### OS X 
 
 Install [homebrew](http://mxcl.github.com/homebrew) and enter:
 
 ```bash
-$ brew tap homebrew/science
-$ brew install vips 
+$ brew install homebrew/science/vips
 ```
 
-You may see some harmless warnings. 
-
 To verify that your vips install is working, try:
 
 ```bash
 $ vips --version
-vips-7.42.1-Sat Dec 27 12:01:43 GMT 2014
-```
-
-libvips has a lot of optional dependencies. You
-may not need all of them.  True `brew info vips` to see what you have enabled
-and what is disabled. See also [the notes
-here](http://www.vips.ecs.soton.ac.uk/index.php?title=Build_on_OS_X) for
-more information.
-
-If you want to build things outside homebrew which depend on vips,
-such as ruby-vips, your pkg-config will need to be working. To test
-`pkg-config`, try:
-
-```bash
-$ pkg-config vips --modversion
-```
-
-If you see a version number, you are OK. If you don't, either update your
-homebrew, or try adjusting `PKG_CONFIG_PATH`. At various times homebrew has
-needed various settings. You might need to point it at homebrew or even at
-libxml2. 
-
-To verify that your `pkg-config` is working correctly with vips, try:
-
-```bash
-$ pkg-config vips --libs
--L/usr/local/Cellar/vips/7.42.1/lib ... a lot of stuff
+vips-8.2.1
 ```
 
-TODO: Describe & test with macports.
-
 ### Other platforms
 
-See [Installation on various
-platforms](https://github.com/jcupitt/ruby-vips/wiki/installation-on-various-platforms).
+You need to install libvips from source since 8.2 has not been packaged yet
+(Jan 2016).
 
-### Installing the gem.
+Download a tarball from the 
+[libvips website](http://www.vips.ecs.soton.ac.uk/supported/current), or build
+from [the git repository](https://github.com/jcupitt/libvips) and see the
+README.
+
+## Installing the gem.
 
 ```bash
 $ gem install ruby-vips
@@ -123,105 +84,100 @@ or include it in Gemfile:
 gem 'ruby-vips'
 ```
 
-For a debug build:
-
-```bash
-$ gem install ruby-vips -- --enable-debug
-```
+And take a look in `examples/`. There is full yard documentation, take a look
+there too.
 
-## Documentation.
-
-ruby-vips has [rdoc
-documentation](http://rubydoc.info/gems/ruby-vips/frames). Also
-see [Wiki page](https://github.com/jcupitt/ruby-vips/wiki)
-
-## Small example
-
-See also the
-[examples](https://github.com/jcupitt/ruby-vips/tree/master/examples)
-directory.
+# Example
 
 ```ruby
-require 'rubygems'
 require 'vips'
 
-include VIPS
+im = Vips::Image.new_from_file filename
 
-# Create an image object. It will not actually load the pixel data until 
-# needed. 
-im = Image.jpeg('mypic.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
+# http://www.vips.ecs.soton.ac.uk/supported/current/doc/html/libvips/libvips-conversion.html#vips-embed
+im = im.embed 100, 100, 3000, 3000, :extend => :mirror
 
-# You can read all the header fields without triggering a pixel load.
-puts "it's #{im.x_size} pixels across!"
+# multiply the green (middle) band by 2, leave the other two alone
+im *= [1, 2, 1]
 
-# Shrink the jpeg by a factor of four when loading -- huge speed and CPU
-# improvements on large images.
-im = Image.jpeg('mypic.jpg', :shrink_factor => 4)
-puts "but only #{im.x_size} pixels when we shrink on load"
+# 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
 
-# Add a shrink by a factor of two to the pipeline. This will not actually be
-# executed yet.
-im_shrink_by_two = im.shrink(2)
+# finally, write the result back to a file on disk
+im.write_to_file output_filename
+```
 
-# Write out the shrunk image to a PNG file. This is where the image is
-# actually loaded and resized. With images that allow for random access from
-# the hard drive (VIPS native format, tiled OpenEXR, ppm/pbm/pgm/pfm, tiled
-# tiff, and RAW images), the entire image is never read into memory.
-# For other formats, the image is either decompressed to a temporary disc 
-# file and then processed from there, or, if you give the :sequential hint, 
-# streamed directly from the file.
-im_shrink_by_two.png('out.png', :interlace => true)
+# Why the API break?
 
-# All ruby-vips image commands can be chained, so the above sequence could
-# be written as:
-Image.jpeg('mypic.jpg', :shrink_factor => 4).shrink(2).png('out.png')
+There's been a `ruby-vips` for a few years now. 
+It was written by a Ruby
+expert, it works well, it includes a test-suite, and has pretty full
+documentation. Why rewrite?
 
-# You hint sequential mode in the loader, so this will stream directly from
-# the source image:
-Image.jpeg('large.png', :sequential => true).shrink(2).png('out.png')
+`ruby-vips` 0.3 was based on the old vips7 API. There's now vips8, 
+which adds several
+very useful new features:
 
-# The statement above will load the jpeg (pre-shrunk by a factor of four),
-# shrink the image again by a factor of two, and then save as a png image.
+* [GObject](https://developer.gnome.org/gobject/stable/)-based API with full
+  introspection. You can discover the vips8 API at runtime. This means that if
+  libvips gets a new operator, any binding that goes via vips8 will 
+  get the new thing immediately. With vips7, whenever libvips was changed, all
+  the bindings needed to be changed too.
 
-# If you want to let vips determine file formats, you can use the generic
-# reader and writer:
-Image.new('mypic.jpg').shrink(2).write('out.png')
+* No C required. Thanks to
+  [gobject-introspection](https://wiki.gnome.org/Projects/GObjectIntrospection)
+  you can write the binding in Ruby itself, there's no need for any C. This
+  makes it a lot smaller and more portable. 
 
-# You can also read and write images from memory areas. For example:
+* vips7 probably won't get new features. vips7 doesn't really exist any more:
+  the API is still there, but now just a thin compatibility layer over vips8.
+  New features may well not get added to the vips7 API.
 
-jpeg_data = IO.read('mypic.jpg')
-reader = JPEGReader.new(jpeg_data, :shrink_factor => 2, :fail_on_warn => true)
-im = reader.read_buffer
+There are some more minor pluses as well:
 
-# As above, the image will not be processed until the .to_memory() method 
-# is called, and then will only decompress the section being processed. 
-# You will need to have all of the compressed data in memory at once though. 
+* Named and optional arguments. vips8 lets you have optional and required
+  arguments, both input and output, and optional arguments can have default
+  values. 
 
-# Note that this means you will get a coredump if you free the compressed
-# image buffer (jpeg_data above) before the write has completed.
+* Operation cache. vips8 keeps track of the last 1,000 or so operations and
+  will automatically reuse results when it can. This can give a huge speedup
+  in some cases.
 
-writer = PNGWriter.new(im, :compression => 2, :interlace => false)
-png_data = writer.to_memory
-IO.write('out.png', png_data)
+* vips8 is much simpler and more regular. For example, 
+  ruby-vips had to work hard to offer a nice loader system, but that's all
+  built into vips8. It can do things like load and save formatted images to 
+  and from memory buffers as well, which just wasn't possible before. 
 
-# Only JPEG, PNG and uncompressed memory images are supported at the moment,
-# and png memory read is only in vips-7.34 and later.
+This binding adds some extra useful features over the old `ruby-vips` binding.
 
-# We hope to add other formats in future. 
+* Full set of arithmetic operator overloads.
 
-png_data = IO.read('mypic.png')
-reader = PNGReader.new(png_data)
-im = reader.read_buffer
+* Automatic constant expansion. You can write things like
+  `image.bandjoin(255)` and the 255 will be automatically expanded to an image 
+  and attached as an extra band. You can mix int, float, scalar, vector and
+  image constants freely.
 
-writer = JPEGWriter.new(im, :quality => 50)
-jpeg_data = writer.to_memory
-IO.write('out.jpg', jpeg_data)
+# How to update your code
 
-```
+* `VIPS::` becomes `Vips::`
+
+* `VIPS::Image.new(filename)` becomes `Vips::Image.new_from_file(filename)`. 
+  `VIPS::Image.jpeg(filename)` also becomes 
+  `Vips::Image.new_from_file(filename)`, similarly for other formats.  
+
+* `#write(filename)` becomes `#write_to_file(filename)`. `#png(filename)` also
+  becomes `#write_to_file(filename)`, same for all other
+  formats.
 
-## Why use ruby-vips?
+* Most member functions are unchanged, but check the yard docs. You can also
+  use the C docs directly, since `ruby-vips` is now a very thin layer over the
+  C API. See the docs for the `Vips` class for guidance. 
 
-  - It supports over 250 low-level image and color manipulation operations.
-  - Operations are chainable and do not get executed until the image is sent to an output.
-  - Memory use is low, even for very, very large images.
-  - Fastest ruby library for resizing large images. See [benchmarks at the official libvips website](http://www.vips.ecs.soton.ac.uk/index.php?title=Speed_and_Memory_Use) and [vips-benchmarks](https://github.com/stanislaw/vips-benchmarks)
+* There are lots of nice new features, see the docs and examples.