Module: Prawn::Images

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

Defined Under Namespace

Classes: Image, JPG, PNG

Stable API (collapse)

Instance Method Details

- (Object) image(file, options = {})

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:

file

path to file or an object that responds to #read and #rewind

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::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)



62
63
64
65
66
67
68
69
70
# File 'lib/prawn/images.rb', line 62

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