Merge pull request libvips#5 from stanislaw/master

jcupitt · jcupitt · commit d67f3f62be72 · 2012-06-22T05:39:07.000-07:00
Better markup for your example
diff --git a/README.md b/README.md
@@ -55,197 +55,202 @@ ruby-vips has [rdoc documentation](http://rubyvips.holymonkey.com).
 
 ## Example.
 
-    require 'rubygems'
-    require 'vips'
-    include VIPS
+```ruby
+require 'rubygems'
+require 'vips'
+include VIPS
 
-    # Create an image object. It will not actually load the image until needed.
-    im = Image.jpeg('mypic.jpg')
+# Create an image object. It will not actually load the image until needed.
+im = Image.jpeg('mypic.jpg')
 
-    # 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)
+# 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)
 
-    # 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)
+# 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)
 
-    # 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.
-    im_shrink_by_two.png('out.png', :interlace => true)
+# 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.
+im_shrink_by_two.png('out.png', :interlace => true)
 
-    # 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')
+# 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')
 
-    # 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.
+# 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.
 
-    # 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')
+# 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')
+```
 
 ## Longer example
 
-    #!/usr/bin/env ruby
-
-    require 'rubygems'
-    require 'vips'
-
-    include VIPS
-
-    # sample image shrinker for ruby-vips
-
-    # handy for leak checking, but not actually a complete shrinker. It takes 
-    # no account of things like colour profiles, for example
-    #
-    # see vipsthumbnail, part of the standard vips distrubution, for a complete
-    # shrink program:
-    #
-    # https://github.com/jcupitt/libvips/blob/master/tools/vipsthumbnail.c
-    #
-    # this demo ought to be worked up to include all that stuff
-
-    # test with:
-    #
-    # $ for i in {1..100}; do cp ~/pics/wtc.jpg t_$i.jpg; done
-    # $ soak.rb t_*.jpg
-    #
-    # where wtc.jpg is a 10,000 x 10,000 pixel RGB image
-    #
-    # with ruby-vips 0.1.1 and vips-7.28.7 I see a steady ~180mb of memuse as 
-    # this program runs (watching RES in top)
-    #
-    # 100mb of this is the vips operation cache, we could disable this to get 
-    # memuse down further if necessary
-    #
-    # on my laptop (2009 macbook running ubuntu 12.04):
-    #
-    # $ time ./soak.rb t_*.jpg
-    # real  0m47.809s
-    # user  0m33.626s
-    # sys   0m1.516s
-    #
-    # ie. about 0.5s real time to do a high-quality shrink of a 10k x 10k 
-    # rgb jpg
-
-    # target size we shrink to ... the image will fit inside a size x size box
-    size = 100
-
-    # we apply a slight sharpen to thumbnails to make then "pop" a bit
-    mask = [
-        [-1, -1,  -1],
-        [-1,  32, -1,],
-        [-1, -1,  -1]
-    ]
-    m = Mask.new mask, 24, 0 
-
-    # show what we do
-    # verbose = true
-    verbose = false
-
-    ARGV.each do |filename|
-        puts "loop #{filename} ..."
-
-        # get the image size ... ,new() only decompresses pixels on access, 
-	# just opening and getting properties is fast
-        # 
-        # this will decode small images to a memory buffer, large images to a
-        # temporary disc file which is then mapped
-        #
-        # vips also supports sequential mode access, where the image is 
-	# directly streamed from the source, through the decode library, to 
-	# the destination, but ruby-vips does not yet expose this, 
-	# unfortunately
-        #
-        # see 
-        #
-        #   http://libvips.blogspot.co.uk/2012/02/sequential-mode-read.html
-        #
-        # enabling this mode would help speed up tiff and png thumbnailing and
-        # reduce disc traffic, must get around to adding it to ruby-vips
-        a = Image.new(filename)
-
-        # largest dimension
-        d = [a.x_size, a.y_size].max
-
-        shrink = d / size.to_f
-        puts "shrink of #{shrink}" if verbose
-
-        # jpeg images can be shrunk very quickly during load, by a factor of 2, 
-        # 4 or 8
-        #
-        # if this is a jpeg, turn on shrink-on-load 
-        #
-        # a better file type test would be good here :-( vips has a nice one, 
-	# but it's not exposed in ruby-vips yet
-        if filename.end_with? ".jpg"
-        if shrink >= 8
-            load_shrink = 8
-        elsif shrink >= 4
-            load_shrink = 4
-        elsif shrink >= 2
-            load_shrink = 4
-        end
-
-        puts "jpeg shrink on load of #{load_shrink}" if verbose
-
-        a = Image.jpeg(filename, :shrink_factor => load_shrink)
-
-        # and recalculate the shrink we need, since the dimensions have changed
-        d = [a.x_size, a.y_size].max
-        shrink = d / size.to_f
-        end
-
-        # we shrink in two stages: we use a box filter (each pixel in output 
-	# is the average of a m x n box of pixels in the input) to shrink by 
-	# the largest integer factor we can, then an affine transform to get 
-	# down to the exact size we need
-        #
-        # if you just shrink with the affine, you'll get bad aliasing for large
-        # shrink factors (more than x2)
-
-        ishrink = shrink.to_i
-
-        # size after int shrink
-        id = (d / ishrink).to_i
-
-        # therefore residual float scale (note! not shrink)
-        rscale = size.to_f / id
-
-        puts "block shrink by #{ishrink}" if verbose
-        puts "residual scale by #{rscale}" if verbose
-
-        # vips has other interpolators, eg. :nohalo ... see the output of 
-	# "vips list classes" at the command-line
-        #
-        # :bicubic is well-known and mostly good enough
-        a = a.shrink(ishrink).affinei_resize(:bicubic, rscale)
-
-        # this will look a little "soft", apply a gentle sharpen
-        a = a.conv(m)
-
-        # finally ... write to the output
-        #
-        # this call will run the pipeline we have built above across all your 
-	# CPUs, though for a simple pipeline like this you'll be spending 
-	# most of your time in the file import / export libraries, which 
-	# are generally single-threaded
-        a = JPEGWriter.new(a, {:quality => 50})
-        a.write('test.jpg')
-
-        # force the GC to run and free up any memory vips is hanging on to
-        #
-        # without this you'll see memuse slowly climb until ruby runs the GC 
-        # for you
-        # 
-        # something to make ruby-vips drop refs to vips objects explicitly 
-	# would be nice 
-        GC.start
+```ruby
+
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'vips'
+
+include VIPS
+
+# sample image shrinker for ruby-vips
+
+# handy for leak checking, but not actually a complete shrinker. It takes 
+# no account of things like colour profiles, for example
+#
+# see vipsthumbnail, part of the standard vips distrubution, for a complete
+# shrink program:
+#
+# https://github.com/jcupitt/libvips/blob/master/tools/vipsthumbnail.c
+#
+# this demo ought to be worked up to include all that stuff
+
+# test with:
+#
+# $ for i in {1..100}; do cp ~/pics/wtc.jpg t_$i.jpg; done
+# $ soak.rb t_*.jpg
+#
+# where wtc.jpg is a 10,000 x 10,000 pixel RGB image
+#
+# with ruby-vips 0.1.1 and vips-7.28.7 I see a steady ~180mb of memuse as 
+# this program runs (watching RES in top)
+#
+# 100mb of this is the vips operation cache, we could disable this to get 
+# memuse down further if necessary
+#
+# on my laptop (2009 macbook running ubuntu 12.04):
+#
+# $ time ./soak.rb t_*.jpg
+# real  0m47.809s
+# user  0m33.626s
+# sys   0m1.516s
+#
+# ie. about 0.5s real time to do a high-quality shrink of a 10k x 10k 
+# rgb jpg
+
+# target size we shrink to ... the image will fit inside a size x size box
+size = 100
+
+# we apply a slight sharpen to thumbnails to make then "pop" a bit
+mask = [
+[-1, -1,  -1],
+[-1,  32, -1,],
+[-1, -1,  -1]
+]
+m = Mask.new mask, 24, 0 
+
+# show what we do
+# verbose = true
+verbose = false
+
+ARGV.each do |filename|
+  puts "loop #{filename} ..."
+
+  # get the image size ... ,new() only decompresses pixels on access, 
+  # just opening and getting properties is fast
+  # 
+  # this will decode small images to a memory buffer, large images to a
+  # temporary disc file which is then mapped
+  #
+  # vips also supports sequential mode access, where the image is 
+  # directly streamed from the source, through the decode library, to 
+  # the destination, but ruby-vips does not yet expose this, 
+  # unfortunately
+  #
+  # see 
+  #
+  #   http://libvips.blogspot.co.uk/2012/02/sequential-mode-read.html
+  #
+  # enabling this mode would help speed up tiff and png thumbnailing and
+  # reduce disc traffic, must get around to adding it to ruby-vips
+  a = Image.new(filename)
+
+  # largest dimension
+  d = [a.x_size, a.y_size].max
+
+  shrink = d / size.to_f
+  puts "shrink of #{shrink}" if verbose
+
+  # jpeg images can be shrunk very quickly during load, by a factor of 2, 
+  # 4 or 8
+  #
+  # if this is a jpeg, turn on shrink-on-load 
+  #
+  # a better file type test would be good here :-( vips has a nice one, 
+  # but it's not exposed in ruby-vips yet
+  if filename.end_with? ".jpg"
+    if shrink >= 8
+        load_shrink = 8
+    elsif shrink >= 4
+        load_shrink = 4
+    elsif shrink >= 2
+        load_shrink = 4
     end
 
+    puts "jpeg shrink on load of #{load_shrink}" if verbose
+
+    a = Image.jpeg(filename, :shrink_factor => load_shrink)
+
+    # and recalculate the shrink we need, since the dimensions have changed
+    d = [a.x_size, a.y_size].max
+    shrink = d / size.to_f
+  end
+
+  # we shrink in two stages: we use a box filter (each pixel in output 
+  # is the average of a m x n box of pixels in the input) to shrink by 
+  # the largest integer factor we can, then an affine transform to get 
+  # down to the exact size we need
+  #
+  # if you just shrink with the affine, you'll get bad aliasing for large
+  # shrink factors (more than x2)
+
+  ishrink = shrink.to_i
+
+  # size after int shrink
+  id = (d / ishrink).to_i
+
+  # therefore residual float scale (note! not shrink)
+  rscale = size.to_f / id
+
+  puts "block shrink by #{ishrink}" if verbose
+  puts "residual scale by #{rscale}" if verbose
+
+  # vips has other interpolators, eg. :nohalo ... see the output of 
+  # "vips list classes" at the command-line
+  #
+  # :bicubic is well-known and mostly good enough
+  a = a.shrink(ishrink).affinei_resize(:bicubic, rscale)
+
+  # this will look a little "soft", apply a gentle sharpen
+  a = a.conv(m)
+
+  # finally ... write to the output
+  #
+  # this call will run the pipeline we have built above across all your 
+  # CPUs, though for a simple pipeline like this you'll be spending 
+  # most of your time in the file import / export libraries, which 
+  # are generally single-threaded
+  a = JPEGWriter.new(a, {:quality => 50})
+  a.write('test.jpg')
+
+  # force the GC to run and free up any memory vips is hanging on to
+  #
+  # without this you'll see memuse slowly climb until ruby runs the GC 
+  # for you
+  # 
+  # something to make ruby-vips drop refs to vips objects explicitly 
+  # would be nice 
+  GC.start
+end
+```
+
 ## Why use ruby-vips?
 
   - It supports over 250 low-level image and color manipulation operations.
