smartimage 0.0.1-java → 0.0.2-java

data/README.markdown

@@ -0,0 +1,164 @@
+SmartImage
+==========
+
+"It's like a Swiss Army Knife for images, but one of those tiny ones you can 
+ keep on your keychain"
+
+SmartImage provides a cross-platform solution for image compositing that works
+on both MRI and JRuby. If using RMagick feels like swatting a fly with a 
+nuclear missile, and ImageScience just doesn't get you there, SmartImage is 
+hopefully at that sweet spot in the middle.
+
+The functionality available in the current version is somewhat limited, but
+should be added easily in the future thanks to a focus on modularity and a
+clear codebase free of lots of platformisms that normally hinder portability.
+
+The goal of SmartImage is to support the most common image compositing tasks
+in a Ruby-like API while not becoming bloated and huge like RMagick, and also
+remaining portable across multiple Ruby implementations, including JRuby.
+
+Backends
+--------
+
+SmartImage works by implementing a platform-specific SmartImage::Canvas class
+that encompasses all of the low level image manipulation primitives.  Two such
+canvases are currently available:
+
+* SmartImage::RMagickCanvas: a canvas backend based on the RMagick gem
+* SmartImage::JavaCanvas: a canvas backend based on Java AWT/Graphics2D APIs
+
+Can it create thumbnails for my Ruby on Rails-based web application?
+--------------------------------------------------------------------
+
+Yes, SmartImage *CAN* create thumbnails for your Ruby on Rails-based web
+application!  And it can do it in the most cross-platform manner imaginable!
+If you are looking for a thumbnail solution that will allow you to safely 
+migrate your web application to JRuby in the future, look no further than 
+SmartImage.
+
+To use SmartImage in your Rails application, simply add the following to
+config/environment.rb:
+
+    config.gem 'smartimage'
+
+(there is an appropriate place to put this line, BTW.  The exact location
+is left as an exercise to the reader)
+
+That's it!  Now wherever you would like to generate thumbnails, use the
+following:
+
+    SmartImage.thumbnail_file(
+      "path/to/input.jpg", 
+      "path/to/output.jpg", 
+      :width  => 69,
+      :height => 42
+    )
+
+This will generate a thumbnail which is at most 69 pixels wide (but could be
+smaller) and at most 42 pixels tall (but again, could be smaller).  It looks
+at the file extension to determine the output format.  We specified a .jpg
+so it will output a JPEG encoded image.
+
+Why could it be smaller, you ask?  Because SmartImage preserves the aspect
+ratio of the original image by default.  SmartImage allows you to set aside
+space of a predetermined width/height, but will ensure images are scaled
+with their aspect ratio preserved.
+
+Don't like this behavior?  Want to stretch out your thumbnails all weird?
+Just turn it off:
+
+    SmartImage.thumbnail_file(
+      "path/to/input.jpg", 
+      "path/to/output.jpg", 
+      :width  => 69,
+      :height => 42,
+      :preserve_aspect_ratio => false
+    )
+  
+Tada!  Stretched-out images!  Yay!
+
+What if I want to work with raw image data instead of files?
+------------------------------------------------------------
+
+SmartImage provides both file-based and data-based methods for every API.  All
+the APIs are the same, except file-based APIs have "_file" on the end.
+
+For example, above we used the SmartImage.thumbnail_file API.  However, there's
+also a SmartImage.thumbnail API that works on raw image data:
+
+    thumbnail = SmartImage.thumbnail image, :width => 69, 
+                                            :height => 42, 
+                                            :format => :jpg
+                                          
+This API produces a thumbnail in-memory from the given input image, also 
+in-memory.  We've requested a .jpg thumbnail, with a max width of 69 and
+a max height of 42.
+
+If an image format isn't specified, the default is PNG.
+
+What other APIs are available?
+------------------------------
+
+SmartImage allows you to successively manipulate an image buffer.  Here's an
+example and below is the deconstruction:
+
+    SmartImage.new(69, 42) do |image|
+      image.composite_file 'mongoose.jpg', :width => 115,
+                                           :height => 95,
+                                           :preserve_aspect_ratio => false
+ 
+      image.alpha_mask_file 'mask.png'
+      image.composite_file  'overlay.png'
+      image.write 'output.png'
+    end
+  
+The first thing to notice is that SmartImage.new takes a width, a height, and
+a block.  Creating a new SmartImage makes a new image "canvas" that you can
+draw to.  However, all the drawing must take place within the block.  You
+can't do things with SmartImages outside the block.  The block yields you
+a SmartImage object that you can manipulate willy nilly within the block.
+But after the block, it's kaput, sorry.  This is because certain silly C 
+extensions lack the ability to garbage collect memory safely and require safe
+allocation and deallocation of memory.
+
+The first thing we do is composite an image file onto the buffer.  Just like
+the SmartImage.thumbnail_file method we give it an options has with a width,
+height, and aspect ratio preservation options.
+
+After that an alpha mask is applied.  SmartImage supports applying alpha masks
+in the form of grayscale images where white is opaque and black is transparent.
+
+After that, a glossy overlay is composited over the top of the canvas.
+
+When it's all done, we write to an output file.  We've specified 'output.png'
+so it will write a PNG image to the given file.
+
+Doesn't RMagick leak memory?
+----------------------------
+
+It does if you use it wrong.  There are experimental attempts to safely garbage
+collect RMagick images.  However, your best bet is to work with an API which is
+designed so you can't leak memory, which is exactly what SmartImage provides.
+
+SmartImage would be over 9000 times better if it...
+---------------------------------------------------
+
+Please fork me!  I'm sure there's a whole world of better backends that 
+SmartImage could be using on MRI-like interpreters than RMagick.  Imagine a
+lightweight FFI wrapper to libfreeimage or something to that effect.
+
+If there's something SmartImage doesn't do that you'd like it do to, please
+send me a pull request.  Just keep in mind that cross-implementation 
+consistency is a major focus of SmartImage, so if you implement a new image
+backend it should implement all methods of SmartImage::BaseCanvas, and if you
+wish to add a new method to either SmartImage or SmartImage::BaseCanvas it 
+should work across all implementations.
+
+Credits
+-------
+
+SmartImage assumes your Ruby interpreter supports the absurdly powerful RMagick
+library, unless you're running JRuby, in which case it uses the absurdly 
+powerful Java Graphics2D library and AWT.
+
+[Mongoose courtesy Wikimedia Commons](http://en.wikipedia.org/wiki/File:Mongoose.jpg)

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/smart_image.rb

@@ -32,6 +32,71 @@ class SmartImage
     def file_info(path)
       info File.read(path)
     end
+    
+    # Generate a thumbnail from the given image data
+    # Options:
+    # * width: max width of the image, or explicit width if not preserving
+    #   aspect ratio
+    # * height: ditto, except for height of course
+    # * preserve_aspect_ratio: if true, ensure image fits within the given
+    #   width/height restraints.
+    # * format: file extension you'd ordinarily apply to an output file of
+    #   the type you desire.  Supported formats are :jpg, :png, and :gif
+    #   (default :png)
+    def thumbnail(data, options = {})
+      source_info = info data
+      
+      opts = {
+        :width  => source_info.width,
+        :height => source_info.height,
+        :preserve_aspect_ratio => true,
+        :format => :png
+      }.merge(options)
+      
+      width, height = calculate_aspect_ratio source_info, opts
+      
+      # Set res so we can assign it within the SmartImage.new block
+      res = nil
+      
+      SmartImage.new(width, height) do |image|
+        image.composite data, :width  => width,
+                              :height => height,
+                              :preserve_aspect_ratio => false
+                              
+        res = image.encode opts[:format]
+      end
+      
+      res
+    end
+    
+    # Generate a thumbnail file from a given input file
+    # Accepts the same options as SmartImage.thumbnail
+    def thumbnail_file(input_path, output_path, options = {})
+      opts = {
+        :format => File.extname(output_path).sub(/^\./, '')
+      }.merge(options)
+      
+      data = SmartImage.thumbnail File.read(input_path), options
+      File.open(output_path, 'w') { |file| file << data }
+    end
+    
+    # Solve aspect ratio constraints based on source image info and
+    # a given options hash.  This is mostly an internal method but
+    # if you find it useful knock yourself out.
+    def calculate_aspect_ratio(info, options)
+      if options[:preserve_aspect_ratio]
+        composited_size = SmartImage::RatioCalculator.new(
+          :source_width  => info.width,
+          :source_height => info.height,
+          :dest_width  => Integer(options[:width]), 
+          :dest_height => Integer(options[:height])
+        ).size
+
+        return composited_size.width, composited_size.height
+      else
+        return options[:width], options[:height]
+      end
+    end
   end
   
   # Create a new SmartImage of the given width and height.  Always takes a
@@ -55,6 +120,8 @@ class SmartImage
     @canvas = DeadCanvas.new
   end
   
+  # After the SmartImage#initialize block completes, the canvas is destroyed
+  # and replaced with a DeadCanvas that doesn't let you do anything
   class DeadCanvas
     def method_missing(*args)
       raise ArgumentError, "your image exists only within the SmartImage.new block"
@@ -81,18 +148,7 @@ class SmartImage
       :preserve_aspect_ratio => true
     }.merge(options)
   
-    if opts[:preserve_aspect_ratio]
-      composited_size = SmartImage::RatioCalculator.new(
-        :source_width  => info.width,
-        :source_height => info.height,
-        :dest_width  => Integer(opts[:width]), 
-        :dest_height => Integer(opts[:height])
-      ).size
-    
-      dest_width, dest_height = composited_size.width, composited_size.height
-    else
-      dest_width, dest_height = opts[:width], opts[:height]
-    end
+    dest_width, dest_height = self.class.calculate_aspect_ratio info, opts
   
     @canvas.composite data, :width  => Integer(dest_width),
                             :height => Integer(dest_height),

data/lib/smart_image/rmagick_canvas.rb

@@ -28,7 +28,11 @@ class SmartImage
       }.merge(options)      
       
       image.thumbnail! opts[:width], opts[:height]
-      @canvas.composite! image, opts[:x], opts[:y], OverCompositeOp
+      begin
+      	@canvas.composite! image, opts[:x], opts[:y], OverCompositeOp
+      ensure
+        image.destroy!
+      end
     end
     
     # Load the given file as an alpha mask for the image

data/lib/smartimage.rb

@@ -0,0 +1,15 @@
+# Maybe you want to:
+#
+#   require 'smartimage'
+#
+# Instead of:
+#
+#   require 'smart_image'
+#
+# Yes SmartImage is CamelCase and smart_image is the String#underscore of
+# that, but seriously, shouldn't require 'smartimage' Just Work?
+#
+# Yes, yes it should...
+#
+
+require 'smart_image'

data/smartimage-java.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{smartimage}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tony Arcieri"]
-  s.date = %q{2010-03-26}
+  s.date = %q{2010-03-30}
   s.description = %q{    SmartImage provides a cross-platform solution for image compositing that works on both MRI and JRuby.
     If using RMagick feels like swatting a fly with a nucler missile, and ImageScience just doesn't get 
     you there, SmartImage is hopefully at that sweet spot in the middle
@@ -17,13 +17,13 @@ Gem::Specification.new do |s|
   s.email = %q{tony@medioh.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.textile"
+     "README.markdown"
   ]
   s.files = [
     ".document",
      ".gitignore",
      "LICENSE",
-     "README.textile",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "lib/smart_image.rb",
@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
      "lib/smart_image/java_canvas.rb",
      "lib/smart_image/ratio_calculator.rb",
      "lib/smart_image/rmagick_canvas.rb",
+     "lib/smartimage.rb",
      "smartimage-java.gemspec",
      "smartimage.gemspec",
      "spec/fixtures/mask.png",

data/smartimage.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{smartimage}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tony Arcieri"]
-  s.date = %q{2010-03-26}
+  s.date = %q{2010-03-30}
   s.description = %q{    SmartImage provides a cross-platform solution for image compositing that works on both MRI and JRuby.
     If using RMagick feels like swatting a fly with a nucler missile, and ImageScience just doesn't get 
     you there, SmartImage is hopefully at that sweet spot in the middle
@@ -17,13 +17,13 @@ Gem::Specification.new do |s|
   s.email = %q{tony@medioh.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.textile"
+     "README.markdown"
   ]
   s.files = [
     ".document",
      ".gitignore",
      "LICENSE",
-     "README.textile",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "lib/smart_image.rb",
@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
      "lib/smart_image/java_canvas.rb",
      "lib/smart_image/ratio_calculator.rb",
      "lib/smart_image/rmagick_canvas.rb",
+     "lib/smartimage.rb",
      "smartimage-java.gemspec",
      "smartimage.gemspec",
      "spec/fixtures/mask.png",

data/spec/smart_image_spec.rb

@@ -41,4 +41,11 @@ describe SmartImage do
       image.write @output_dir + 'alpha_mask.png'
     end
   end
+  
+  it "generates thumbnails" do
+    output = @output_dir + 'thumbnail.jpg'
+    
+    SmartImage.thumbnail_file @mongoose, output, :width  => 115,
+                                                 :height => 95
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: smartimage
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: java
 authors: 
 - Tony Arcieri
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-26 00:00:00 -06:00
+date: 2010-03-30 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -40,12 +40,12 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.textile
+- README.markdown
 files: 
 - .document
 - .gitignore
 - LICENSE
-- README.textile
+- README.markdown
 - Rakefile
 - VERSION
 - lib/smart_image.rb
@@ -53,6 +53,7 @@ files:
 - lib/smart_image/java_canvas.rb
 - lib/smart_image/ratio_calculator.rb
 - lib/smart_image/rmagick_canvas.rb
+- lib/smartimage.rb
 - smartimage-java.gemspec
 - smartimage.gemspec
 - spec/fixtures/mask.png

data/README.textile

@@ -1,11 +0,0 @@
-h1. SmartImage
-
-Hi.  There will be a real README here soon, I promise.
-
-h2. Credits
-
-SmartImage assumes your Ruby interpreter supports the absurdly powerful RMagick
-library, unless you're running JRuby, in which case it uses the absurdly 
-powerful Java Graphics2D library and AWT.
-
-Mongoose courtesy Wikimedia Commons: http://en.wikipedia.org/wiki/File:Mongoose.jpg