Module PDF::Writer::Graphics
In: lib/pdf/writer/graphics.rb

This module contains graphics primitives. Objects that include this module must respond to add_content.

The PDF::Writer coordinate system is in PDF userspace units. The coordinate system in PDF::Writer is slightly different than might be expected, in that (0, 0) is at the lower left-hand corner of the canvas (page), not the normal top left-hand corner of the canvas. (See the diagram below.)

    Y     Y
   0+-----+X
    |     |
    |     |
    |     |
   0+-----+X
    0     0

Each primitive provided below indicates the New Point, or the coordinates new drawing point at the completion of the drawing operation. Drawing operations themselves do not draw or fill the path. This must be done by one of the stroke or fill operators, stroke, close_stroke, fill, close_fill, fill_stroke, or close_fill_stroke.

Drawing operations return self (the canvas) so that operations may be chained.

Methods

Classes and Modules

Class PDF::Writer::Graphics::ImageInfo

Constants

KAPPA = 4.0 * ((Math.sqrt(2) - 1.0) / 3.0)   This constant is used to approximate a symmetrical arc using a cubic Bezier curve.

Public Instance methods

Add an image from a loaded image (JPEG or PNG) resource at position (x, y) (the lower left-hand corner of the image) and scaled to width by height units. If provided, image_info is a PDF::Writer::Graphics::ImageInfo object.

In PDF::Writer 1.1 or later, the new link parameter is a hash with two keys:

:type:The type of link, either :internal or :external.
:target:The destination of the link. For an :internal link, this is an internal cross-reference destination. For an :external link, this is an URI.

This will automatically make the image a clickable link if set.

Add an image from a file to the current page at position (x, y) (the lower left-hand corner of the image). The image will be scaled to width by height units. The image may be a PNG or JPEG image.

The image parameter may be a filename or an object that returns the full image data when read is called with no parameters (such as an IO object). If ‘open-uri’ is loaded, then the image name may be an URI.

In PDF::Writer 1.1 or later, the new link parameter is a hash with two keys:

:type:The type of link, either :internal or :external.
:target:The destination of the link. For an :internal link, this is an internal cross-reference destination. For an :external link, this is an URI.

This will automatically make the image a clickable link if set.

Draws a circle of radius r with the centre-point at (x, y) as a complete subpath. The drawing point will be moved to the centre-point upon completion of the drawing the circle.

Close the current path by appending a straight line segment from the drawing point to the starting point of the path. If the path is closed, this does nothing. This operator terminates the current subpath.

Close the current path by appending a straight line segment from the drawing point to the starting point of the path, and then fill it. This does the same as close followed by fill.

See fill for more information on fill rules.

Closes, fills and then strokes the path. Open subpaths are explicitly closed before being filled (as if close and then fill_stroke had been called). This is the same as constructing two identical path objects, calling fill on one and stroke on the other. Paths filled and stroked in this manner are treated as if they were one object for PDF transparency purposes (PDF transparency is not yet supported by PDF::Writer).

See fill for more information on fill rules.

Close the current path by appending a straight line segment from the drawing point to the starting point of the path, and then stroke it. This does the same as close followed by stroke.

Draw a cubic Bezier curve from (x0, y0) to (x3, y3) using (x1, y1) and (x2, y2) as control points.

New Point:(x3, y3)
Subpath:New

Draws a cubic Bezier curve from the drawing point to (x2, y2) using (x0, y0) and (x1, y1) as the control points for the curve.

New Point:(x2, y2)
Subpath:Current

Draw a cubic Bezier curve from (x0, y0) to (x2, y2) using (x1, y1) and (x2, y2) as control points.

New Point:(x2, y2)
Subpath:New

Draws a cubic Bezier curve from the drawing point to (x1, y1) using (x0, y0) and (x1, y1) as the control points for the curve.

New Point:(x1, y1)
Subpath:Current

Draw an ellipse centered at (x, y) with x radius r1 and y radius r2. A partial ellipse can be drawn by specifying the starting and finishing angles.

New Point:(x, y)
Subpath:New

Draws an ellipse of x radius r1 and y radius r2 with the centre-point at (x, y) as a complete subpath. The drawing point will be moved to the centre-point upon completion of the drawing the ellipse.

Fills the path. Open subpaths are implicitly closed before being filled. PDF offers two methods for determining the fill region. The first is called the "nonzero winding number" and is the default fill. The second is called "even-odd".

Use the even-odd rule (called with fill(:even_odd)) with caution, as this will cause certain portions of the path to be considered outside of the fill region, resulting in interesting cutout patterns.

Sets the color for fill operations.

Forces the color for fill operations to be set, even if the color is the same as the current color. Does nothing if nil is provided.

Returns the current fill color.

Fills and then strokes the path. Open subpaths are implicitly closed before being filled. This is the same as constructing two identical path objects, calling fill on one and stroke on the other. Paths filled and stroked in this manner are treated as if they were one object for PDF transparency purposes (the PDF transparency model is not yet supported by PDF::Writer).

See fill for more information on fill rules.

Add an image easily to a PDF document. image is the name of a JPG or PNG image. options is a Hash:

:pad:The number of PDF userspace units that will be on all sides of the image. The default is 5 units.
:width:The desired width of the image. The image will be resized to this width with the aspect ratio kept. If unspecified, the image‘s natural width will be used.
:resize:How to resize the image, either :width (resizes the image to be as wide as the margins) or :full (resizes the image to be as large as possible). May be a numeric value, used as a multiplier for the image size (e.g., 0.5 will shrink the image to half-sized). If this and :width are unspecified, the image‘s natural size will be used. Mutually exclusive with the <tt>:width<tt> option.
:justification:The placement of the image. May be :center, :right, or :left. Defaults to :left.
:border:The border options. No default border. If specified, must be either true, which uses the default border, or a Hash.
:link:Makes the image a clickable link.

Image borders are specified as a hash with two options:

:color:The colour of the border. Defaults to 50% grey.
:style:The stroke style of the border. This must be a StrokeStyle object and defaults to the default line.

Image links are defined as a hash with two options:

:type:The type of link, either :internal or :external.
:target:The destination of the link. For an :internal link, this is an internal cross-reference destination. For an :external link, this is an URI.

Draw a straight line from (x0, y0) to (x1, y1). The line is a new subpath.

New Point:(x1, y1).
Subpath:New

Draw a straight line from the drawing point to (x, y).

New Point:(x, y)
Subpath:Current

Move the drawing point to the specified coordinates (x, y).

New Point:(x, y)
Subpath:New

Draw a polygon. points is an array of PolygonPoint objects, or an array that can be converted to an array of PolygonPoint objects with PDF::Writer::PolygonPoint.new(*value).

New Point:(points[-1].x, points[-1].y)
Subpath:New

Draw a rectangle. The first corner is (x, y) and the second corner is (x + w, y - h).

New Point:(x + w, y - h)
Subpath:Current

Rotate the axis of the coordinate system by the specified clockwise angle.

Draw a rounded rectangle with corners (x, y) and (x + w, y - h) and corner radius r. The radius should be significantly smaller than h and w.

New Point:(x + w, y - h)
Subpath:New

Scale the coordinate system axis by the specified factors.

Draw a cubic Bezier curve from (x0, y0) to (x2, y2) using (x0, y0) and (x1, y1) as control points.

New Point:(x2, y2)
Subpath:New

Draws a cubic Bezier curve from the drawing point to (x1, y1) using the drawing point and (x0, y0) as the control points for the curve.

New Point:(x1, y1)
Subpath:Current

Draws an ellipse segment. Draws a closed partial ellipse.

New Point:(x, y)
Subpath:New

Skew the coordinate system axis by the specified angles.

Draws a star centered on (x, y) with rays portions of length from the centre. Stars with an odd number of rays should have the top ray pointing toward the top of the document. This will not create a "star" with fewer than four points.

New Point:(cx, cy)
Subpath:New

Stroke the path. This operation terminates a path object and draws it.

Sets the color for stroke operations.

Forces the color for stroke operations to be set, even if the color is the same as the current color. Does nothing if nil is provided.

Returns the current stroke color.

This sets the line drawing style. This must be a PDF::Writer::StrokeStyle object.

Forces the line drawing style to be set, even if it‘s the same as the current color. Emits the current stroke style if nil is provided.

Returns the current stroke style.

Set the text rendering style. This may be one of the following options:

0:fill
1:stroke
2:fill then stroke
3:invisible
4:fill and add to clipping path
5:stroke and add to clipping path
6:fill and stroke and add to clipping path
7:add to clipping path

Forces the text rendering style to be set, even if it‘s the same as the current style.

Reutnrs the current text rendering style.

Transforms the coordinate axis with the appended matrix. All transformations (including those above) are performed with this matrix. The transformation matrix is:

  +-     -+
  | a c e |
  | b d f |
  | 0 0 1 |
  +-     -+

The six values are represented as a six-digit vector: [ a b c d e f ]

  • Axis translation uses [ 1 0 0 1 x y ] where x and y are the new (0,0) coordinates in the old axis system.
  • Scaling uses [ sx 0 0 sy 0 0 ] where sx and sy are the scaling factors.
  • Rotation uses [ cos(a) sin(a) -sin(a) cos(a) 0 0 ] where a is the angle, measured in radians.
  • X axis skewing uses [ 1 0 tan(a) 1 0 0 ] where a is the angle, measured in radians.
  • Y axis skewing uses [ 1 tan(a) 0 1 0 0 ] where a is the angle, measured in radians.

Translate the coordinate system axis by the specified user space coordinates.

[Validate]