Method: HexaPDF::Content::Canvas#xobject

Defined in:

lib/hexapdf/content/canvas.rb

#xobject(obj, at:, width: nil, height: nil) ⇒ Object Also known as: image

:call-seq:

canvas.xobject(filename, at:, width: nil, height: nil)       => xobject
canvas.xobject(io, at:, width: nil, height: nil)             => xobject
canvas.xobject(image_object, at:, width: nil, height: nil)   => image_object
canvas.xobject(form_object, at:, width: nil, height: nil)    => form_object

Draws the given XObject (either an image XObject or a form XObject) at the specified position and returns the XObject.

Any image format for which a HexaPDF::ImageLoader object is available and registered with the configuration option ‘image_loader’ can be used. PNG (lossless), JPEG (lossy) and PDF (vector) images are supported out of the box.

If the filename or the IO specifies a PDF file, the first page of this file is used to create a form XObject which is then drawn.

The at argument has to be an array containing two numbers specifying the bottom-left corner at which to draw the XObject.

If width and height are specified, the drawn XObject will have exactly these dimensions. If only one of them is specified, the other dimension is automatically calculated so that the aspect ratio is retained. If neither is specified, the width and height of the XObject are used (for images, 1 pixel being represented by 1 PDF point, i.e. 72 DPI).

Note: If a form XObject is drawn, all currently set graphics state parameters influence the rendering of the form XObject. This means, for example, that when the line width is set to 20, all lines of the form XObject are drawn with that line width unless the line width is changed in the form XObject itself.

Examples:

#>pdf
canvas.xobject(machu_picchu, at: [10, 10], width: 90)        # bottom left

file = File.new(machu_picchu, 'rb')                          # top left
canvas.xobject(file, at: [10, 110], height: 50)

image = doc.images.add(machu_picchu)
canvas.xobject(image, at: [110, 10], width: 50, height: 90)  # bottom right

form = doc.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, 100, 100]})
form.canvas.stroke_color("hp-blue").line(10, 10, 90, 90).stroke
canvas.line_width = 20
canvas.xobject(form, at: [100, 100])                         # top right

See: PDF2.0 s8.8, s.8.10.1, HexaPDF::Type::Image, HexaPDF::Type::Form, HexaPDF::ImageLoader

# File 'lib/hexapdf/content/canvas.rb', line 1754

def xobject(obj, at:, width: nil, height: nil)
  unless obj.kind_of?(HexaPDF::Stream)
    obj = context.document.images.add(obj)
  end
  return obj if obj.width == 0 || obj.height == 0

  left, bottom = *at
  width, height = calculate_dimensions(obj.width, obj.height,
                                       rwidth: width, rheight: height)
  if obj[:Subtype] != :Image
    width /= obj.box.width.to_f
    height /= obj.box.height.to_f
    left -= obj.box.left
    bottom -= obj.box.bottom
  end

  if left == 0 && bottom == 0 && width == 1 && height == 1
    invoke1(:Do, resources.add_xobject(obj))
  else
    transform(width, 0, 0, height, left, bottom) do
      invoke1(:Do, resources.add_xobject(obj))
    end
  end

  obj
end