Module: PDF::Writer::Graphics

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

add_image add_image_from_file circle_at close close_fill close_fill_stroke close_stroke curve curve_to ecurve ecurve_to ellipse2_at ellipse_at fill fill_color fill_color! fill_color? fill_stroke image line line_to move_to polygon rectangle rotate_axis rounded_rectangle scale_axis scurve scurve_to segment_at skew_axis star stroke stroke_color stroke_color! stroke_color? stroke_style stroke_style! stroke_style? text_render_style text_render_style! text_render_style? transform_matrix translate_axis

### 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_image(image, x, y, width = nil, height = nil, image_info = nil, link = nil)

Add an image from a loaded image (JPEG or PNG) resource at position `(x, y)` (the upper 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_image_from_file(image, x, y, width = nil, height = nil, link = nil)

Add an image from a file to the current page at position `(x, y)` (the upper 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.

circle_at(x, y, r)

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

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_fill(rule = nil)

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.

close_fill_stroke(rule = nil)

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_stroke()

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.

curve(x0, y0, x1, y1, x2, y2, x3, y3)

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

curve_to(x0, y0, x1, y1, x2, y2)

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

ecurve(x0, y0, x1, y1, x2, y2)

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

ecurve_to(x0, y0, x1, y1)

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

ellipse2_at(x, y, r1, r2 = r1, start = 0, stop = 359.99, segments = 8)

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

ellipse_at(x, y, r1, r2 = r1)

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.

fill(rule = nil)

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.

fill_color(color)

Sets the color for fill operations.

fill_color!(color = nil)

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.

fill_color?()

Returns the current fill color.

fill_stroke(rule = nil)

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.

image(image, options = {})

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.

line(x0, y0, x1, y1)

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

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

line_to(x, y)

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

New Point: | `(x, y)`
Subpath: | Current

move_to(x, y)

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

New Point: | `(x, y)`
Subpath: | New

polygon(points)

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

rectangle(x, y, w, h = w)

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_axis(angle)

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

rounded_rectangle(x, y, w, h, r)

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_axis(x = 1, y = 1)

Scale the coordinate system axis by the specified factors.

scurve(x0, y0, x1, y1, x2, y2)

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

scurve_to(x0, y0, x1, y1)

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

segment_at(x, y, r1, r2 = r1, start = 0, stop = 360, segments = 8)

Draws an ellipse segment. Draws a closed partial ellipse.

New Point: | `(x, y)`
Subpath: | New

skew_axis(xangle = 0, yangle = 0)

Skew the coordinate system axis by the specified angles.

star(cx, cy, length, rays = 5)

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

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

stroke_color(color)

Sets the color for stroke operations.

stroke_color!(color = nil)

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.

stroke_color?()

Returns the current stroke color.

stroke_style(style)

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

stroke_style!(style = nil)

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.

stroke_style?()

Returns the current stroke style.

text_render_style(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

text_render_style!(style)

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

text_render_style?()

Reutnrs the current text rendering style.

transform_matrix(a, b, c, d, e, f)

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_axis(x, y)

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

[Validate]