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

#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 (:top, :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