Create the definition of a non-rectangular clipping path.

Description

A feature of SVG is that elements can be clipped to by more than just a rectangular region. Most graphical elements can be drawn. The purpose of these functions is to define a more sophisticated clipping path that will be applied until the current viewport (or context, see popContext) is popped.

Usage

clipPath(grob)
registerClipPath(label, clippath)

Arguments

Details

A clipping path will be drawn within the current viewport at the time of definition (if the grob has no vp specified).

Most grobs can be used for clipping but there are some limitations on what will actually be used for clipping. In general though, anything that is drawn as the clipping path will have the union of its drawn regions become the new region that the current viewport (or grob) will clip to.

The limitations are as follows:

• Any viewport pushed by the clipping path grob will no longer clip to its contents. However, its clipping region will remain. This means that the clipping region for a pushed viewport will become the union of its contents and the viewport clipping region itself, instead of just the pushed viewport's clipping region.

• When drawing a textGrob, only character labels will be used, no plotmath expressions will be used.

• No pointGrobs are able to be used for clipping.

• Any operations that apply to containers (e.g. gpars, garnishing, animation), will no longer work. Any operations that are not applied to groups are unaffected. This affects in particular viewports, gTrees, and the familiar gridSVG grob grouping that occurs.

Value

None

Author(s)

Simon Potter

See Also

popContext, grid.clipPath, pushClipPath, grid.clip

Functions for using an imported coordinate system

Description

These functions convert between different units. The conversion occurs within viewports unknown to grid, but imported to R via gridSVGCoords.

Usage

viewportConvertX(vpname, x, from, to = "svg")
viewportConvertY(vpname, x, from, to = "svg")
viewportConvertPos(vpname, x, y, from, to = "svg")
viewportConvertWidth(vpname, x, from, to)
viewportConvertHeight(vpname, x, from, to)
viewportConvertDim(vpname, w, h, from, to)

Arguments

Details

Although grid has conversion functions available, it only converts units relative to the current viewport. After writing out to SVG, we no longer have actual grid viewports to convert units within.

These functions are designed so that once coordinate information is loaded into gridSVG via gridSVGCoords, we can translate units within each of these viewports. Note: this requires that a gridSVG plot has had viewport information exported.

These functions can be used in much the same way as grid's unit conversion functions, the only difference being that we have a new unit, svg, which represents the size of a unit in SVG pixels.

The viewportConvertPos() and viewportConvertDim() functions are for use with a viewport that has a non-zero rotation (both viewportConvertX() and viewportConvertY() will fail in that situation and viewportConvertWidth() and viewportConvertHeight() will give a not very useful answer).

Value

A numeric vector containing a single value, the value of the new unit, or a list with components x and y for viewportConvertPos(), or a list with components w and h for viewportConvertDim().

In the case of the viewportConvertX and viewportConvertY functions, we always return a value that is in terms of SVG pixels.

Author(s)

Simon Potter

Importing an external coordinate system

Description

This function is both a getter and a setter function for coordinate information imported from a plot unknown to the current R session.

Usage

gridSVGCoords(newcoords = NULL)

Arguments

Details

In order to translate between SVG coordinates and the coordinate system that grid understands, we first need to import the coordinate information exported from grid.export. We can then take the JSON representation of this coordinate information and import it as a named list via fromJSON. This can then initialise a coordinate system by passing that named list into gridSVGCoords.

We can supply new definitions of a viewport's coordinate system by simply passing in an appropriate list with information for that viewport.

All viewport coordinate system information can be wiped if a single NA value is passed in.

Value

If newcoords is NULL, then we get back a named list representing coordinate system information.

If we pass the named list representing a coordinate system into the function, we get no output. We also get no output if we pass in a single NA value.

Author(s)

Simon Potter

Identifies input for a filter effect primitive.

Description

How to use and identify inputs for filter effect primitives.

Filter Inputs

The value chosen for a filter effect primitive can be either one of six keywords or can be a string which matches a previous result attribute value within the same filter effect container. If no value is provided and this is the first filter effect primitive, then the input will be SourceGraphic. If no value is provided and this is a subsequent filter effect primitive, then this filter effect primitive will use the result from the previous filter primitive as its input.

If the value for result appears multiple times within a given filter container, then a reference to that result will use the closest preceding filter primitive with the given value for the result results. Forward references to results are an error and will not draw.

Definitions for the seven possible options:

• SourceGraphic This keyword represents the appearance of grobs before they are being filtered. For raster effects filter primitives, the grobs will be rasterized into an initially clear RGBA raster in image space. Pixels left untouched by the original graphic will be left clear. The image is specified to be rendered in linear RGBA pixels. The alpha channel of this image captures any anti-aliasing specified by SVG. (Since the raster is linear, the alpha channel of this image will represent the exact percent coverage of each pixel.)

• SourceAlpha This keyword represents the appearance of grobs before they are being filtered. SourceAlpha has all of the same rules as SourceGraphic except that only the alpha channel is used. The input image is an RGBA image consisting of implicitly black color values for the RGB channels, but whose alpha channel is the same as SourceGraphic. If this option is used, then some implementations might need to rasterize the graphics elements in order to extract the alpha channel.

• BackgroundImage This keyword represents an image snapshot of the canvas under the filter region at the time that the referring grob is being filtered.

• BackgroundAlpha Same as BackgroundImage except only the alpha channel is used.

• FillPaint This keyword represents the value of the fill property on the grob being filtered. The FillPaint image has conceptually infinite extent. Frequently this image is opaque everywhere, but it might not be if the "paint" itself has alpha, as in the case of a gradient or pattern which itself includes transparent or semi-transparent parts.

• StrokePaint This keyword represents the value of the col property on the grob being filtered. The StrokePaint image has conceptually infinite extent. Frequently this image is opaque everywhere, but it might not be if the "paint" itself has alpha, as in the case of a gradient or pattern which itself includes transparent or semi-transparent parts.

• The result of any filter effect operation. This is the name that has been given to the result argument of a filter primitive.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#FilterPrimitiveInAttribute

Create a definition of a gradient fill.

Description

A feature of SVG is that elements can be filled with a gradient that is defined somewhere in the document. The purpose of the registerGradientFill function is to create a definition of a gradient fill so that it can be referred to by grobs drawn by gridSVG.

Usage

registerGradientFill(label, gradient)

Arguments

Value

None.

Author(s)

Simon Potter

See Also

linearGradient, radialGradient, grid.gradientFill

Create Linear and Radial Gradients

Description

Create objects which describe linear and radial gradients. These objects can later be used to apply a gradient fill to grobs, and also to define a gradient so that it may be reused multiple times.

Usage

linearGradient(col = c("black", "white"),
               stops = seq(0, 1, length.out = length(col)),
               gradientUnits = c("bbox", "coords"),
               x0 = unit(0, "npc"), x1 = unit(1, "npc"),
               y0 = unit(0, "npc"), y1 = unit(1, "npc"),
               default.units = "npc",
               spreadMethod = c("pad", "reflect", "repeat"))
radialGradient(col = c("black", "white"),
               stops = seq(0, 1, length.out = length(col)),
               gradientUnits = c("bbox", "coords"),
               x = unit(0.5, "npc"), y = unit(0.5, "npc"),
               r = unit(0.5, "npc"),
               fx = unit(0.5, "npc"), fy = unit(0.5, "npc"),
               default.units = "npc",
               spreadMethod = c("pad", "reflect", "repeat"))

Arguments

Details

When defining gradient stops via col and stops, the order is important. Gradient stops which are defined earlier are drawn first, with later stops being drawn over the top.

For spreadMethod the possible values are:

• pad Use the terminal colors of the gradient to fill the remainder of the target region.

• reflect Reflect the gradient pattern start-to-end, end-to-start, start-to-end, etc. continuously until the target region is filled.

• repeat Repeat the gradient pattern start-to-end, start-to-end, start-to-end, etc. continuously until the target region is filled.

Value

A gradient object.

Author(s)

Simon Potter

Importing JavaScript coordinate information.

Description

This function reads in a JavaScript file and transforms it into JSON text. This text is then transformed into a list that can be used in conjunction with gridSVGCoords.

Usage

readCoordsJS(filename)

Arguments

Details

In order to use the fromJSON function to parse JSON text, the JavaScript file produced by grid.export needs to be transformed. It needs to transform from being an assignment of an object literal to simply the object literal itself.

This function performs that task by producing a valid JSON string ready for parsing by fromJSON. It then returns the parsed list.

Value

A list of coordinate information.

Author(s)

Simon Potter

Importing JavaScript mapping information.

Description

This function reads in a JavaScript file and transforms it into JSON text. This text is then transformed into a list that can be used in conjunction with gridSVGMappings.

Usage

readMappingsJS(filename)

Arguments

Details

In order to use the fromJSON function to parse JSON text, the JavaScript file produced by grid.export needs to be transformed. It needs to transform from being an assignment of an object literal to simply the object literal itself.

This function performs that task by producing a valid JSON string ready for parsing by fromJSON. It then returns the parsed list.

Value

A list of mapping information.

Author(s)

Simon Potter

Mapping Viewport, Grob and Reference Names to SVG IDs

Description

This function is both a getter and a setter function for mapping information imported from a plot unknown to the current R session.

Usage

gridSVGMappings(newmappings = NULL)

Arguments

Details

In order to generate unique names for SVG IDs, gridSVG output will not produce the same names as are visible on the grid display list. This function will store and return mapping information. This is information on how names have been translated from their original grob/viewport names to their SVG IDs.

Mapping information is stored as a list with 4 components, viewport mapping information, grob mapping information, reference mapping information and the ID separator used at the time of exporting.

Viewport, grob, and reference mapping information is stored as the name of the object, paired with a vector of suffixes associated with these names. When combined with the ID separator, we can construct the SVG IDs that have been applied, given each name. Use getSVGMappings to do this.

Value

If newmappings is NULL, then we get back a named list representing name mapping information.

If we pass the named list representing mapping information into the function, we get no output.

Author(s)

Simon Potter

Create the definition of an opacity mask.

Description

A feature of SVG is that elements can have an opacity mask applied to it. An opacity mask is an image that, for various levels of opacity, makes the object that is being masked inherit the same levels of opacity. The purpose of these functions is to define an opacity mask that will be applied until the current viewport (or context, see popContext) is popped. Alternatively it can also be applied to grobs.

Usage

mask(grob,
     x = unit(0.5, "npc"), y = unit(0.5, "npc"),
     width = unit(1, "npc"), height = unit(1, "npc"),
     default.units = "npc",
     just = "centre", hjust = NULL, vjust = NULL)
registerMask(label, mask = NULL, ...)

Arguments

Details

When registering the mask, the rectangular region that the mask applies to will become fixed.

When referring to an opacity mask, the masked content will be opaque at the same coordinates that the mask is opaque. The same applies when there is any level of transparency, as any transparency in the mask will also apply in the same corresponding region of the masked object.

The mask's opacity is defined as being the level of luminance present in the mask. This means anything black is fully transparent, while anything white is completely opaque. The background is assumed to be black (i.e. fully transparent). The alpha value in a mask will still be used, but its effect is combined with the computed opacity from the luminance of the mask.

By using an opacity mask it is possible to have a grob with non-uniform opacity. In other words, rather than specifying an opacity via gpar's alpha parameter, which is uniform across the grob, we can define varying opacities on a grob via an opacity mask.

The x, y, width, height parameters determine the location and dimensions of the area to apply the mask to. This means we can apply a mask to any rectangular region, relative to the viewport in which it is defined (via registerMask).

Value

For mask, a mask object.

Author(s)

Simon Potter

See Also

grid.mask, pushMask, popContext.

Create a definition of a fill pattern.

Description

A feature of SVG is that elements can be filled with a pattern that is defined somewhere in the document. The purpose of these functions is to create the definition of a fill pattern so that it can be referred to by grobs drawn by gridSVG.

Usage

pattern(grob,
        x = unit(0, "npc"), y = unit(0, "npc"),
        width = unit(0.1, "npc"), height = unit(0.1, "npc"),
        default.units = "npc",
        just = "centre", hjust = NULL, vjust = NULL,
        dev.width = 7, dev.height = 7)
registerPatternFill(label, pattern = NULL, ...)
registerPatternFillRef(label, refLabel, pattern = NULL, ...)

Arguments

Details

The pattern fill is drawn off-screen on a new device. The size of this device is determined by dev.width and dev.height. The grob and vp that have been given are then drawn within this device. This is relevant for determining what the pattern definition looks like.

The previous arguments do not determine the size of the pattern as it is being used (i.e. how big each "tile" is). This is set by the x, y, width, height arguments. The values of these arguments are relative to the current viewport as this function is being called. From then on, the definition of the location and size of the pattern are fixed.

In summary, the pattern function defines what a pattern looks like, along with how big each tile is (and its position).

To avoid repetition of pattern definitions, use registerPatternFillRef to reuse an existing pattern definition (referred to by refLabel). This means that a pattern "tile" can now be reused, repositioned and rescaled without having to describe how it needs to be drawn.

In general use, first create a pattern object, then either give a label to the definition (for grobs to use), or alternatively simply pass on the pattern object to grid.patternFill.

Value

A pattern object for pattern, none otherwise.

Author(s)

Simon Potter

See Also

grid.patternFill

Retrieving Viewport, Grob, and Reference Names as SVG IDs, CSS Selectors and XPath Expressions

Description

This function gives us SVG IDs (or CSS selectors and XPath expressions) that have been created from a grob, viewport, or referenced name as a result of exporting to SVG.

Usage

getSVGMappings(name, type, result = "id")

Arguments

Details

In order to generate unique names for SVG IDs, gridSVG output will not produce the same names as are visible on the grid display list. This function retrieves the SVG IDs associated with grob and viewport names. To use this function first requires importing mapping information, see gridSVGMappings.

To make using results easier with existing JavaScript libraries and R packages, CSS selectors and XPath expressions can be returned. This is the case when result is specified as one of selector or xpath. These are targeted to match just the SVG element itself, nothing more.

Value

A character vector representing values that can target specific SVG output.

Author(s)

Simon Potter

Generate a set of animation values.

Description

These functions can be used to generate a set of values for use with grid.animate() to animate some feature of a grob.

Usage

animUnit(x, timeid = NULL, id = NULL)
animValue(x, timeid = NULL, id = NULL)
as.animUnit(x, ...)
as.animValue(x, ...)

Arguments

Details

A set of animation values is ultimately either a numeric or character vector OR a unit vector. Subsets of the animation values can be defined per time point, or per identifier, or both.

The as functions allow animation values to be specified as matrices or lists, which are converted to formal animation value sets. The grid.animate() function calls these functions so the conversion typically happens automatically.

These functions should only have to be called directly in relatively complex cases where multiple values need to be specified per time point AND per identifier.

Value

An animUnit or animValue object.

Author(s)

Paul Murrell

See Also

grid.animate

Examples

require(grid)

animValue(c("visible", "hidden"))
animUnit(unit(1:24, "in"),
         timeid=rep(1:3, each=8),
         id=rep(1:2, 12))

Convert animation specifications to SVG elements.

Description

This function is used to generate <animate> elements based on animation information on a grob. It is generic so new grob classes can write their own methods.

Usage

animate(x, dev)

Arguments

Details

This function is not called directly by the user. It is exposed so that new grob classes can easily write their own methods which call existing methods for standard grobs.

Author(s)

Paul Murrell

Creating a generic filter effect

Description

This function creates an object that contains all of the basic attributes that each filter effect inherits from. This is not intended to be used directly, instead it is to be used as a convenience function for building up filter effect objects.

Usage

fe(...,
   x = unit(0.5, "npc"), y = unit(0.5, "npc"),
   width = unit(1, "npc"), height = unit(1, "npc"),
   just = "centre", hjust = NULL, vjust = NULL,
   default.units = "npc", result = NULL)

Arguments

Value

A filter.effect object.

Author(s)

Simon Potter

See Also

filterEffect

Blend two objects together.

Description

This filter composites two objects together using commonly used imaging software blending modes. It performs a pixel-wise combination of two input images.

Usage

feBlend(input1 = NA, input2 = NA,
        mode = c("normal", "multiply", "screen", "darken", "lighten"),
        ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.blend object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feBlendElement

See Also

filterEffect, fe.

Apply a matrix transformation on colour values.

Description

This filter applies a matrix transformation on the RGBA colour and alpha values of every pixel on the input graphics to produce a result with a new set of RGBA colour and alpha values.

Usage

feColorMatrix(input = NA,
              type = c("matrix", "saturate",
                       "hueRotate", "luminanceToAlpha"),
              values = NULL, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.color.matrix object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feColorMatrixElement

See Also

filterEffect, fe.

Perform Colour Component-wise Remapping.

Description

This filter primitive performs component-wise remapping of data by taking a colour transfer function, and applying that to the set of RGBA colour components.

It allows operations like brightness adjustment, contrast adjustment, colour balance or thresholding.

The calculations are performed on non-premultiplied colour values. If the input graphics consists of premultiplied colour values, those values are automatically converted into non-premultiplied colour values for this operation. (Note that the undoing and redoing of the premultiplication can be avoided if alpha transfer function is the identity transform and all alpha values on the source graphic are set to 1.)

Usage

feComponentTransfer(input = NA, transfers = NULL, ...)
addComponentFunction(ct, channel = c("R", "G", "B", "A"), func)
transferFunction(type = c("identity", "table", "discrete",
                          "linear", "gamma"),
                 tableValues = numeric(),
                 slope = 1, intercept = 0,
                 amplitude = 1, exponent = 1, offset = 0)

Arguments

Details

For more information about this primitive, consult the references to the SVG specification.

Value

For feComponentTransfer, an fe.component.transfer object.

For addComponentFunction, none.

For transferFunction, a transfer.function object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feComponentTransferElement, https://www.w3.org/TR/SVG/filters.html#feFuncRElement

See Also

filterEffect, fe.

Combine images using Porter-Duff operations.

Description

This filter performs the combination of the two input images pixel-wise in image space using one of the Porter-Duff compositing operations.

The arithmetic operation is useful for combining the output from the feDiffuseLighting and feSpecularLighting filter effects with texture data. It is also useful for implementing dissolve.

Usage

feComposite(input1 = NA, input2 = NA,
            operator = c("over", "in", "out", "atop",
                         "xor", "arithmetic"),
            k1 = 0, k2 = 0, k3 = 0, k4 = 0, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.composite object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feCompositeElement

Compositing Digital Images, T. Porter and T. Duff. SIGGRAPH '84 Conference Proceedings, Association for Computing Machinery, Volume 18, Number 3, July 1984.

See Also

filterEffect, fe.

Apply a matrix convolution filter effect.

Description

A convolution combines pixels in the input image with neighbouring pixels to produce a resulting image. A wide variety of imaging operations can be achieved through convolutions, including blurring, edge detection, sharpening, embossing and beveling.

Usage

feConvolveMatrix(input = NA, order = 3,
                 kernelMatrix = matrix(),
                 divisor = 1, bias = 0,
                 targetX = 1, targetY = 1,
                 edgeMode = c("duplicate", "wrap", "none"),
                 kernelUnitLength = NA, preserveAlpha = FALSE,
                 ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.convolve.matrix object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feConvolveMatrixElement

See Also

filterEffect, fe.

Light an image using the alpha channel as a bump map.

Description

This filter primitive lights an image using the alpha channel as a bump map. The resulting image is an RGBA opaque image based on the light colour with alpha = 1 everywhere. The lighting calculation follows the standard diffuse component of the Phong lighting model. The resulting image depends on the light colour, light position and surface geometry of the input bump map.

Usage

feDiffuseLighting(input = NA,
                  surfaceScale = 1, diffuseConstant = 1,
                  kernelUnitLength = NA, col = "white",
                  lightSource = NULL, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.diffuse.lighting object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feDiffuseLightingElement

See Also

filterEffect fe, feDistantLight, fePointLight, feSpotLight.

Displace pixel values from a filter input.

Description

This filter primitive uses the pixels values from the image from input2 to spatially displace the image from input1.

Usage

feDisplacementMap(input1 = NA, input2 = NA,
                  scale = 0,
                  xChannelSelector = c("A", "R", "G", "B"),
                  yChannelSelector = c("A", "R", "G", "B"),
                  ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.displacement.map object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feDisplacementMapElement

See Also

filterEffect, fe.

Create a Distant Light Source

Description

This filter primitive defines a distant light source that can be used within a lighting filter primitive: feDiffuseLighting or feSpecularLighting.

Usage

feDistantLight(azimuth = 0, elevation = 0, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.distant.light object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feDistantLightElement

See Also

filterEffect, fe, feDiffuseLighting, feSpecularLighting.

Create and fill a rectangular region.

Description

This filter primitive creates a rectangle filled with a specified colour. The rectangle is as large as the filter primitive subregion established by the x, y, width and height attributes passed onto fe via ....

Usage

feFlood(col = "black", ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.flood object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feFloodElement

See Also

filterEffect, fe.

Apply a Gaussian blur to an image.

Description

This filter effect primitive performs a Gaussian blur on the input image.

Usage

feGaussianBlur(input = NA, sd = 0, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.gaussian.blur object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feGaussianBlurElement

See Also

filterEffect, fe.

Draw a referred image.

Description

This filter effect primitive refers to a graphic external to this filter container, which is loaded or rendered into an RGBA raster and becomes the result of the filter effect primitive.

Usage

feImage(preserveAspectRatio = "xMidYMid meet", href = "", ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.image object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feImageElement https://www.w3.org/TR/SVG/coords.html#PreserveAspectRatioAttribute

See Also

filterEffect, fe.

Composite image layers together.

Description

This filter primitive composites input image layers on top of each other using the "over" operator with "input1" (corresponding to the first child merge node) on the bottom and the last specified input, "inputN" (corresponding to the last child merge node), on top.

Usage

feMerge(mergeNodes = NULL, ...)
addMergeNode(fe, mergeNode, after = NA)
feMergeNode(input = NA)

Arguments

Details

If you wish to add more merge nodes after an fe.merge object has been created, use addMergeNode to add merge nodes to the filter primitive.

For more information about the feMerge primitive, consult the reference to the SVG specification.

Value

For feMerge, an fe.merge object.

For addMergeNode, an fe.merge object.

For feMergeNode, an fe.merge.node object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feMergeElement

See Also

filterEffect, fe.

"Fatten" or "thin" artwork.

Description

This filter primitive performs "fattening" or "thinning" of artwork. It is particularly useful for fattening or thinning an alpha channel.

Usage

feMorphology(input = NA, operator = c("erode", "dilate"),
             radius = unit(0, "npc"), default.units = "npc", ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.morphology object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feMorphologyElement

See Also

filterEffect, fe.

Offset an input image relative to its current position.

Description

This filter primitive offsets the input image relative to its current position in the image space by the specified vector.

This is important for effects like drop shadows.

Usage

feOffset(input = NA,
         dx = unit(0, "npc"), dy = unit(0, "npc"),
         default.units = "npc", ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.offset object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feOffsetElement

See Also

filterEffect, fe.

Create a Point Light Source

Description

This filter primitive defines a point light source that can be used within a lighting filter primitive: feDiffuseLighting or feSpecularLighting.

Usage

fePointLight(z = unit(0, "npc"), default.units = "npc", zdim = "x", ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.point.light object.

Author(s)

Simon Potter

References

http://www.w3.org/TR/SVG/filters.html#fePointLightElement

See Also

filterEffect, fe, feDiffuseLighting, feSpecularLighting.

Light an image using the alpha channel as a bump map.

Description

This filter primitive lights a source graphic using the alpha channel as a bump map. The resulting image is an RGBA image based on the light colour. The lighting calculation follows the standard specular component of the Phong lighting model. The resulting image depends on the light colour, light position and surface geometry of the input bump map. The result of the lighting calculation is added. The filter primitive assumes that the viewer is at infinity in the z direction (i.e., the unit vector in the eye direction is (0,0,1) everywhere).

This filter primitive produces an image which contains the specular reflection part of the lighting calculation. Such a map is intended to be combined with a texture using the add term of the arithmetic method in feComposite. Multiple light sources can be simulated by adding several of these light maps before applying it to the texture image.

Usage

feSpecularLighting(input = NA,
                   surfaceScale = 1, specularConstant = 1,
                   specularExponent = 1, kernelUnitLength = NA,
                   col = "white", lightSource = NULL, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.specular.lighting object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feSpecularLightingElement

See Also

filterEffect fe, feDistantLight, fePointLight, feSpotLight.

Create a Spot Light Source

Description

This filter primitive defines a spot light source that can be used within a lighting filter primitive: feDiffuseLighting or feSpecularLighting.

Usage

feSpotLight(x = unit(0, "npc"), y = unit(0, "npc"), z = unit(0, "npc"),
            pointsAtX = unit(1, "npc"), pointsAtY = unit(1, "npc"),
            pointsAtZ = unit(0, "npc"), zdim = "x",
            default.units = "npc", specularExponent = 1,
            limitingConeAngle = NA, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.spot.light object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feSpotLightElement

See Also

filterEffect, fe, feDiffuseLighting, feSpecularLighting.

Fill a rectangle with a tiled pattern of an input image.

Description

This filter primitive fills a target rectangle with a repeated, tiled pattern of an input image. The target rectangle is as large as the filter primitive subregion established by the x, y, width and height arguments that are passed onto fe by feTile.

Usage

feTile(input = NA, ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.tile object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feTileElement

See Also

filterEffect, fe.

Create an image using the Perlin turbulence function.

Description

This filter primitive creates an image using the Perlin turbulence function. It allows the synthesis of artificial textures like clouds or marble.

Usage

feTurbulence(baseFrequency = 0, numOctaves = 1,
             seed = 1, stitchTiles = FALSE,
             type = c("turbulence", "fractalNoise"), ...)

Arguments

Details

For more information about this primitive, consult the reference to the SVG specification.

Value

An fe.turbulence object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#feTurbulenceElement

See Also

filterEffect, fe.

Creating Filter Effects

Description

Create objects which describe filter effects. These objects can be used to add filter effect primitives. They can be used to apply a filter effect to grobs and also to define a filter effect so that it may be used multiple times.

Usage

filterEffect(feList = NULL, filterUnits = c("coords", "bbox"),
             x = unit(0.5, "npc"), y = unit(0.5, "npc"),
             width = unit(1, "npc"), height = unit(1, "npc"),
             just = "centre", hjust = NULL, vjust = NULL,
             default.units = "npc",
             primitiveUnits = c("coords", "bbox"))
addFilterEffect(filter, filterEffect, after = NA)

Arguments

Details

This is primarily a container object to hold filter effect primitives.

Value

A filter object.

Author(s)

Simon Potter

References

https://www.w3.org/TR/SVG/filters.html#FilterElement

See Also

Any of the filter effect primitives (named fe*), e.g. feGaussianBlur.

Convert animation specifications to SVG elements.

Description

This function is used to generate a list of SVG attributes based on information on a grob. It is generic so new grob classes can write their own methods.

Usage

garnish(x, ...)

Arguments

Details

This function is not called directly by the user. It is exposed so that new grob classes can easily write their own methods which call existing methods for standard grobs.

Author(s)

Paul Murrell

Manage SVG fonts

Description

These functions control the SVG font stacks that are used when exporting text to SVG.

Usage

getSVGFonts()
setSVGFonts(fontStacks)

Arguments

Details

getSVGFonts() returns a list of three font stacks called serif, sans, and mono. The user can modify the values in each stack and then reset the stacks by calling setSVGFonts() (a default value will always be forced at the end of each font stack).

Value

A list (for getSVGFonts()).

Author(s)

Simon Potter

Animate a grid grob

Description

Creates an animated.grob object. Useful in conjunction with grid.export, to produce an SVG document with animated graphical elements.

Usage

animateGrob(grob, ...,
            duration=1,
            rep=FALSE, revert=FALSE,
            begin=0, interpolate="linear", group=FALSE)
grid.animate(path, ..., group=FALSE, redraw = FALSE,
             strict=FALSE, grep=FALSE, global=FALSE)

Arguments

Value

An animated.grob object.

Author(s)

Paul Murrell

See Also

grid.export

Apply a clipping path to a grid grob.

Description

Creates a pathClipped.grob object which is a normal grid grob, with a clipping path applied to it. Used in conjunction with registerClipPath, to produce an SVG document containing graphical elements with masked content.

Usage

grid.clipPath(path, clippath = NULL, label = NULL,
              group = TRUE, redraw = FALSE,
              strict = FALSE, grep = FALSE, global = FALSE)
clipPathGrob(x, clippath = NULL, label = NULL, group = TRUE)

Arguments

Details

If label is specified, uses a clipping path that has been supplied to registerClipPath. If clippath is specified it will be used as the clipping path applied to each grob. If both are specified, it will attempt to define the clipping path with the given label, as well as applying the clipping path to the appropriate grobs.

Value

A pathClipped.grob object (for clipPathGrob).

Author(s)

Simon Potter

See Also

registerClipPath, pushClipPath.

Create a grid grob representing a comment

Description

Creates a comment.grob object which is a grid nullGrob, with a comment attached. Useful in conjunction with grid.export, to produce an SVG document with comments inserted at the point where the grob is “drawn”.

Usage

grid.comment(comment, name = NULL, vp = NULL)
commentGrob(comment, name = NULL, vp = NULL)

Arguments

Value

A comment.grob object.

Author(s)

Simon Potter

See Also

grid.export

Create a grid grob representing an SVG element

Description

Creates a element.grob object which is a grid gTree, representing an SVG element. Useful in conjunction with grid.export, to produce an SVG document with elements inserted at particular points. The element (and its children) are inserted at the point where the grob is “drawn”. Text can be inserted in a similar manner with grid.textNode.

Usage

grid.element(el, name = NULL, attrs = NULL,
             namespace = NULL, namespaceDefinitions = NULL,
             children = NULL, vp = NULL,
             childrenvp = NULL, asis = FALSE)
elementGrob(el, name = NULL, attrs = NULL,
            namespace = NULL, namespaceDefinitions = NULL,
            children = NULL, vp = NULL,
            childrenvp = NULL, asis = FALSE)
grid.textNode(text, name = NULL, vp = NULL)
textNodeGrob(text, name = NULL, vp = NULL)

Arguments

Value

An element.grob object. For grid.textNode a textnode.grob object.

Author(s)

Simon Potter

See Also

grid.export

Generate SVG output from a grid graphic

Description

Produces an SVG version of the current grid page.

Usage

grid.export(name = "Rplots.svg",
            exportCoords = c("none", "inline", "file"),
            exportMappings = c("none", "inline", "file"),
            exportJS = c("none", "inline", "file"),
            res = NULL,
            prefix = "",
            addClasses = FALSE,
            indent = TRUE,
            htmlWrapper = FALSE,
            usePaths = c("vpPaths", "gPaths", "none", "both"),
            uniqueNames = TRUE,
            annotate = TRUE,
            progress = FALSE,
            compression = 0,
            strict = TRUE,
            rootAttrs = NULL,
            xmldecl = xmlDecl())

Arguments

Details

The uniqueNames parameter is set to TRUE by default in order to ensure that each SVG element ID is unique. This is a requirement of XML (which SVG is based on). This differs from usePaths because usePaths can still generate names that are not unique (there are several ways for this to happen). uniqueNames modifies grob and viewport names with a numeric suffix to ensure uniqueness. When FALSE, only grob names will be kept unmodified because modifying viewport names would affect coordinate information.

Occasionally the XML package can report warnings, despite valid SVG being produced. If spurious warnings are being produced, set options(gridSVGWarnings = FALSE) to ignore them.

See the files in the directory gridSVG/tests for examples of things that can be done. See the file gridSVG/doc/overview.tex for limitations.

Value

When name has a valid filename the side effect is to produce an SVG file of the specified name.

Optionally a JavaScript file containing coordinate transformation information is also exported.

Optionally a JavaScript file containing name mapping information is also exported.

Optionally a JavaScript file containing utility JavaScript functions is also exported.

When name has a filename with zero characters, a named list is returned with four elements. svg is the SVG root node (and all its children, see the XML package for more information on how to use this. coords contains the list of coordinate information for exported viewports. mappings is a list containing information on how names have been modified during the exporting process. utils is a character vector containing JavaScript code to manipulate gridSVG plots in the browser.

This list is always returned but when a valid filename is given, it is returned invisibly.

Author(s)

Paul Murrell

See Also

grid.hyperlink, grid.animate, grid.garnish

Associate a filter effect with a grid grob.

Description

Creates a filtered.grob object which is a normal grid grob, with a filter effect applied to it Used in conjunction with registerFilter, to produce an SVG document containing graphical elements with filter effects.

Usage

grid.filter(path, filter = NULL, label = NULL,
            group = TRUE, redraw = FALSE,
            strict = FALSE, grep = FALSE, global = FALSE)
filterGrob(x, filter = NULL, label = NULL, group = TRUE)

Arguments

Details

If label is specified, uses a filter effect that has been supplied to registerFilter. If filter is specified it will be used as the filter effect applied to each grob. If both are specified, it will attempt to define the filter effect with the given label, as well as applying the filter effect to the appropriate grobs.

Value

A filtered.grob object (for filterGrob).

Author(s)

Simon Potter

See Also

registerFilter, filterEffect.

Associate arbitrary SVG attributes with a grid grob

Description

Creates an svg.grob object which is a normal grid grob, with SVG attributes attached. Useful in conjunction with grid.export, to produce an SVG document with attributes that have no corresponding concept in grid graphics.

Usage

garnishGrob(x, ..., group=TRUE)
grid.garnish(path, ..., group=TRUE, redraw=FALSE,
             strict = FALSE, grep=FALSE, global=FALSE)

Arguments

Details

The SVG attribute settings can be vectors (in the case of garnishing individual SVG elements) or even named vectors (if you want precise control over which attribute value is apportioned to which individual SVG element).

Value

A garnished.grob object.

Author(s)

Paul Murrell

See Also

grid.export

Associate a gradient fill with a grid grob

Description

Creates a gradientFilled.grob object which is a normal grid grob, with a gradient fill used in place of a regular fill. Used in conjunction with registerGradientFill, to produce an SVG document containing graphical elements with gradient fills.

Usage

grid.gradientFill(path, gradient = NULL, label = NULL,
                  alpha = 1, group = TRUE, redraw = FALSE,
                  strict = FALSE, grep = FALSE, global = FALSE)
gradientFillGrob(x, gradient = NULL, label = NULL,
                 alpha = 1, group = TRUE)

Arguments

Details

If label is specified, uses a gradient that has been supplied to registerGradientFill. If gradient is specified it will be used as the gradient fill applied to each grob. If both are specified, it will attempt to define the gradient with the given label, as well as applying a gradient fill to the appropriate grobs.

Value

A gradientFilled.grob object (for gradientFillGrob).

Author(s)

Simon Potter

See Also

linearGradient, radialGradient, registerGradientFill

Associate a hyperlink with a grid grob

Description

Creates a linked.grob object which is a normal grid grob, with a hyperlink attached. Useful in conjunction with grid.export, to produce an SVG document with hyperlinked graphical elements.

Usage

grid.hyperlink(path, href, show=NULL, group=TRUE, redraw=FALSE,
               strict=FALSE, grep=FALSE, global=FALSE)
hyperlinkGrob(x, href, show=NULL, group=TRUE)

Arguments

Value

A linked.grob object.

Author(s)

Paul Murrell

See Also

grid.export

Apply an opacity mask to a grid grob.

Description

Creates a masked.grob object which is a normal grid grob, with an opacity mask applied to it. Used in conjunction with registerMask, to produce an SVG document containing graphical elements with masked content.

Usage

grid.mask(path, mask = NULL, label = NULL, group = TRUE, redraw = FALSE,
          strict = FALSE, grep = FALSE, global = FALSE)
maskGrob(x, mask = NULL, label = NULL, group = TRUE)

Arguments

Details

If label is specified, uses a mask that has been supplied to registerMask. If mask is specified it will be used as the opacity mask applied to each grob. If both are specified, it will attempt to define the opacity mask with the given label, as well as applying the mask to the appropriate grobs.

Value

A masked.grob object (for maskGrob).

Author(s)

Simon Potter

See Also

registerMask, mask, pushMask.

Associate a pattern fill with a grid grob

Description

Creates a patternFilled.grob object which is a normal grid grob, with a pattern fill used in place of a regular fill. Used in conjunction with registerPatternFill, to produce an SVG document containing graphical elements with pattern fills.

Usage

grid.patternFill(path, pattern = NULL, label = NULL,
                 alpha = 1, group = TRUE, redraw = FALSE,
                 strict = FALSE, grep = FALSE, global = FALSE)
patternFillGrob(x, pattern = NULL, label = NULL,
                alpha = 1, group = TRUE)

Arguments

Details

If label is specified, uses a pattern that has been supplied to registerPatternFill. If pattern is specified it will be used as the fill pattern applied to each grob. If both are specified, it will attempt to define the pattern with the given label, as well as applying a pattern fill to the appropriate grobs.

Value

A patternFilled.grob object (for patternFillGrob).

Author(s)

Simon Potter

See Also

registerPatternFill

Create a grid grob containing an SVG script

Description

Creates a script object which is a normal grid grob containing an SVG script. Useful in conjunction with grid.export, to produce an SVG document with script elements.

Usage

scriptGrob(script=NULL, filename=NULL, type="application/ecmascript",
           inline=FALSE, name=NULL)
grid.script(...)

Arguments

Value

A script.grob object.

Author(s)

Paul Murrell

See Also

grid.export

Move to a New Page on a gridSVG Device

Description

This function erases the current device or moves to a new page. In addition, it clears any definitions of referenced content defined by gridSVG.

Usage

gridSVG.newpage(wipeRefs = TRUE, recording = TRUE)

Arguments

Details

When creating a gridSVG image, it is possible to create referenced content. An example is pattern fills. This function should be used in order to remove the definitions of referenced content.

Value

None.

Author(s)

Simon Potter

gridSVG Graphics Device

Description

Provides a convenient and familiar graphics device interface for the gridSVG package.

Usage

gridsvg(name = "Rplots.svg",
        exportCoords = c("none", "inline", "file"),
        exportMappings = c("none", "inline", "file"),
        exportJS = c("none", "inline", "file"),
        res = NULL,
        prefix = "",
        addClasses = FALSE,
        indent = TRUE,
        htmlWrapper = FALSE,
        usePaths = c("vpPaths", "gPaths", "none", "both"),
        uniqueNames = TRUE,
        annotate = TRUE,
        progress = FALSE,
        compression = 0,
        strict = TRUE,
        rootAttrs = NULL,
        xmldecl = xmlDecl(), ...)
dev.off(which = dev.cur())

Arguments

Details

These functions provide a more familiar and perhaps convenient interface to gridSVG than grid.export. It uses a PDF device as drawing occurs, but when the device needs to be written out (via dev.off) then it will save an SVG image instead.

When a grid display list is not in use, or any device other than the gridsvg device is used, the behaviour of dev.off is the same as dev.off from the grDevices package.

Value

gridsvg returns nothing.

dev.off will return in the same manner as grid.export. A list is always returned, but invisibly when an invalid filename is given.

Author(s)

Simon Potter

See Also

pdf and grid.export.

Convert a grob to device calls

Description

This function is used to make calls to a device to draw a grob. It is generic so new grob classes can write their own methods.

Usage

grobToDev(x, dev)

Arguments

Details

This function is not called directly by the user. It is exposed so that new grob classes can easily write their own methods which call existing methods for standard grobs.

The difference between this function and primToDev() is that this one takes care of setting up coordinate systems based on the grid viewports so that SVG output is positioned correctly, then it calls primToDev() to produce the actual SVG elements.

Author(s)

Paul Murrell

List All Reference Definitions

Description

Returns a listing of the labels given to reference definitions.

Usage

listSVGDefinitions(print = TRUE)

Arguments

Details

When definitions of referenced content are stored in gridSVG via any of the register* functions (e.g. registerPatternFill), we can use this function to show us all of the labels given when content is registered.

Value

A data frame, returned invisibly.

Author(s)

Simon Potter

Leaving A Modified Viewport Context

Description

A modified viewport context is where the appearance of grobs is no longer determined solely by the grob itself and the viewport into which they're drawn. This can occur when applying clipping paths and opacity masks, which modify the appearance of anything drawn after they have been applied. This function should be used when attempting to stop the effect of a modified viewport context (e.g. to stop clipping to paths).

Usage

popContext(n = 1)

Arguments

Details

Popping a context can produce a warning. In this case it is recommended that the context "pushing" and "popping" be revised to have matching pairs of pushes and pops.

Value

None.

Author(s)

Simon Potter

See Also

grid.clipPath and grid.mask

Convert a grob to device calls

Description

This function is used to make calls to a device to draw a grob. It is generic so new grob classes can write their own methods.

Usage

primToDev(x, dev)

Arguments

Details

This function is not called directly by the user. It is exposed so that new grob classes can easily write their own methods which call existing methods for standard grobs.

Author(s)

Paul Murrell

Apply a clipping context to the current viewport.

Description

This function is intended to be used similarly to grid.clip. The only difference is that a non-rectangular clipping region can be applied.

Usage

pushClipPath(clippath = NULL, label = NULL, name = NULL, draw = TRUE)
popClipPath()

Arguments

Details

If label is specified, uses a clipping path that has been supplied to registerClipPath. If clippath is specified it will be used as the new clipping context for the current viewport. If both are specified, it will attempt to define the clipping path with the given label, as well as adding the clipping path as a clipping context for the current viewport.

popClipPath is an alias for popContext

Value

A pushClipPath grob. The value is returned invisibly.

Author(s)

Simon Potter

See Also

registerClipPath, grid.clipPath, popContext.

Apply a masking context to the current viewport.

Description

This function is intended to be used similarly to grid.clip. The key difference is that instead of applying a new clipping context to the viewport, we apply a new masking context.

Usage

pushMask(mask = NULL, label = NULL, name = NULL, draw = TRUE)
popMask()

Arguments

Details

If label is specified, uses a mask that has been supplied to registerMask. If mask is specified it will be used as the new masking context for the current viewport. If both are specified, it will attempt to define the mask with the given label, as well as applying the mask as the new masking context for the current viewport.

popMask is an alias for popContext.

Value

A pushMask grob. The value is returned invisibly.

Author(s)

Simon Potter

See Also

mask, registerMask, grid.mask, popContext.

Create the definition a filter effect.

Description

A feature of SVG is that elements can be filtered using filter effects defined somewhere in the document. The purpose of this function is to create the definition of a filter effect so that it can be referred to by grobs drawn by gridSVG.

Usage

registerFilter(label, filter)

Arguments

Details

When registering a filter, all locations and dimensions that filter effects refer to become fixed.

Value

None.

Author(s)

Simon Potter

See Also

grid.filter, filterEffect.

Get and Set Global Options

Description

Provides access to a predefined set of global options for the gridSVG package.

Usage

getSVGoption(name)
getSVGoptions()
setSVGoptions(...)

Arguments

Details

The options currently available are:

• id.sep which controls the separator used between the grob name and the suffix number when gridSVG generates id values for SVG elements.

• gPath.sep which controls the separator used between elements of a grid gPath.

• vpPath.sep which controls the separator used between elements of a grid vpPath.

Value

getSVGoption() returns at most one option setting. getSVGoptions() returns all option settings. setSVGoptions() returns a list of previous option settings for the options that were changed.

Author(s)

Paul Murrell

See Also

grid.export

Internal gridSVG Functions

Description

Some functions you can call, but I'm not documenting (yet).

Recreate a viewport from imported coordinate information.

Description

Creates a viewport object that is positioned in the same location as a previously exported viewport.

The purpose of this function is so that we can recreate content for later manipulation.

Usage

viewportCreate(vpname, newname = NULL,
               vpPath.sep = getSVGoption("vpPath.sep"))

Arguments

Details

In order to use this function, coordinate information must be available to gridSVG. This means that viewport information must be imported using gridSVGCoords.

The ROOT viewport must also have coordinate information imported because the created viewport is positioned relative to this.

Value

A viewport object.

Author(s)

Simon Potter

Examples

## Not run: 
  require(grid)

  grid.newpage()

  # Pushing a new VP to draw a rect within
  pushViewport(viewport(x = unit(0.3, "npc"), y = unit(0.2, "npc"),
                        width = unit(0.1, "npc"), height = unit(0.3, "npc"),
                        xscale = c(0, 20), yscale = c(0, 10),
                        name = "testVP"))
  grid.rect()
  grid.export("create-test.svg", exportCoords = "file")

  # Importing coordinate information
  gridSVGCoords(readCoordsJS("create-test.svg.coords.js"))

  # This should appear to be the same rect
  grid.newpage()
  pushViewport(viewportCreate("testVP.1"))
  grid.rect()

  # Let's see if the scales are accurate, should be:
  # xscale: [0, 20]
  # yscale: [0, 10]
  current.viewport()$xscale
  current.viewport()$yscale

## End(Not run)