R: Create the definition of an opacity mask.

Opacity Masks {gridSVG}

R Documentation

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

`grob`	A grob or gTree that will be drawn as the opacity mask.
`x`	A numeric vector or unit object specifying x-location.
`y`	A numeric vector or unit object specifying y-location.
`width`	A numeric vector or unit object specifying width.
`height`	A numeric vector or unit object specifying height.
`default.units`	A string indicating the default units to use if `x`, `y`, `width`, or `height` are only given as numeric vectors.
`just`	The justification of the pattern relative to its (x, y) location. If there are two values, the first value specifies horizontal justification and the second value specifies vertical justification. Possible string values are: `"left"`, `"right"`, `"centre"`, `"center"`, `"bottom"`, and `"top"`. For numeric values, 0 means left alignment and 1 means right alignment.
`hjust`	A numeric vector specifying horizontal justification. If specified, overrides the `just` setting.
`vjust`	A numeric vector specifying vertical justification. If specified, overrides the `just` setting.
`label`	A character identifier that will be used to reference this definition.
`mask`	A `mask` object that defines the mask.
`...`	Arguments to be given to `mask`.

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