Module: Prawn::Images

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

Overview

rubocop: disable Style/Documentation

Defined Under Namespace

Classes: Image, JPG, PNG

Stable API collapse

Instance Method Details

#build_image_object(file) ⇒ Object

Builds an info object (Prawn::Images::*) and a PDF reference representing the given image. Return a pair: [pdf_obj, info].



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/prawn/images.rb', line 72

def build_image_object(file)
  image_content = verify_and_read_image(file)
  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
    if info.respond_to?(:min_pdf_version)
      renderer.min_version(info.min_pdf_version)
    end

    # 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

#embed_image(pdf_obj, info, options) ⇒ Object

Given a PDF image resource pdf_obj that has been added to the page’s resources and an info object (the pair returned from #build_image_object), embed the image according to the options given.



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/prawn/images.rb', line 102

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[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

#image(file, options = {}) ⇒ Prawn::Images::Image

Add the image at file 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.)

If only one of :width or :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.

Examples:

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

Parameters:

  • file (String, IO) —

    Path to file or an object that responds to #read and #rewind.

  • options (Hash{Symbol => any}) (defaults to: {})

Options Hash (options):

  • :at (Array(Number, Number)) —

    The location of the top left corner of the image. If provided, the image will be place in the current page but the text position will not be changed.

  • :position (:left, :center, :right, Number) —

    Horizontal position relative to the current bounding box.

  • :vposition (:topm :center, :bottom, Number) —

    Vertical position relative to the current bounding box.

  • :height (Number) — default: actual height of the image —

    The height of the image.

  • :width (Number) — default: actual width of the image —

    The width of the image.

  • :scale (Number) —

    Scale the dimensions of the image proportionally.

  • :fit (Array(Number, Number)) —

    Scale the dimensions of the image proportionally to fit inside the rectangle of specified size (width, height).

Returns:

  • (Prawn::Images::Image) —

    An image handler. All image handlers provided by Prawn are subclasses of Image. This object can be used to check the image dimensions and get other format-specific information.

See Also:



56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/prawn/images.rb', line 56

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

  pdf_obj, info = build_image_object(file)
  embed_image(pdf_obj, info, options)

  info
end