RMagick 2.9.0: RVG Reference: RVG Class

###### RMagick 2.9.0 User's Guide and Reference

# class RVG < Object

## 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.

#### 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 "#000000ff". 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

#### 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 viewport

Rendered into a 150x200 viewport

#### 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 Fixnum 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 `Fixnum`

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.