prawn 0.1.0

data/lib/prawn/images.rb

@@ -0,0 +1,241 @@
+# encoding: ASCII-8BIT
+# images.rb : Implements PDF image embedding
+#
+# Copyright April 2008, James Healy, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'digest/sha1'
+
+module Prawn
+
+  module Images
+
+    # add the image at filename to the current page. Currently only
+    # JPG and PNG files are supported.
+    #
+    # Arguments:
+    # <tt>filename</tt>:: the path to the file to be embedded
+    #
+    # Options:
+    # <tt>:at</tt>:: the location of the top left corner of the image [current position]
+    # <tt>:height</tt>:: the height of the image [actual height of the image]
+    # <tt>:width</tt>:: the width of the image [actual width of the image]
+    # <tt>:scale</tt>:: scale the dimensions of the image proportionally
+    # 
+    #   Prawn::Document.generate("image2.pdf", :page_layout => :landscape) do     
+    #     pigs = "#{Prawn::BASEDIR}/data/images/pigs.jpg" 
+    #     image pigs, :at => [50,450], :width => 450                                      
+    #
+    #     dice = "#{Prawn::BASEDIR}/data/images/dice.png"
+    #     image dice, :at => [50, 450], :scale => 0.75 
+    #   end   
+    #
+    # If only one of :width / :height are provided, the image will be scaled
+    # proportionally.  When both are provided, the image will be stretched to 
+    # fit the dimensions without maintaining the aspect ratio.
+    #
+    def image(filename, options={})
+      raise ArgumentError, "#{filename} not found" unless File.file?(filename)  
+      
+      
+      read_mode = ruby_18 { "rb" } || ruby_19 { "rb:ASCII-8BIT" }
+      image_content =  File.open(filename, read_mode) { |f| f.read }
+      
+      image_sha1 = Digest::SHA1.hexdigest(image_content)
+
+      # register the fact that the current page uses images
+      proc_set :ImageC
+
+      # if this image has already been embedded, just reuse it
+      image_obj = image_registry[image_sha1]
+
+      if image_registry[image_sha1]
+        info = image_registry[image_sha1][:info]
+        image_obj = image_registry[image_sha1][:obj]
+      else
+        # build the image object and embed the raw data
+        image_obj = case detect_image_format(image_content)
+        when :jpg then
+          info = Prawn::Images::JPG.new(image_content)
+          build_jpg_object(image_content, info)
+        when :png then
+          info = Prawn::Images::PNG.new(image_content)
+          build_png_object(image_content, info)
+        end
+        image_registry[image_sha1] = {:obj => image_obj, :info => info}
+      end
+
+      # find where the image will be placed and how big it will be
+      x,y = translate(options[:at])
+      w,h = calc_image_dimensions(info, options)
+
+      # add a reference to the image object to the current page
+      # resource list and give it a label
+      label = "I#{next_image_id}"
+      page_xobjects.merge!( label => image_obj )
+
+      # add the image to the current page
+      instruct = "\nq\n%.3f 0 0 %.3f %.3f %.3f cm\n/%s Do\nQ"
+      add_content instruct % [ w, h, x, y - h, label ]
+    end
+
+    private
+
+    def build_jpg_object(data, jpg) 
+      color_space = case jpg.channels
+      when 1
+        :DeviceGray
+      when 4
+        :DeviceCMYK
+      else
+        :DeviceRGB
+      end
+      obj = ref(:Type       => :XObject,
+          :Subtype          => :Image,
+          :Filter           => :DCTDecode,
+          :ColorSpace       => color_space,
+          :BitsPerComponent => jpg.bits,
+          :Width            => jpg.width,
+          :Height           => jpg.height,
+          :Length           => data.size ) 
+      obj << data
+      return obj
+    end
+
+    def build_png_object(data, png)
+
+      if png.compression_method != 0
+        raise ArgumentError, 'PNG uses an unsupported compression method'
+      end
+
+      if png.filter_method != 0
+        raise ArgumentError, 'PNG uses an unsupported filter method'
+      end
+
+      if png.interlace_method != 0
+        raise ArgumentError, 'PNG uses unsupported interlace method'
+      end
+
+      if png.bits > 8
+        raise ArgumentError, 'PNG uses more than 8 bits'
+      end
+      
+      case png.color_type
+      when 0
+        ncolor = 1
+        color = :DeviceGray
+      when 2
+        ncolor = 3
+        color  = :DeviceRGB
+      when 3
+        ncolor = 1
+        color  = :DeviceRGB
+      when 6
+        ncolor = 3
+        color  = :DeviceRGB
+      else
+        raise ArgumentError, "PNG has unsupported color type" 
+      end                                   
+
+      # build the image dict
+      obj = ref(:Type             => :XObject,
+                :Subtype          => :Image,
+                :Height           => png.height,
+                :Width            => png.width,
+                :BitsPerComponent => png.bits,
+                :Length           => png.img_data.size,
+                :Filter           => :FlateDecode
+                
+               )
+
+      unless png.alpha_channel
+        obj.data[:DecodeParms] = {:Predictor => 15,
+                                  :Colors    => ncolor,
+                                  :Columns   => png.width}
+      end
+
+      # append the actual image data to the object as a stream
+      obj << png.img_data
+      
+      # sort out the colours of the image
+      if png.palette.empty?
+        obj.data[:ColorSpace] = color
+      else
+        # embed the colour palette in the PDF as a object stream
+        palette_obj = ref(:Length => png.palette.size)
+        palette_obj << png.palette
+
+        # build the color space array for the image
+        obj.data[:ColorSpace] = [:Indexed, 
+                                 :DeviceRGB,
+                                 (png.palette.size / 3) -1,
+                                 palette_obj]
+
+        # add transparency data if necessary
+        #if png.transparency && png.transparency[:type] == 'indexed'
+        #  obj.data[:Mask] = png.transparency[:data]
+        #end
+      end
+
+      if png.alpha_channel
+        smask_obj = ref(:Type             => :XObject,
+                        :Subtype          => :Image,
+                        :Height           => png.height,
+                        :Width            => png.width,
+                        :BitsPerComponent => 8,
+                        :Length           => png.alpha_channel.size,
+                        :Filter           => :FlateDecode,
+                        :ColorSpace       => :DeviceGray,
+                        :Decode           => [0, 1]
+                       )
+        smask_obj << png.alpha_channel
+        obj.data[:SMask] = smask_obj
+      end
+
+      return obj
+    end
+
+    def calc_image_dimensions(info, options)
+      # TODO: allow the image to be aligned in a box
+      w = options[:width] || info.width
+      h = options[:height] || info.height
+
+      if options[:width] && !options[:height]
+        wp = w / info.width.to_f 
+        w = info.width * wp
+        h = info.height * wp
+      elsif options[:height] && !options[:width]         
+        hp = h / info.height.to_f
+        w = info.width * hp
+        h = info.height * hp   
+      elsif options[:scale] 
+        w = info.width * options[:scale]
+        h = info.height * options[:scale]
+      end
+
+      [w,h]
+    end
+
+    def detect_image_format(content)
+      top = content[0,128]                       
+
+      if top[0, 3] == "\xff\xd8\xff"
+        return :jpg
+      elsif top[0, 8]  == "\x89PNG\x0d\x0a\x1a\x0a"
+        return :png
+      else
+        raise ArgumentError, "Unsupported Image Type"
+      end
+    end
+
+    def image_registry
+      @image_registry ||= {}
+    end
+
+    def next_image_id
+      @image_counter ||= 0
+      @image_counter += 1
+    end
+  end
+end

data/lib/prawn/images/jpg.rb

@@ -0,0 +1,43 @@
+# encoding: ASCII-8BIT
+
+# jpg.rb : Extracts the data from a JPG that is needed for embedding
+#
+# Copyright April 2008, James Healy.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'stringio'
+
+module Prawn
+  module Images
+    # A convenience class that wraps the logic for extracting the parts
+    # of a PNG image that we need to embed them in a PDF
+    class JPG #:nodoc:
+      attr_reader :width, :height, :bits, :channels
+
+      JPEG_SOF_BLOCKS = %W(\xc0 \xc1 \xc2 \xc3 \xc5 \xc6 \xc7 \xc9 \xca \xcb \xcd \xce \xcf)
+      JPEG_APP_BLOCKS = %W(\xe0 \xe1 \xe2 \xe3 \xe4 \xe5 \xe6 \xe7 \xe8 \xe9 \xea \xeb \xec \xed \xee \xef)
+
+      # Process a new JPG image
+      #
+      # <tt>:data</tt>:: A string containing a full PNG file
+      def initialize(data)
+        data = StringIO.new(data.dup)
+
+        c_marker = "\xff" # Section marker.
+        data.read(2)   # Skip the first two bytes of JPEG identifier.
+        loop do
+          marker, code, length = data.read(4).unpack('aan')
+          raise "JPEG marker not found!" if marker != c_marker
+
+          if JPEG_SOF_BLOCKS.include?(code)
+            @bits, @height, @width, @channels = data.read(6).unpack("CnnC")
+            break
+          end
+
+          buffer = data.read(length - 2)
+        end
+      end
+    end
+  end
+end

data/lib/prawn/images/png.rb

@@ -0,0 +1,178 @@
+# encoding: utf-8
+
+# png.rb : Extracts the data from a PNG that is needed for embedding
+#
+# Based on some similar code in PDF::Writer by Austin Ziegler
+#
+# Copyright April 2008, James Healy.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'stringio'
+
+module Prawn
+  module Images
+    # A convenience class that wraps the logic for extracting the parts
+    # of a PNG image that we need to embed them in a PDF
+    class PNG #:nodoc:
+      attr_reader :palette, :img_data, :transparency
+      attr_reader :width, :height, :bits
+      attr_reader :color_type, :compression_method, :filter_method
+      attr_reader :interlace_method, :alpha_channel
+
+      # Process a new PNG image
+      #
+      # <tt>:data</tt>:: A string containing a full PNG file
+      def initialize(data)
+        data = StringIO.new(data.dup)
+
+        data.read(8)  # Skip the default header
+
+        @palette  = ""
+        @img_data = ""
+
+        loop do
+          chunk_size  = data.read(4).unpack("N")[0]
+          section     = data.read(4)
+          case section
+          when 'IHDR'
+            # we can grab other interesting values from here (like width,
+            # height, etc)
+            values = data.read(chunk_size).unpack("NNCCCCC")
+
+            @width              = values[0]
+            @height             = values[1]
+            @bits               = values[2]
+            @color_type         = values[3]
+            @compression_method = values[4]
+            @filter_method      = values[5]
+            @interlace_method   = values[6]
+          when 'PLTE'
+            @palette << data.read(chunk_size)
+          when 'IDAT'
+            @img_data << data.read(chunk_size)
+          when 'tRNS'
+            # This chunk can only occur once and it must occur after the
+            # PLTE chunk and before the IDAT chunk
+            @transparency = {}
+            case @color_type
+            when 3
+              # Indexed colour, RGB. Each byte in this chunk is an alpha for
+              # the palette index in the PLTE ("palette") chunk up until the
+              # last non-opaque entry. Set up an array, stretching over all
+              # palette entries which will be 0 (opaque) or 1 (transparent).
+              @transparency[:type]  = 'indexed'
+              @transparency[:data]  = data.read(chunk_size).unpack("C*")
+            when 0
+              # Greyscale. Corresponding to entries in the PLTE chunk.
+              # Grey is two bytes, range 0 .. (2 ^ bit-depth) - 1
+              @transparency[:grayscale] = data.read(2).unpack("n")
+              @transparency[:type]      = 'indexed'
+            when 2
+              # True colour with proper alpha channel.
+              @transparency[:rgb] = data.read(6).unpack("nnn")
+            end
+          when 'IEND'
+            # we've got everything we need, exit the loop
+            break
+          else
+            # unknown (or un-important) section, skip over it
+            data.seek(data.pos + chunk_size)
+          end
+
+          data.read(4)  # Skip the CRC
+        end
+
+        # if our img_data contains alpha channel data, split it out
+        unfilter_image_data if @color_type == 6
+      end
+
+      private
+
+      def paeth(a, b, c) # left, above, upper left
+        p = a + b - c
+        pa = (p - a).abs
+        pb = (p - b).abs
+        pc = (p - c).abs
+
+        return a if pa <= pb && pa <= pc
+        return b if pb <= pc
+        c
+      end
+
+      def unfilter_image_data
+        data = Zlib::Inflate.inflate(@img_data).unpack 'C*'
+        @img_data = ""
+        @alpha_channel = ""
+        scanline_length = 4 * @width + 1 # for filter
+        row = 0
+        pixels = []
+        until data.empty? do
+          row_data = data.slice! 0, scanline_length
+          filter = row_data.shift
+          case filter
+          when 0 then # None
+          when 1 then # Sub
+            row_data.each_with_index do |byte, index|
+              left = index < 4 ? 0 : row_data[index - 4]
+              row_data[index] = (byte + left) % 256
+              #p [byte, left, row_data[index]]
+            end
+          when 2 then # Up
+            row_data.each_with_index do |byte, index|
+              col = index / 4
+              upper = row == 0 ? 0 : pixels[row-1][col][index % 4]
+              row_data[index] = (upper + byte) % 256
+            end
+          when 3 then # Average
+            row_data.each_with_index do |byte, index|
+              col = index / 4
+              upper = row == 0 ? 0 : pixels[row-1][col][index % 4]
+              left = index < 4 ? 0 : row_data[index - 4]
+
+              row_data[index] = (byte + ((left + upper)/2).floor) % 256
+            end
+          when 4 then # Paeth
+            left = upper = upper_left = nil
+            row_data.each_with_index do |byte, index|
+              col = index / 4
+
+              left = index < 4 ? 0 : row_data[index - 4]
+              if row == 0 then
+                upper = upper_left = 0
+              else
+                upper = pixels[row-1][col][index % 4]
+                upper_left = col == 0 ? 0 :
+                  pixels[row-1][col-1][index % 4]
+              end
+
+              paeth = paeth left, upper, upper_left
+              row_data[index] = (byte + paeth) % 256
+              #p [byte, paeth, row_data[index]]
+            end
+          else
+            raise ArgumentError, "Invalid filter algorithm #{filter}"
+          end
+
+          pixels << []
+          row_data.each_slice 4 do |slice|
+            pixels.last << slice
+          end
+          row += 1
+        end
+
+        # convert the pixel data to seperate strings for colours and alpha
+        pixels.each do |row|
+          row.each do |pixel|
+            @img_data << pixel[0,3].pack("C*")
+            @alpha_channel << pixel[3]
+          end
+        end
+
+        # compress the data
+        @img_data = Zlib::Deflate.deflate(@img_data)
+        @alpha_channel = Zlib::Deflate.deflate(@alpha_channel)
+      end
+    end
+  end
+end