Filters are an integral part of Chevalet. Each filter modifies a request's original image and passes the modified image to the next filter. At the end of the filter chain, Chevalet outputs a URL to the resulting image.
Explore the range of filters available by browsing classes in the Chevalet::Filters module, or read below for information on how to use filters in general.
Filters are specified using JSON. If the optional filters
parameter is set to a valid JSON string, Chevalet will apply the requested filters in
the order specified. The JSON data itself should be an array of JSON
objects representing filters. For example:
[
{
"filter": "resize",
"params": { "geometry": "150%" }
},
{
"filter": "crop",
"params": { "width": 200, "height": 560 }
}
]
The above JSON will apply the Chevalet::Filters::Resize filter, followed by Chevalet::Filters::Crop, along with the specified parameters. Some filters accept parameters and some do not; refer to individual filters’ documentation for details.
Certain filters combine two or more images. The algorithm used in the composition process is called a blend mode, and many unique blend modes are available, ranging from the utilitarian to the artistic.
Perhaps the simplest blend mode is “over,” which simply overlays one image on top of another, as you would expect. This is the default blend mode for many filters which composite images.
To specify a blend mode, simply provide a blend mode string. Some
commonly-used blend modes are documented below. For a complete list, refer
to RMagick’s CompositeOperator
documentation. To use one of RMagick’s blend algorithms, remove
“CompositeOp” from the end of its name, and then convert the remainder from
CamelCase to lowercase_underscored. For example,
HardLightCompositeOp would be specified as
hard_light.
over
Normal: take each pixel from the top layer if present. Otherwise, use pixels from the bottom layer.
multiply
Multiply the pixels for the top and bottom layers. See en.wikipedia.org/wiki/Blend_mode#Multiply.
screen
Invert, multiply and invert again the pixels for the top and bottom layers. See en.wikipedia.org/wiki/Blend_mode#Screen.
overlay
Combine the multiply and screen modes to make dark parts darker and light parts lighter. See en.wikipedia.org/wiki/Blend_mode#Overlay.
Many parameters specify colors to use when drawing various elements, such
as text or shapes. Chevalet accepts any
standard RMagick color name or formatted string, such as green
or rgb(138,203,94). Refer to RMagick’s color
name documentation for an exhaustive overview.
Notably, the color string none may be used to specify
transparency.
Chevalet makes several typefaces available to filters which render text. To specify a font, simply use one of the strings below:
bello
Bello Pro
comicsans
Comic Sans
fixedsys
Fixedsys
fsalbert
FSAlbert
impact
Impact
interstate
Interstate
komika
Komika
lapture
Lapture
myriad
Myriad Pro
Some filters accept one or more geometry string parameters. These strings are an ImageMagick standard, and are capable of describing width, height and offset values and the rules applied to them.
For detailed information on crafting geometry strings, refer to ImageMagick’s geometry string documentation.
Gravity provides a convenient method of specifying a relative location in an image, e.g. “top left,” “middle bottom” or “center”. Some filters use gravity to specify in which direction offsets are measured, or where certain elements to be overlaid should be placed.
To specify a type of gravity, simply provide one of the following strings:
north_west
Top left
north
Top center
north_east
Top right
west
Left center
center
In the middle
east
Right center
south_west
Bottom left
south
Bottom center
south_east
Bottom right
A common default gravity is north_west, which measures from
the top left.