Module: Prawn::Images

Included in:
Document
Defined in:
lib/prawn/images.rb,
lib/prawn/images/jpg.rb,
lib/prawn/images/png.rb

Defined Under Namespace

Classes: JPG, PNG

Instance Method Summary collapse

Instance Method Details

#image(file, options = {}) ⇒ Object

Add the image at filename to the current page. Currently only JPG and PNG files are supported.

NOTE: Prawn is very slow at rendering PNGs with alpha channels. The workaround for those who don’t mind installing RMagick is to use:

github.com/amberbit/prawn-fast-png

Arguments:

file

path to file or an object that responds to #read

Options:

:at

an array [x,y] with the location of the top left corner of the image.

:position

One of (:left, :center, :right) or an x-offset

:vposition

One of (:top, :center, :center) or an y-offset

:height

the height of the image [actual height of the image]

:width

the width of the image [actual width of the image]

:scale

scale the dimensions of the image proportionally

:fit

scale the dimensions of the image proportionally to fit inside [width,height]

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.

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)



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/prawn/images.rb', line 65

def image(file, options={})
  Prawn.verify_options [:at, :position, :vposition, :height, 
                        :width, :scale, :fit], options

  if file.respond_to?(:read)
    image_content = file.read
  else
    raise ArgumentError, "#{file} not found" unless File.file?(file)  
    image_content = File.binread(file)
  end
  
  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
    klass = case detect_image_format(image_content)
            when :jpg then Prawn::Images::JPG
            when :png then Prawn::Images::PNG
            end
    info = klass.new(image_content)

    # Bump PDF version if the image requires it
    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

  # find where the image will be placed and how big it will be  
  w,h = calc_image_dimensions(info, 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 => 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 ]
  
  return info
end