The overlay feature overlays an image or text string on top of a derivative (output) image. This can be useful for description, branding, attribution, copyright notices, and so on.
With both types of overlays, the position, inset, and output dimensions threshold (below which the overlay won't be drawn) are configurable.
The overlay system offers two "strategies," or modes of operation: a basic strategy, where overlay properties are set in the configuration file and applied to all requests; and a script strategy, where the decision of whether to apply an overlay, and what kind, depends on the return value of a delegate method. The overlays.strategy
configuration key is used to set the strategy.
With BasicStrategy, the overlays.BasicStrategy.*
keys in the configuration file are used to set an overlay type (image or string), position, inset, and others. This strategy is easy to configure and is all that is needed when it is intended for the same overlay to be applied to all images.
Perhaps you want to apply an image overlay to some of your images, and to others, you want to apply a string overlay, or no overlay. Perhaps you want to control overlays based on the client's IP address or user agent. Using the overlay()
delegate method, this can be accomplished in just a few lines of code.
Position and inset are configurable. Supported positions are top left
, top center
, top right
, left center
, center
, right center
, bottom left
, bottom center
, and bottom right
. Image overlays also support repeat
and scaled
. All positions except repeat
support an inset.
An image overlay must be an 8-bit RGB or RGBA PNG image. It will be blended pixel-for-pixel into the output image.
Overlay images can be located on the filesystem or a web server. Regardless, they are cached in memory after being loaded the first time.
When using multiple image overlays, their filenames must all be different, regardless of where they reside.
The sample image above is opaque. To achieve the semi-transparency that some of the examples below demonstrate, the alpha channel must be rescaled in an image editor.
String overlays are dynamically rendered onto an image using Java 2D. The font family, size, weight, color, stroke color, background color and opacity, etc., are configurable.
Line breaks within the string (\n
) are respected, enabling multi-line strings. Each line is auto-aligned to the edge of the image according to the overlay position.
When using BasicStrategy, the lines of the string are applied verbatim and not wrapped or broken in any way. If a string doesn't fit entirely inside the image at its specified font size, the application will try to use the largest font size that fits, down to the configurable minimum allowed size. If none fit, the string won't be drawn.
ScriptStrategy can work the same way, but it also supports a word wrap mode, which can be enabled by returning a value of true
for a word_wrap
key in the hash returned from overlay()
. When word wrap is enabled, the string is broken at word boundaries to fit inside the width of the image. If the resulting string's height exceeds the image's height, it won't be drawn.
To get a list of all available fonts, start the JVM with the -list-fonts
command-line argument.
This example renders the image identifier onto the image.
Zooming image viewers display a mosaic of cropped image tiles. There are a few techniques that can prevent each tile from receiving an overlay:
overlays.BasicStrategy.output_width_threshold
and overlays.BasicStrategy.output_height_threshold
configuration options to values that are slightly larger than the tile size used by the image viewer. This will disable overlays for images the size of image viewer tiles, and enable them for anything larger. Be aware, though, that the tile size used by the viewer may differ depending on the source image.overlay()
delegate method. Of course, a user could figure this out and supply the same argument in other image requests.nil
if a crop operation is present in the operation list. Example: