prawn-git 2.0.1

data/lib/prawn/image_handler.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+# ImageHandler provides a way to register image processors with Prawn
+#
+# Contributed by Evan Sharp in November 2013.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  # @group Extension API
+
+  def self.image_handler
+    @image_handler ||= ImageHandler.new
+  end
+
+  class ImageHandler
+    def initialize
+      @handlers = []
+    end
+
+    def register(handler)
+      @handlers.delete(handler)
+      @handlers.push handler
+    end
+
+    def register!(handler)
+      @handlers.delete(handler)
+      @handlers.unshift handler
+    end
+
+    def unregister(handler)
+      @handlers.reject!{ |h| h == handler }
+    end
+
+    def find(image_blob)
+      handler = @handlers.find{ |h| h.can_render? image_blob }
+
+      return handler if handler
+
+      raise Prawn::Errors::UnsupportedImageType,
+            "image file is an unrecognised format"
+    end
+  end
+end

data/lib/prawn/images.rb

@@ -0,0 +1,199 @@
+# 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'
+require 'pathname'
+
+module Prawn
+
+  module Images
+    # @group Stable API
+
+    # Add the image at filename to the current page. Currently only
+    # JPG and PNG files are supported. (Note that processing PNG
+    # images with alpha channels can be processor and memory intensive.)
+    #
+    # Arguments:
+    # <tt>file</tt>:: path to file or an object that responds to #read and #rewind
+    #
+    # Options:
+    # <tt>:at</tt>:: an array [x,y] with the location of the top left corner of the image.
+    # <tt>:position</tt>::  One of (:left, :center, :right) or an x-offset
+    # <tt>:vposition</tt>::  One of (:top, :center, :center) or an y-offset
+    # <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
+    # <tt>:fit</tt>:: scale the dimensions of the image proportionally to fit inside [width,height]
+    #
+    #   Prawn::Document.generate("image2.pdf", :page_layout => :landscape) do
+    #     pigs = "#{Prawn::DATADIR}/images/pigs.jpg"
+    #     image pigs, :at => [50,450], :width => 450
+    #
+    #     dice = "#{Prawn::DATADIR}/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.
+    #
+    #
+    # If :at is provided, the image will be place in the current page but
+    # the text position will not be changed.
+    #
+    #
+    # If instead of an explicit filename, an object with a read method is
+    # passed as +file+, you can embed images from IO objects and things
+    # that act like them (including Tempfiles and open-uri objects).
+    #
+    #   require "open-uri"
+    #
+    #   Prawn::Document.generate("remote_images.pdf") do
+    #     image open("http://prawn.majesticseacreature.com/media/prawn_logo.png")
+    #   end
+    #
+    # This method returns an image info object which can be used to check the
+    # dimensions of an image object if needed.
+    # (See also: Prawn::Images::PNG , Prawn::Images::JPG)
+    #
+    def image(file, options={})
+      Prawn.verify_options [:at, :position, :vposition, :height,
+                            :width, :scale, :fit], options
+
+      pdf_obj, info = build_image_object(file)
+      embed_image(pdf_obj, info, options)
+
+      info
+    end
+
+
+    # Builds an info object (Prawn::Images::*) and a PDF reference representing
+    # the given image. Return a pair: [pdf_obj, info].
+    #
+    # @private
+    def build_image_object(file)
+      io = verify_and_open_image(file)
+      image_content = io.read
+      image_sha1 = Digest::SHA1.hexdigest(image_content)
+
+      # if this image has already been embedded, just reuse it
+      if image_registry[image_sha1]
+        info = image_registry[image_sha1][:info]
+        image_obj = image_registry[image_sha1][:obj]
+      else
+        # Build the image object
+        info = Prawn.image_handler.find(image_content).new(image_content)
+
+        # Bump PDF version if the image requires it
+        renderer.min_version(info.min_pdf_version) if info.respond_to?(:min_pdf_version)
+
+        # Add the image to the PDF and register it in case we see it again.
+        image_obj = info.build_pdf_object(self)
+        image_registry[image_sha1] = {:obj => image_obj, :info => info}
+      end
+
+      [image_obj, info]
+    end
+
+    # Given a PDF image resource <tt>pdf_obj</tt> that has been added to the
+    # page's resources and an <tt>info</tt> object (the pair returned from
+    # build_image_object), embed the image according to the <tt>options</tt>
+    # given.
+    #
+    # @private
+    def embed_image(pdf_obj, info, options)
+      # find where the image will be placed and how big it will be
+      w,h = info.calc_image_dimensions(options)
+
+      if options[:at]
+        x,y = map_to_absolute(options[:at])
+      else
+        x,y = image_position(w,h,options)
+        move_text_position h
+      end
+
+      # add a reference to the image object to the current page
+      # resource list and give it a label
+      label = "I#{next_image_id}"
+      state.page.xobjects.merge!(label => pdf_obj)
+
+      cm_params = PDF::Core.real_params([ w, 0, 0, h, x, y - h])
+      renderer.add_content("\nq\n#{cm_params} cm\n/#{label} Do\nQ")
+    end
+
+    private
+
+    def verify_and_open_image(io_or_path)
+      # File or IO
+      if io_or_path.respond_to?(:rewind)
+        io = io_or_path
+        # Rewind if the object we're passed is an IO, so that multiple embeds of
+        # the same IO object will work
+        io.rewind
+        # read the file as binary so the size is calculated correctly
+        # guard binmode because some objects acting io-like don't implement it
+        io.binmode if io.respond_to?(:binmode)
+        return io
+      end
+      # String or Pathname
+      io_or_path = Pathname.new(io_or_path)
+      raise ArgumentError, "#{io_or_path} not found" unless io_or_path.file?
+      io = io_or_path.open('rb')
+      io
+    end
+
+    def image_position(w,h,options)
+      options[:position] ||= :left
+
+      y = case options[:vposition]
+      when :top
+        bounds.absolute_top
+      when :center
+        bounds.absolute_top - (bounds.height - h) / 2.0
+      when :bottom
+        bounds.absolute_bottom + h
+      when Numeric
+        bounds.absolute_top - options[:vposition]
+      else
+        determine_y_with_page_flow(h)
+      end
+
+      x = case options[:position]
+      when :left
+        bounds.left_side
+      when :center
+        bounds.left_side + (bounds.width - w) / 2.0
+      when :right
+        bounds.right_side - w
+      when Numeric
+        options[:position] + bounds.left_side
+      end
+
+      return [x,y]
+    end
+
+    def determine_y_with_page_flow(h)
+      if overruns_page?(h)
+        bounds.move_past_bottom
+      end
+      self.y
+    end
+
+    def overruns_page?(h)
+      (self.y - h) < reference_bounds.absolute_bottom
+    end
+
+    def image_registry
+      @image_registry ||= {}
+    end
+
+    def next_image_id
+      @image_counter ||= 0
+      @image_counter += 1
+    end
+  end
+end

data/lib/prawn/images/image.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+# image.rb : Base class for image info objects
+#
+# Copyright September 2011, Brad Ediger. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'digest/sha1'
+
+module Prawn
+  module Images
+    class Image
+      # @group Extension API
+
+      def calc_image_dimensions(options)
+        w = options[:width] || width
+        h = options[:height] || height
+
+        if options[:width] && !options[:height]
+          wp = w / width.to_f
+          w = width * wp
+          h = height * wp
+        elsif options[:height] && !options[:width]
+          hp = h / height.to_f
+          w = width * hp
+          h = height * hp
+        elsif options[:scale]
+          w = width * options[:scale]
+          h = height * options[:scale]
+        elsif options[:fit]
+          bw, bh = options[:fit]
+          bp = bw / bh.to_f
+          ip = width / height.to_f
+          if ip > bp
+            w = bw
+            h = bw / ip
+          else
+            h = bh
+            w = bh * ip
+          end
+        end
+        self.scaled_width = w
+        self.scaled_height = h
+
+        [w,h]
+      end
+    end
+  end
+end

data/lib/prawn/images/jpg.rb

@@ -0,0 +1,91 @@
+# 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 JPG image that we need to embed them in a PDF
+    #
+    class JPG < Image
+      # @group Extension API
+
+      attr_reader :width, :height, :bits, :channels
+      attr_accessor :scaled_width, :scaled_height
+
+      JPEG_SOF_BLOCKS = [0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF]
+
+      def self.can_render?(image_blob)
+        image_blob[0, 3].unpack("C*") == [255, 216, 255]
+      end
+
+      # Process a new JPG image
+      #
+      # <tt>:data</tt>:: A binary string of JPEG data
+      #
+      def initialize(data)
+        @data = data
+        d = StringIO.new(@data)
+        d.binmode
+
+        c_marker = 0xff # Section marker.
+        d.seek(2)    # Skip the first two bytes of JPEG identifier.
+        loop do
+          marker, code, length = d.read(4).unpack('CCn')
+          raise "JPEG marker not found!" if marker != c_marker
+
+          if JPEG_SOF_BLOCKS.include?(code)
+            @bits, @height, @width, @channels = d.read(6).unpack("CnnC")
+            break
+          end
+
+          d.seek(length - 2, IO::SEEK_CUR)
+        end
+      end
+
+      # Build a PDF object representing this image in +document+, and return
+      # a Reference to it.
+      #
+      def build_pdf_object(document)
+        color_space = case channels
+        when 1
+          :DeviceGray
+        when 3
+          :DeviceRGB
+        when 4
+          :DeviceCMYK
+        else
+          raise ArgumentError, 'JPG uses an unsupported number of channels'
+        end
+
+        obj = document.ref!(
+          :Type             => :XObject,
+          :Subtype          => :Image,
+          :ColorSpace       => color_space,
+          :BitsPerComponent => bits,
+          :Width            => width,
+          :Height           => height
+        )
+
+        # add extra decode params for CMYK images. By swapping the
+        # min and max values from the default, we invert the colours. See
+        # section 4.8.4 of the spec.
+        if color_space == :DeviceCMYK
+          obj.data[:Decode] = [ 1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0 ]
+        end
+
+        obj.stream << @data
+        obj.stream.filters << :DCTDecode
+        obj
+      end
+
+    end
+  end
+end

data/lib/prawn/images/png.rb

@@ -0,0 +1,290 @@
+# encoding: ASCII-8BIT
+
+# 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'
+require 'enumerator'
+
+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 < Image
+      # @group Extension API
+
+      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
+      attr_accessor :scaled_width, :scaled_height
+
+      def self.can_render?(image_blob)
+        image_blob[0, 8].unpack("C*") == [137, 80, 78, 71, 13, 10, 26, 10]
+      end
+
+      # Process a new PNG image
+      #
+      # <tt>data</tt>:: A binary string of PNG data
+      #
+      def initialize(data)
+        data = StringIO.new(data.dup)
+
+        data.read(8)  # Skip the default header
+
+        @palette  = ""
+        @img_data = ""
+        @transparency = {}
+
+        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
+              raise Errors::UnsupportedImageType,
+                "Pallete-based transparency in PNG is not currently supported.\n" +
+                "See https://github.com/prawnpdf/prawn/issues/783"
+            when 0
+              # Greyscale. Corresponding to entries in the PLTE chunk.
+              # Grey is two bytes, range 0 .. (2 ^ bit-depth) - 1
+              grayval = data.read(chunk_size).unpack("n").first
+              @transparency[:grayscale] = grayval
+            when 2
+              # True colour with proper alpha channel.
+              @transparency[:rgb] = data.read(chunk_size).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
+
+        @img_data = Zlib::Inflate.inflate(@img_data)
+      end
+
+      # number of color components to each pixel
+      #
+      def colors
+        case self.color_type
+        when 0, 3, 4
+          return 1
+        when 2, 6
+          return 3
+        end
+      end
+
+      # split the alpha channel data from the raw image data in images
+      # where it's required.
+      #
+      def split_alpha_channel!
+        split_image_data if alpha_channel?
+      end
+
+      def alpha_channel?
+        @color_type == 4 || @color_type == 6
+      end
+
+      # Build a PDF object representing this image in +document+, and return
+      # a Reference to it.
+      #
+      def build_pdf_object(document)
+        if compression_method != 0
+          raise Errors::UnsupportedImageType,
+            'PNG uses an unsupported compression method'
+        end
+
+        if filter_method != 0
+          raise Errors::UnsupportedImageType,
+            'PNG uses an unsupported filter method'
+        end
+
+        if interlace_method != 0
+          raise Errors::UnsupportedImageType,
+            'PNG uses unsupported interlace method'
+        end
+
+        # some PNG types store the colour and alpha channel data together,
+        # which the PDF spec doesn't like, so split it out.
+        split_alpha_channel!
+
+        case colors
+        when 1
+          color = :DeviceGray
+        when 3
+          color = :DeviceRGB
+        else
+          raise Errors::UnsupportedImageType,
+            "PNG uses an unsupported number of colors (#{png.colors})"
+        end
+
+        # build the image dict
+        obj = document.ref!(
+          :Type             => :XObject,
+          :Subtype          => :Image,
+          :Height           => height,
+          :Width            => width,
+          :BitsPerComponent => bits
+        )
+
+        # append the actual image data to the object as a stream
+        obj << img_data
+
+        obj.stream.filters << {
+          :FlateDecode => {
+            :Predictor => 15,
+            :Colors    => colors,
+            :BitsPerComponent => bits,
+            :Columns   => width
+          }
+        }
+
+        # sort out the colours of the image
+        if palette.empty?
+          obj.data[:ColorSpace] = color
+        else
+          # embed the colour palette in the PDF as a object stream
+          palette_obj = document.ref!({})
+          palette_obj << palette
+
+          # build the color space array for the image
+          obj.data[:ColorSpace] = [:Indexed,
+                                   :DeviceRGB,
+                                   (palette.size / 3) -1,
+                                   palette_obj]
+        end
+
+        # *************************************
+        # add transparency data if necessary
+        # *************************************
+
+        # For PNG color types 0, 2 and 3, the transparency data is stored in
+        # a dedicated PNG chunk, and is exposed via the transparency attribute
+        # of the PNG class.
+        if transparency[:grayscale]
+          # Use Color Key Masking (spec section 4.8.5)
+          # - An array with N elements, where N is two times the number of color
+          #   components.
+          val = transparency[:grayscale]
+          obj.data[:Mask] = [val, val]
+        elsif transparency[:rgb]
+          # Use Color Key Masking (spec section 4.8.5)
+          # - An array with N elements, where N is two times the number of color
+          #   components.
+          rgb = transparency[:rgb]
+          obj.data[:Mask] = rgb.collect { |x| [x,x] }.flatten
+        end
+
+        # For PNG color types 4 and 6, the transparency data is stored as a alpha
+        # channel mixed in with the main image data. The PNG class seperates
+        # it out for us and makes it available via the alpha_channel attribute
+        if alpha_channel?
+          smask_obj = document.ref!(
+            :Type             => :XObject,
+            :Subtype          => :Image,
+            :Height           => height,
+            :Width            => width,
+            :BitsPerComponent => bits,
+            :ColorSpace       => :DeviceGray,
+            :Decode           => [0, 1]
+          )
+          smask_obj.stream << alpha_channel
+
+          smask_obj.stream.filters << {
+            :FlateDecode => {
+              :Predictor => 15,
+              :Colors    => 1,
+              :BitsPerComponent => bits,
+              :Columns   => width
+            }
+          }
+          obj.data[:SMask] = smask_obj
+        end
+
+        obj
+      end
+
+      # Returns the minimum PDF version required to support this image.
+      def min_pdf_version
+        if bits > 8
+          # 16-bit color only supported in 1.5+ (ISO 32000-1:2008 8.9.5.1)
+          1.5
+        elsif alpha_channel?
+          # Need transparency for SMask
+          1.4
+        else
+          1.0
+        end
+      end
+
+      private
+
+      def split_image_data
+        alpha_bytes = bits / 8
+        color_bytes = colors * bits / 8
+
+        scanline_length  = (color_bytes + alpha_bytes) * self.width + 1
+        scanlines = @img_data.bytesize / scanline_length
+        pixels = self.width * self.height
+
+        data = StringIO.new(@img_data)
+        data.binmode
+
+        color_data = [0x00].pack('C') * (pixels * color_bytes + scanlines)
+        color = StringIO.new(color_data)
+        color.binmode
+
+        @alpha_channel = [0x00].pack('C') * (pixels * alpha_bytes + scanlines)
+        alpha = StringIO.new(@alpha_channel)
+        alpha.binmode
+
+        scanlines.times do |line|
+          data.seek(line * scanline_length)
+
+          filter = data.getbyte
+
+          color.putc filter
+          alpha.putc filter
+
+          self.width.times do
+            color.write data.read(color_bytes)
+            alpha.write data.read(alpha_bytes)
+          end
+        end
+
+        @img_data = color_data
+      end
+    end
+  end
+end