Overview

This plugin provides a way to watermark resources. It allows you to modify a base resource to add a link to your site, a logo, etc.

The initial goal of this plugin was to be able to watermark images when they are hotlinked from a foreign website, but may also provide utilities to watermark other kinds of content in the future.

Usage

Watermarking images

You can use this plugin for many reasons, but one of them is to watermark resources protected using the hotlinking protection provided by Spincast. You redirect hotlinked images to a specific route handler that uses this plugin to generate watermarked versions of the base images.

The watermark this plugin creates can be based on some specified text or on an image you provide (a logo, for example).

Building a Watermarker instance

The first thing to do is to use the SpincastWatermarkerFactory factory to start the creation of a SpincastImageWatermarker instance:

@Inject
protected SpincastWatermarkerFactory spincastWatermarkerFactory;

SpincastImageWatermarker imgWatermarker = 
    spincastWatermarkerFactory.imageWatermarkerBuilder()
                              .text("My company name")
                              .position(SpincastWatermarkPosition.BOTTOM_RIGHT)
                              .build();

This watermarker would then be used to watermark images with a "My company name" text, at their bottom right.

Watermarking the images

Once you have created a SpincastImageWatermarker instance, you can watermark images using it:


imgWatermarker.watermark("/cat.jpg", true, new File(tempDirectory + "/cat-watermarked.jpg"));

In this example, a new "cat-watermarked.jpg" image would be created and would contain a "My company name" text watermark.

Options

By default, if you don't specify any options, the resulting watermarker will add text watermarks, at the bottom right of the base images, using the default system font and the color black. This text will be the base URL of your application ("https://www.example.com" for example.) The background will be white and a small black border will be added around the text.

Here are the options available when building a Watermarker using the SpincastWatermarkerFactory:

  • SpincastImageWatermarkerBuilder text(...)

    When calling one of the "text(...)" overloads, you create a watermarker that will add some text to the base images. This method allows you to specify:

    • The text itself.
    • The color to use for the text.
    • The font to use when writing the text.

  • SpincastImageWatermarkerBuilder backgroundColor(Color color)

    The color to use as the background for the watermark section. This option is only used when a text watermark is created, not when an image is used.

  • SpincastImageWatermarkerBuilder image(...)

    When calling one of the "image(...)" overloads, you create a watermarker that will be based on an image you provide (your logo, for example). This method requires the path to the image to use and allows you to specify if this image is on the classpath or on the file system.

  • SpincastImageWatermarkerBuilder position(SpincastWatermarkPosition position, int margin)

    The position of the watermark. It can be:

    • TOP_LEFT
    • TOP_CENTER
    • TOP_RIGHT
    • BOTTOM_LEFT
    • BOTTOM_CENTER
    • BOTTOM_RIGHT

    This option also allows you to specify a margin between the watermark and the edge of the base images.

  • SpincastImageWatermarkerBuilder widthPercent(...)

    The width of the watermark, relative to the width of the base image. It can be between 1 and 100.

    Defaults to 50 (50% width of the base image).

  • SpincastImageWatermarkerBuilder border(int widthInPixels, Color color)

    Allows you to add a border around the watermark. You can specify the width of the border (in pixels) and its color. Use 0 as the width for no border at all!

    Defaults to a 5 pixels black border.

  • SpincastImageWatermarkerBuilder opacity(...)

    Allows you to control the opacity of the watermark. It can go from "0.0F" (totally transparent) to "1.0F" (totally opaque).

Installation

1. Add this Maven artifact to your project:

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-watermarker</artifactId>
    <version>2.2.0</version>
</dependency>

2. Add an instance of the SpincastWatermarkerPlugin plugin to your Spincast Bootstrapper:


Spincast.configure()
        .plugin(new SpincastWatermarkerPlugin())
        // ...