Documentation

Simple Effects

The easiest way to use Filter Effects for Raphael is to apply a simple effect to an element. These methods extend the Raphael.js Element object; that is, you can apply them directly to an Element (such as a Path).

Blur

This method performs a Gaussian Blur on the scope element.

Element.blur([stdDeviation]);

The blur method accepts one argument, an optional standard deviation for the Guassian Blur. The standard deviation defaults to 3.

Example:

var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "black"});
path.blur();

Shadow

This method adds a drop shadow to the scope element.

Element.shadow([dx], [dy], [blur], [opacity], [color]);

The shadow method accepts the following arguments

• dx: the "x" offset in pixels, defaults to 3
• dy: the "y" offset in pixels, defaults to 3
• blur: the amount of blur for the shadow (see "blur"), defaults to 3
• opacity: the opacity for the shadow, between 0 and 1, defaults to 0.6 (i.e. 60%)
• color: any valid SVG color string, defaults to black

Example:

var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "black"});
path.shadow();

Light

The light method will render the scope element as if it were lit from a point in space. The filter includes either a diffused or specular light source. Diffused lighting gives a general feel of a light source (such as the sun, a window, bulb, etc) and specular creates a spotlight.

Element.light([x], [y], [x], [color], [type]);

The values passed to the light method are:

• x: The "x" position of the light source, defaults to the right-hand-side of the paper
• y: The "y" position of the light source, defaults to 0
• z: The height of the light source above the paper, defaults to 20
• color: Any valid SVG color string, defaults to null (which gives the light no color, in effect white)
• type: Either "diffuse" or "specular", defaults to diffuse.

Example:

var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "black"});
path.light();

Color Shift

Color shift pushes an element towards a particular color; for example, a red color shift would push blue through purple towards red and would push yellow through orange towards red.

Element.colorShift([color], [shiftAmount]);

The two arguments for colorShift are:

• color: Any valid SVG color string, defaults to black
• shiftAmount: a number between 0 and 1 which represents the extent of the shift; if 0 is applied no transformation will take place, if 1 is supplied the element will be entirely the new color, if 0.5 is supplied the element will be half way between it's original colors and the supplied color. Defaults to 0.5.

Example:

var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "yellow"});
path.colorShift("blue");

Emboss

Creates a filter to make the scope element appear embossed.

Element.emboss([height]);

The "height" argument for the emboss method indicates how much the element should be embossed, i.e. how high to raise it. It defaults to 2.

Example:

var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "black"});
path.emboss();

Advanced Effects

The simple effects (listed above) are pre-canned filters which can be applied to elements. It is possible to create your own filters which can be applied to elements in a number of ways. Using these tools it is possible to achieve any effect which can be created using SVG FilterEffects.

A typical flow would involve creating a new filter and then stacking some effects onto the filter before applying the filter to one or more elements.

The Filter class

The basis of filters is the Filter class. Creating an instance of this class will create a filter SVG tag in the drawing; the instance will manage adding filter effects to the filter tag and can, if required, manage the filter's ID and the chaining of filter effects ("in", "in2" and "result" attributes in the filter effect tags).

There are three ways to create a filter: directly, through the constructor, using the helper method which extends Raphael Papers or using the helper method which extends Raphael Elements.

Filter constructor

Creates a new Filter.

FRaphael.Filter([id]);

The Filter constructor can be called with an explicit id, if omitted the id will be generated.

Example:

var myFilter = new FRaphael.Filter();

Creating a filter from a paper

This method wraps the Filter constructor.

Paper.filter([id]);

Example:

var paper = Raphael("divId");
var myFilter = paper.filter();

Getting a filter for an element

The getFilter method will either return the filter that is already applied to the scope element or, in the case that there is no filter, will create a new Filter and apply it to the element. An SVG element can only have a single filter so this is a convenient way to create new Filters - pre-applied to an element.

Element.getFilter();

Example:

var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "black"});
var myFilter = path.getFilter();

Adding filter effects

Once you have created a filter you are ready to start adding filter effects to it. Effects can be added using helper methods from the filter or manually using a DOM interface.

Filter effect helpers

The following list of methods can be applied to a filter to add an effect. All of these methods accept an optional attributes object which constitutes a key-value list that will become attributes in the filter effect tag.

• Filter.addBlur(stdDeviation, [attributes]); - see Element.blur()
• Filter.addOffset(dx, dy, [attribuites]); - moves elements by the vector dx, dy
• Filter.addLighting(x, y, z, [color], [type], [attribuites]); - see Element.light()
• Filter.addShiftToColor(color, [moveBy], [attribuites]); - see Element.colorShift()
• Filter.addRecolor(color, [opacity], [attribuites]); - similar to addShiftToColor(), this method recolors elements to the specified color and opacity - the color shift method does not allow you to apply opacity
• Filter.addConvolveMatrix(matrix, [attribuites]); - Applies a convolve matrix transformation, the matrix argument should be a string of 9 digits seperated by spaces - see W3C documentation

Composite filter effect helpers

These methods add a series of filter effects to create an overall effect (used in the element helpers).

• Filter.createShadow(dx, dy, blur, [opacity], [color]); - see Element.shadow()
• Filter.createEmboss(height, [x], [y], [z]); - see Element.emboss(), the x, y, z coordinates are used to generate a diffused lighting for the effect and can be overridden

Flattening filter effect helpers

These methods will combine other layers of effects in non-linear ways. These methods are more difficult to use and the W3C documentation should be consulted for more details on what the effects achieve.

• Filter.merge(in1, in2, [attributes]); - performs a "merge" of the two results, in1 and in2
• Filter.compose(in1, in2, [operator], [attributes]); - performs a "compose" of the two results, in1 and in2, operator defaults to "over"
• Filter.arithmeticCompose(in1, in2, k1, k2, k3, k4); - wraps the compose method to apply the arithmetic compose operator with given k-values

Applying filters to elements

Filters are applied to elements using the Element's helper method, filter.

Element.filter(filter|id)

The method takes a single argument which is either a Filter object or a string representing the ID of a valid filter.

Example:

var paper = Raphael("divId");
var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "black"});

var myFilter = paper.filter();
myFilter.addBlur(5);

path.filter(myFilter);

Example 2:

var paper = Raphael("divId");
var path = paper.path("M 10 10 l 10 0 l 0 10 z").attr({fill: "red", stroke: "black"});

var myFilter = paper.filter("my-filter");
myFilter.addBlur(5);

path.filter("my-filter");

Manually creating filter effects

If you need to work directly with the DOM to create SVG filter effects which are not covered by the Filter helper methods, then you can create a filter effect manually. This can be done using the FilterEffect constructor but is recommended that you use either the addEffect() or chainEffect() helper methods.

Add effect

The add effect method will create a DOM structure to represent a filter effect, and add that to the scope filter.

Filter.addEffect(type, attributes, [children]);

add effects accepts:

• type: A string representing the type of the tag to create - see W3C documentation on Filter Effects
• attributes: An object describing key-value pairs for the attributes of the tag
• children: Either a single FilterEffect

Example:

filter.addEffect("feTurbulence", {type: "turbulence", baseFrequency: "0.05", numOctaves: "2"});

Chain effect

The chain effect method works in exactly the same way as the add effect method accept that it manages the chaining of effects; that is, it will set the "in" attribute to be the "result" of the previous effect in the filter.

Filter.chainEffect(type, attributes, [children]);

The FilterEffect constructor

The FilterEffect constructor will create a new filter effect tag but not apply it to the DOM. The effect element (in the DOM sense) can be found in a member called element, which can be attached to the DOM manually.

FRaphael.FilterEffect(type, attributes);

The constructor requires two arguments:

• type: A string representing the type of the tag to create - see W3C documentation on Filter Effects
• attributes: An object describing key-value pairs for the attributes of the tag

Example:

var filter = paper.filter();
var effect = new FRaphael.FilterEffect("feTurbulence", {type: "turbulence", baseFrequency: "0.05", numOctaves: "2"});
filter.element.appendChild(effect.element);

Other functions

Get filter

See Element.getFilter().

FRaphael.getFilter(element);

Get last result

When using the Filter.chainEffect() method to add bespoke effects an increment ID is used to track the result of each effect and used as the in value for the next. You can use this method to retrieve the current output ID. This technique is useful for doing other kinds of flattening, such as merges.

Filter.getLastResult();