class RVG < Object

Table of Contents

class methods

attributes

instance methods

shared methods

In addition to the methods listed above, class RVG also implements the styles method, the shape methods and the transform methods.

Units

class methods

new

RVG.new(width=nil, height=nil) [ { |canvas| drawing method calls } ] -> rvg

Description

Creates a container that can have its own coordinate system. Within the block, call drawing methods on canvas to render shapes, text, and raster images in the container.

An RVG object is always the outermost container for a drawing. Call the draw method on the returned RVG object to produce the final image.

Arguments

If the RVG object is the outermost container, width and height are required and specify the width and height of the final drawing in pixels. You can call conversion methods to use units such as inches and millimeters instead of pixels.

Otherwise, width and height specify the area of the viewbox. If the RVG object will be used as an argument to the use method, then width and height may be omitted here, then specified as arguments to use.

Returns

An RVG object

Example

See the tutorial for a simple example. The image below demonstrates an advanced use of RVG.new. This example creates an RVG object that draws an orange-and-green target. The width and height arguments are omitted in the RVG.new call. Instead, the viewport width and height are specified as arguments to 4 invocations of use. Each use specifies a different viewport size, so the same RVG object draws 4 different-sized targets.

Click the image to see the example script.

nested RVG example

See also

Group

attributes

background_fill=

canvas.background_fill = value

Description

Specify a background fill color. The attribute value may be either a pixel or a color name. The default fill color is "#00000000". This color is usually called "none". This attribute has no effect on nested RVG objects.

Example

canvas.background_fill = 'white'

Returns

value

background_fill_opacity=

canvas.background_fill_opacity = value

Description

Specify the opacity of the background fill color when the background fill is not the default. The value is a number between 0.0 (fully transparent) and 1.0 (fully opaque). The default is 1.0. The attribute is ignored unless background_fill is specified. This attribute has no effect on nested RVG objects.

Example

canvas.background_fill = 'white'
canvas.background_fill_opacity = 0.50

Returns

value

background_image=

canvas.background_image = image

Description

Specify an image to be used as the canvas background. The value is an Image object. This attribute has no effect on nested RVG objects.

Example

canvas.background_image = Magick::Image.read('myBackground.gif').first

Returns

image

See also

background_position=

background_pattern=

canvas.background_pattern = fill

Description

Specify an Fill object to fill the canvas background. This attribute has no effect on nested RVG objects.

Example

canvas.background_pattern = Magick::GradientFill.new(0, 0, 0, 100, "#900", "#000")

Returns

a Fill object

background_position=

canvas.background_position = pos

Description

If the dimensions of the image specified by background_image do not exactly match the canvas dimensions, this attribute specifies how to position the image on the background. This attribute has no effect on nested RVG objects.

Argument

The value of pos can be any one of the following symbols :
:scaled
The image is scaled to fit. The image proportions are not retained.
:tiled
The image is tiled across the background.
:fit
The image is scaled to fit. The image proportions are retained. Any part of the background that is not covered by the image is colored with the background color.

Example

canvas.background_image = Magick::Image.read('myBackground.gif').first
canvas.background_position = :scaled

Returns

pos

canvas

rvg.canvas -> image

Description

After the draw method has been used, returns the rendered image. This is the same image that draw returns.

Returns

An image

desc, desc=

rvg.desc -> string
rvg.desc = string

Description

Use the desc attribute to assign a text description to the drawing. The description will be assigned to the "desc" property of the resulting image. This attribute has no effect on nested RVG objects.

height

rvg.height -> height

Description

The height of the RVG object in user coordinates.

See also

width

metadata, metadata=

rvg.metadata -> string
rvg.metadata = string

Description

Use the metadata attribute to assign additional metadata to the drawing. The metadata string will be assigned to the "metadata" property of the resulting image. This attribute has no effect on nested RVG objects.

title, title=

rvg.title -> string
rvg.title = string

Description

Use the title attribute to assign a title to the drawing. The title will be assigned to the "title" property of the resulting image. This attribute has no effect on nested RVG objects.

width

rvg.width -> width

Description

The width of the RVG object in user coordinates.

See also

height

x

rvg.x -> x-offset

Description

If this RVG object is nested within another RVG object, returns the x-offset in user coordinates from the upper-left corner of the enclosing RVG object.

See also

y

y

rvg.y -> y-offset

Description

If this RVG object is nested within another RVG object, returns the y-offset in user coordinates from the upper-left corner of the enclosing RVG object.

See also

x

instance methods

draw

rvg.draw -> image

Description

Causes all the drawing objects that have been added to the canvas to be rendered.

Regardless of the order in which methods were called, draw executes the methods in this order:

  1. transforms, in the order they were called.
  2. viewbox and preserve_aspect_ratio
  3. styles
  4. nested groups, RVG objects, shapes, text, and images, in the order they were added to the containing object

Nested groups and RVG objects also follow this sequence.

Returns

An image

Example

      img = rvg.draw
      img.write('myDrawing.jpg')

g

rvg.g [{|grp| ...}] -> group

Description

Calls RVG::Group.new to construct a group and adds it to the enclosing RVG object. Yields to a block if one is present, passing the new group as an argument.

Returns

Returns the new group, so RVG::Group methods can be chained to this method.

image

rvg.image(raster_image, width=nil, height=nil, x=0, y=0) -> image

Description

Calls RVG::Image.new to construct an image and adds it to the enclosing RVG object.

Returns

Returns the new image, so RVG::Image methods can be chained to this method.

Notes

An RVG::Image object is not the same as a Magick::Image object!

preserve_aspect_ratio

rvg.preserve_aspect_ratio(align, meet_or_slice='meet') [{|self| ...}] -> self

Description

If you use the viewbox method and the user coordinate system does not scale uniformly to the default coordinate system (for example, the width and height of the RVG object is 4x3 and the user coordinate system is 16x9), use the preserve_aspect_ratio method to specify whether or not the content is stretched to fit. If not, you can specify how to fit the content into the space.

Preserve_aspect_ratio yields to a block if one is present, passing self as an argument.

Arguments

align
When the value of the meet_or_slice argument is 'meet' or 'slice', this argument controls the placement of the content within the viewport. The align argument is the concatenation of an x-alignment and a y-alignment. The values are shown in these lists:
x-alignment
xMin
align the minimum x value of the content with the left corner of the viewport.
xMid
vertically center the content within the viewport.
xMax
align the maximum x value of the content with the right corner of the viewport.
y-alignment
YMin
align the minimum y value of the content with the top of the viewport.
YMid
horizontally center the content within the viewport.
YMax
align the maximum y value of the content with the bottom of the viewport
meet_or_slice
This argument can have one of these three values:
'none'
The content is scaled as necessary so that it fits exactly within the viewport. The aspect ratio is not maintained.
'meet'
The content is scaled as necessary so that the larger dimension exactly fits the viewport. There may be some unused space in the viewport. The aspect ratio is maintained.
'slice'
The content is scaled as necessary so that the smaller dimension exactly fits the viewport. Some of the content in the larger dimension may be cut off. The aspect ratio is maintained.

Example

preserve_aspect_ratio example

Returns

Self, so other RVG methods can be chained to this method.

See Also

viewbox

rvg

rvg.rvg(width, height, x=0, y=0) [{|new_rvg| ...}] -> self

Description

This method constructs a new RVG object and adds it to the enclosing RVG object. Each nested RVG object can use the viewbox method to define its own coordinate system. The rvg method yields to a block, passing the nested RVG object as an argument. Within the block, any drawing objects added to the nested RVG object are rendered within the nested RVG object's viewport.

Arguments

width, height
Specifies the viewport width and height. The units are in the user coordinate system of the parent container.
x, y
The x- and y-axis offsets of the viewport upper-left corner. The units are in the user coordinate system of the parent container.

Example

See the example for preserve_aspect_ratio.

Returns

The RVG object, so other RVG methods can be chained to this method.

text

rvg.text(x=0, y=0, text=nil) [{|text| ...}] -> text

Description

Calls RVG::Text.new to construct a text object and adds it to the enclosing RVG object. Yields to a block if one is present, passing the new text object as an argument.

Returns

The RVG::Text object, so other RVG::Text methods can be chained to this method.

use

rvg.use(obj, x=0, y=0, width=nil, height=nil) -> use

Description

Calls RVG::Use.new to construct a use object and adds it to the RVG object.

When the referenced argument is another RVG object, width and height can be used to specify the width and height of the viewport. If present and non-nil, these arguments override any width and height specified when the RVG object was created. You must specify the viewport size either when creating the RVG object or when referencing it with use.

Examples

See RVG::Use.new

Returns

The RVG::Use object, so other RVG::Use methods can be chained to this method.

viewbox

rvg.viewbox(min_x, min_y, width, height) [{|self| ...}] -> self

Description

The area of the RVG object is called the viewport. By default the origin of the coordinate system for an RVG object is (0,0). The user coordinates are pixels and the width and height are established by the width and height arguments to RVG.new.

Use the viewbox method to superimpose a user coordinate system on the viewport. The viewbox method lets you set up a coordinate system using the units of your choice.

The viewbox method yields to a block if one is present, passing self as an argument.

Arguments

min_x, min_y
The minimum x-coordinate and y-coordinate of the user coordinate system.
width, height
The width and height of the user coordinate system.

Example

In the following examples, because the viewbox method specifies the dimensions of the coordinate system, the dimensions specified for the graphic objects can remain the same while the size of the canvas changes.

Rendered into a 300x200 viewportviewbox 300x200 example

Rendered into a 150x200 viewportviewbox 150x200 example

Returns

Self, so other RVG methods may be chained to viewbox.

See Also

preserve_aspect_ratio

Units

RVG supports a subset of the unit identifiers defined by the SVG specification. In RVG, unit identifiers are methods in the Float and Integer classes. The units are (for the most part) defined in terms of "dots per inch," accordingly, the unit identifier methods are added only if the value

    Magick::RVG.dpi = NN

is defined, where NN is the number of "dots" (pixels) per inch you wish to use. (Hint: 90 is a good default.)

For example, to specify a length of 10 inches, you can use

    Magick::RVG.dpi = 90
    length = 10.in  # => 900 pixels

If the dpi is defined, the following methods are added to Float and Integer

px
Pixel. The default unit of measurement.
in
Converts inches to pixels
mm
Converts millimeters to pixels
cm
Converts centimeters to pixels
pt
Converts points to pixels. There are 72 points to the inch.
pc
Converts picas to pixels. There are 12 points to the pica.
deg
Degrees. The default unit of rotation.
rad
Converts radians to degrees.
grad
Converts grads to degrees. There are 400 grads in a circle.
pct
This conversion takes an numeric argument and returns a percentage of the argument. For example 20.pct(150) -> 30

SVG also supports em and ex, which are measurements based on the font size. RVG does not.