Your IP : 216.73.216.145
# svg.filter.js
A plugin for [svg.js](https://svgdotjs.github.io) adding filter functionality.
svg.filter.js is licensed under the terms of the MIT License.
- [Examples](#examples)
- [Furthermore](#furthermore)
- [unfilter](#unfilter)
- [referencing the filter node](#referencing-the-filter-node)
- [Animating filter values](#animating-filter-values)
- [Chaining Effects](#chaining-effects)
- [Effect Classes](#effect-classes)
## Usage
### Npm
```sh
npm i @svgdotjs/svg.filter.js
```
### Yarn
```sh
yarn add @svgdotjs/svg.filter.js
```
Include this plugin after including the svg.js library in your html document.
Here is how each filter effect on the example page is achieved.
## Examples
- [gaussian blur](#gaussian-blur)
- [horizontal blur](#horizontal-blur)
- [desaturate](#desaturate)
- [contrast](#contrast)
- [sepiatone](#sepiatone)
- [hue rotate 180](#hue-rotate-180)
- [luminance to alpha](#luminance-to-alpha)
- [colorize](#colorize)
- [posterize](#posterize)
- [darken](#darken)
- [lighten](#lighten)
- [invert](#invert)
- [gamma correct 1](#gamma-correct-1)
- [gamma correct 2](#gamma-correct-2)
- [drop shadow](#drop-shadow)
- [extrude](#extrude)
### original
```javascript
var image = draw.image('path/to/image.jpg').size(300, 300)
```
### gaussian blur
```javascript
image.filterWith(function(add) {
add.gaussianBlur(30)
})
```
### horizontal blur
```javascript
image.filterWith(function(add) {
add.gaussianBlur(30, 0)
})
```
### desaturate
```javascript
image.filterWith(function(add) {
add.colorMatrix('saturate', 0)
})
```
### contrast
```javascript
image.filterWith(function(add) {
var amount = 1.5
add.componentTransfer({
type: 'linear',
slope: amount,
intercept: -(0.3 * amount) + 0.3
})
})
```
### sepiatone
```javascript
image.filterWith(function(add) {
add.colorMatrix('matrix', [ .343, .669, .119, 0, 0
, .249, .626, .130, 0, 0
, .172, .334, .111, 0, 0
, .000, .000, .000, 1, 0 ])
})
```
### hue rotate 180
```javascript
image.filterWith(function(add) {
add.colorMatrix('hueRotate', 180)
})
```
### luminance to alpha
```javascript
image.filterWith(function(add) {
add.colorMatrix('luminanceToAlpha')
})
```
### colorize
```javascript
image.filterWith(function(add) {
add.colorMatrix('matrix', [ 1.0, 0, 0, 0, 0
, 0, 0.2, 0, 0, 0
, 0, 0, 0.2, 0, 0
, 0, 0, 0, 1.0, 0 ])
})
```
### posterize
```javascript
image.filterWith(function(add) {
add.componentTransfer({
type: 'discrete',
tableValues: [0, 0.2, 0.4, 0.6, 0.8, 1]
})
})
```
### darken
```javascript
image.filterWith(function(add) {
add.componentTransfer({
type: 'linear',
slope: 0.2
})
})
```
### lighten
```javascript
image.filterWith(function(add) {
add.componentTransfer({
type: 'linear',
slope: 1.5,
intercept: 0.2
})
})
```
### invert
```javascript
image.filterWith(function(add) {
add.componentTransfer({
type: 'table'
tableValues: [1, 0]
})
})
```
### gamma correct 1
```javascript
image.filterWith(function(add) {
add.componentTransfer({
g: { type: 'gamma', amplitude: 1, exponent: 0.5 }
})
})
```
### gamma correct 2
```javascript
image.filterWith(function(add) {
add.componentTransfer({
g: { type: 'gamma', amplitude: 1, exponent: 0.5, offset: -0.1 }
})
})
```
### drop shadow
You will notice that all the effect descriptions have a drop shadow. Here is how this drop shadow can be achieved:
```javascript
var text = draw.text('SVG text with drop shadow').fill('#fff')
text.filterWith(function(add) {
var blur = add.offset(0, 1).in(add.$sourceAlpha).gaussianBlur(1)
add.blend(add.$source, blur)
})
```
This technique can be achieved on any other shape of course:
```javascript
var rect = draw.rect(100,100).fill('#f09').stroke({ width: 3, color: '#0f9' }).move(10,10)
rect.filterWith(function(add) {
var blur = add.offset(20, 20).in(add.$sourceAlpha).gaussianBlur(5)
add.blend(add.$source, blur)
this.size('200%','200%').move('-50%', '-50%')
})
```
If the drop shadow should get the colour of the shape so it appears like coloured glass:
```javascript
var rect = draw.rect(100,100).fill('#f09').stroke({ width: 3, color: '#0f9' }).move(10,10)
rect.filterWith(function(add) {
var blur = add.offset(20, 20).gaussianBlur(5)
add.blend(add.$source, blur)
this.size('200%','200%').move('-50%', '-50%')
})
```
### extrude
```javascript
image.filterWith(function(add){
var matrix = add.convolveMatrix([
1,0,0,0,0,0,
0,1,0,0,0,0,
0,0,1,0,0,0,
0,0,0,1,0,0,
0,0,0,0,1,0,
0,0,0,0,0,1
]).attr({
devisor: '2',
preserveAlpha: 'false'
}).in(add.$sourceAlpha)
//recolor it
var color = add.composite(add.flood('#ff2222'),matrix,'in');
//merge all of them toggether
add.merge(color,add.$source);
})
```
## Furthermore
Some more features you should know about.
### unfilter
The `unfilter` method removes the filter attribute from the node:
```javascript
image.unfilter()
```
### creating a reusable filter
its also posible to create a filter by using the `new` keyword
*NOTE: when creating a filter this way, it can take an optional attr object*
```javascript
var filter = new SVG.Filter();
// create the filters effects here
filter.offset(20, 20).gaussianBlur(5);
filter.blend(filter.$source, blur);
filter.size('200%','200%').move('-50%', '-50%')
```
then once you have created the filter you can use it one multiple elements
```javascript
var image = new SVG.Image();
var shape = new SVG.Rect(10, 10);
image.filterWith(filter);
shape.filterWith(filter);
```
### referencing the filter node
An internal reference to the filter node is made in the element:
```javascript
image.filterer()
```
This can also be very useful to reuse an existing filter on various elements:
```javascript
otherimage.filterWith(image.filterer())
```
### Animating filter values
Every filter value can be animated as well:
```javascript
var hueRotate
image.filterWith(function(add) {
hueRotate = add.colorMatrix('hueRotate', 0)
})
hueRotate.animate(3000).attr('values', 360)
```
### Chaining Effects
[Method chaining](https://en.wikipedia.org/wiki/Method_chaining) is a programing style where each function returns the object it belongs to, for an example look at JQuery.<br>
it's possible to chain the effects on a filter when you are creating them, for example:
```javascript
image.filterWith(function(add){
add.flood('black',0.5).composite(add.$sourceAlpha,'in').offset(10).merge(add.$source)
})
```
this would create a basic shadow filter where the first input on the `composite` effect would be the `flood` effect, and the input on the offset effect would be the `composite` effect.<br>
same with the `merge` effect, its first input would be the `offset` effect, and its second input would be `add.$source`
some effects like [Merge](#merge), [Blend](blend), [Composite](#composite), [DisplacementMap](displacementmap) have thier arguments changed when they are chained, for example
```javascript
image.filterWith(function(add){
add.flood('black',0.5).composite(add.$sourceAlpha,'in')
})
```
the `composite` effects first input is set to the `flood` effect and its second input becomes the first argument, this is the same for the merge, blend, composite, and displacmentMap effect. <br>
for more details check out each effects doc below
## Effect Classes
- [Base Effect Class](base-effect-class)
- [Blend](#blend)
- [ColorMatrix](#colormatrix)
- [ComponentTransfer](#componenttransfer)
- [Composite](#composite)
- [ConvolveMatrix](#convolvematrix)
- [DiffuseLighting](#diffuselighting)
- [DisplacementMap](#displacementmap)
- [Flood](#flood)
- [GaussianBlur](#gaussianblur)
- [Image](#image)
- [Merge](#merge)
- [Morphology](#morphology)
- [Offset](#offset)
- [SpecularLighting](#specularlighting)
- [Tile](#tile)
- [Turbulence](#turbulence)
### Base Effect Class
#### in(effect)
gets or sets the `in` attribute of the effect
- **effect:** this can be another effect or a string <br>
if **effect** is not provided it will look for another effect on the same filter whose `result` is equal to this effects `in` attribute, else it will return the value of the `in` attribute
```javascript
image.filterWith(function(add){
var offset = add.offset(10)
//create the blur effect and then set its input
var blur = add.gaussianBlur(3)
//set the input to an effect
blur.in(offset)
//this will return the offset effect
var input = blur.in()
//set the input to a string
blur.in('another-result-as-a-string')
//this will return a string since there is no other effect which has a matching result attribute
var input2 = blur.in()
})
```
#### in2(effect)
gets or sets the `in2` attribute of the effect <br>
this function works the same as the [in](#ineffect) method. <br>
it's only on effects ([Blend](#blend), [Composite](#composite), and [DisplacementMap](#displacementmap))
#### result(string)
gets or sets the `result` attribute of the effect
- **string:** if a string is provided it will set the value of the `result` attribute. <br>
if no arguments are provided it will act as a getter and return the value of the `result` attribute
### Blend
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feBlendElement)
```javascript
filter.blend(in1, in2, mode)
//or
new SVG.BlendEffect({in1, in2, mode})
```
- **in1**: an effect or the result of effect
- **in2**: same as **in1**
- **mode**: "normal | multiply | screen | darken | lighten" defaults to "normal"
**chaining** when this effect is called right after another effect, for example:
```javascript
filter.offset(10).blend(filter.$source)
```
the first input is set to the `offset` effect and the second input is set to `filter.$source` or what ever was passed as the first argument, and the second input becomes the **mode**
### ColorMatrix
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feColorMatrixElement)
```javascript
filter.colorMatrix(type, values);
//or
new SVG.ColorMatrixEffect({type, values});
```
- **type**: "matrix | saturate | hueRotate | luminanceToAlpha"
- **values**
- **type="matrix"**: values would be a matrix the size of 4x5
- **type="saturate"**: number (0 to 1)
- **type="hueRotate"**: number (0 to 360) deg
- **type="luminanceToAlpha"**: value not needed
### ComponentTransfer
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feComponentTransferElement)
```javascript
filter.componentTransfer(components);
// or
filter.componentTransfer(function (add) { add.funcA({ type... }) });
//or
new SVG.ComponentTransferEffect();
```
- **components**: an object which is set for all chanels or `r`, `g`, `b`, `a` properties for each chanel
```javascript
type: "identity | table | discrete | linear | gamma",
//type="table"
tableValues: "0 0.5 2 1", //number separated by spaces
//type="linear"
slope: 1, //number
intercept: 3,//number
//type="gamma"
amplitude: 0, //number
exponent: 0, //number
offset: 0 //number
}
```
### Composite
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feCompositeElement)
```javascript
filter.composite(in1, in2, operator);
//or
new SVG.CompositeEffect({in1, in2, operator});
```
- **in1**: an effect or the result of an effect
- **in2**: same as **in1**
- **operator**: "over | in | out | atop | xor | arithmetic" defaults to "over"
**chaining** when this effect is called right after another effect, for example:
```javascript
filter.flood('black',0.5).composite(filter.$sourceAlpha,'in')
```
the first input is set to the `flood` effect and the second input is set to `filter.$sourceAlpha` or what ever was passed as the first argument.<br>
also the second argument becomes the **operator**
### ConvolveMatrix
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feConvolveMatrixElement)
```javascript
filter.convolveMatrix(matrix);
//or
new SVG.ConvolveMatrixEffect({matrix});
```
- **matrix**: a square matrix of numbers that will be applied to the image
- exmaple:
```javascript
[
1,0,0,
0,1,0,
0,0,1
]
```
### DiffuseLighting
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feDiffuseLightingElement)
```javascript
filter.diffuseLighting(surfaceScale, lightingColor, diffuseConstant, kernelUnitLength);
//or
new SVG.DiffuseLightingEffect({surfaceScale, lightingColor, diffuseConstant, kernelUnitLength});
```
***very complicated, just check out the W3 doc***
### DisplacementMap
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feDisplacementMapElement)
```javascript
filter.displacementMap(in1, in2, scale, xChannelSelector, yChannelSelector);
//or
new SVG.DisplacementMapEffect({in1, in2, scale, xChannelSelector, yChannelSelector});
```
***very complicated, just check out the W3 doc***
**chaining** when this effect is called right after another effect, for example:
```javascript
filter.offset(20,50).displacementMap(filter.$source,2)
```
the first input is set to the `offset` effect and the second input is set to `filter.$source` or what ever was passed as the first argument.<br>
also the second argument becomes the **scale**, and the third argument is the **xChannelSelector** and so on
### Flood
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feFloodElement)
```javascript
filter.flood(color,opacity);
//or
new SVG.FloodEffect(color,opacity);
```
- **color**: a named or hex color in string format
- **opacity**: number form 0 to 1
### GaussianBlur
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feGaussianBlurElement)
```javascript
filter.gaussianBlur(x, y);
//or
new SVG.GaussianBlurEffect({x, y});
```
- **x**: blur on the X
- **y**: blur on the y, will default to the **x** if not provided
### Image
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feImageElement)
```javascript
filter.image(src);
//or
new SVG.ImageEffect({src});
```
### Merge
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feMergeElement)
```javascript
filter.merge();
//or
new SVG.MergeEffect();
```
- **Array**: an Array of effects or effect results `filter.merge([effectOne,"result-two",another_effect])`
- **chaining** you can also chain the merge effect `filter.offset(10).merge(anotherEffect)` which will result in a merge effect with its first input set to the `offset` effect and its second input set to `anotherEffect`
### Morphology
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feMorphologyElement)
```javascript
filter.morphology(operator, radius);
//or
new SVG.MorphologyEffect({operator, radius});
```
- **operator**: "erode | dilate"
- **radius**: a single number or a string of two numbers separated by a space
- the first number is the X
- the second number is the Y, if no second number was provided it will default to the first number
### Offset
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feOffsetElement)
```javascript
filter.offset(x, y);
//or
new SVG.OffsetEffect({x, y});
```
- **x**: move on the X
- **y**: move on the y, will default to the **x** if not provided
### SpecularLighting
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feSpecularLightingElement)
```javascript
filter.specularLighting(surfaceScale, lightingColor, diffuseConstant, specularExponent, kernelUnitLength);
//or
new SVG.SpecularLightingEffect(surfaceScale, lightingColor, diffuseConstant, specularExponent, kernelUnitLength);
```
***very complicated, just check out the W3 doc***
### Tile
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feTileElement)
```javascript
filter.tile();
//or
new SVG.TileEffect();
```
***no arguments, but if you want to find out what it does check out the W3 doc***
### Turbulence
[W3 doc](https://www.w3.org/TR/SVG/filters.html#feTurbulenceElement)
```javascript
filter.turbulence(baseFrequency, numOctaves, seed, stitchTiles, type);
//or
new SVG.TurbulenceEffect({baseFrequency, numOctaves, seed, stitchTiles, type});
```
***very complicated, just check out the W3 doc***