Sirv Image Transformation - Java

A fluent Java library for building Sirv image transformation URLs using the builder pattern with method chaining.

Requirements

• Java 11 or higher
• Maven 3.6+

Installation

Maven

<dependency>
    <groupId>com.sirv</groupId>
    <artifactId>sirv-image</artifactId>
    <version>1.0.0</version>
</dependency>

Build from source

cd java
mvn clean install

Quick Start

import com.sirv.SirvImage;

// Create from full URL
String url = new SirvImage("https://demo.sirv.com/image.jpg")
    .width(300)
    .height(200)
    .format("webp")
    .quality(80)
    .toUrl();
// https://demo.sirv.com/image.jpg?w=300&h=200&format=webp&q=80

// Create from base URL + path
String url = new SirvImage("https://demo.sirv.com", "/image.jpg")
    .resize(400, 300, "fill")
    .toUrl();
// https://demo.sirv.com/image.jpg?w=400&h=300&scale.option=fill

API Reference

Constructors

Constructor	Description
new SirvImage(String fullUrl)	Create from a complete image URL
new SirvImage(String baseUrl, String path)	Create from base URL and image path

Resize

Method	Description
resize(int width, int height, String option)	Set width, height, and fit option ("fill", "contain", "cover", "force")
width(int w)	Set the resize width
height(int h)	Set the resize height
scaleByLongest(int s)	Scale so the longest side matches the value
thumbnail(int size)	Generate a thumbnail

new SirvImage(url).resize(400, 300, "fill").toUrl();
new SirvImage(url).width(300).toUrl();
new SirvImage(url).scaleByLongest(500).toUrl();
new SirvImage(url).thumbnail(150).toUrl();

Crop

Method	Description
crop(int w, int h, int x, int y, String type, int padW, int padH)	Crop with full control
clipPath(String name)	Apply a clip path

// Simple crop
new SirvImage(url).crop(200, 200, 50, 50, null, 0, 0).toUrl();

// Face crop with padding
new SirvImage(url).crop(300, 300, 0, 0, "face", 10, 10).toUrl();

// Clip path
new SirvImage(url).clipPath("mypath").toUrl();

Rotation

Method	Description
rotate(double degrees)	Rotate by degrees (0-360)
flip()	Flip vertically
flop()	Flop horizontally

new SirvImage(url).rotate(90).flip().toUrl();

Format

Method	Description
format(String fmt)	Set output format ("jpg", "png", "webp", "avif")
quality(int q)	Set quality (1-100)
webpFallback(String fmt)	Set fallback format for non-WebP browsers
subsampling(String v)	Set chroma subsampling ("420", "422", "444")
pngOptimize(boolean enabled)	Enable/disable PNG optimization
gifLossy(int level)	Set GIF lossy compression level (0-200)

new SirvImage(url).format("webp").quality(85).toUrl();
new SirvImage(url).format("webp").webpFallback("jpg").toUrl();
new SirvImage(url).pngOptimize(true).toUrl();

Color Adjustments

Method	Description
brightness(int v)	Adjust brightness (-100 to 100)
contrast(int v)	Adjust contrast (-100 to 100)
exposure(int v)	Adjust exposure (-100 to 100)
hue(int v)	Adjust hue (-360 to 360)
saturation(int v)	Adjust saturation (-100 to 100)
lightness(int v)	Adjust lightness (-100 to 100)
shadows(int v)	Adjust shadows (-100 to 100)
highlights(int v)	Adjust highlights (-100 to 100)
grayscale()	Convert to grayscale
colorLevel(int black, int white)	Set black/white color levels (0-255)
histogram(String channel)	Generate histogram ("r", "g", "b", "rgb", "luminance")

new SirvImage(url).brightness(15).contrast(10).saturation(20).toUrl();
new SirvImage(url).grayscale().toUrl();
new SirvImage(url).colorLevel(10, 245).toUrl();

Color Effects

Method	Description
colorize(String color, int opacity)	Apply a color tint
colortone(String preset)	Apply a preset colortone (e.g. "sepia")
colortone(String color, int level, String mode)	Apply a custom colortone

new SirvImage(url).colorize("ff6600", 40).toUrl();
new SirvImage(url).colortone("sepia").toUrl();
new SirvImage(url).colortone("ff6600", 50, "solid").toUrl();

Effects

Method	Description
blur(int v)	Apply Gaussian blur (0-100)
sharpen(int v)	Apply sharpening (0-100)
vignette(int value, String color)	Apply vignette effect
opacity(int v)	Set image opacity (0-100)

new SirvImage(url).blur(5).sharpen(10).toUrl();
new SirvImage(url).vignette(40, "000000").toUrl();

Text Overlay

Add text overlays using TextOptions for styling. Multiple text layers are supported.

// Single text layer
SirvImage.TextOptions opts = new SirvImage.TextOptions()
    .fontSize(32)
    .fontFamily("Arial")
    .fontStyle("italic")
    .fontWeight("bold")
    .color("ffffff")
    .opacity(80)
    .position("south")
    .backgroundColor("000000")
    .backgroundOpacity(50)
    .outlineWidth(2)
    .outlineColor("333333")
    .offsetX(10)
    .offsetY(20);

new SirvImage(url).text("Hello World", opts).toUrl();

// Multiple text layers (automatically indexed)
new SirvImage(url)
    .text("Title", new SirvImage.TextOptions().fontSize(48).position("north"))
    .text("Subtitle", new SirvImage.TextOptions().fontSize(24).position("south"))
    .toUrl();

TextOptions Methods

Method	Description
fontSize(int size)	Font size in pixels
fontFamily(String family)	Font family name
fontStyle(String style)	Font style (e.g. "italic")
fontWeight(String weight)	Font weight (e.g. "bold")
color(String color)	Text color (hex)
opacity(int opacity)	Text opacity (0-100)
position(String position)	Position on image
backgroundColor(String color)	Background color (hex)
backgroundOpacity(int opacity)	Background opacity (0-100)
outlineWidth(int width)	Outline width in pixels
outlineColor(String color)	Outline color (hex)
offsetX(int x)	Horizontal offset
offsetY(int y)	Vertical offset

Watermark

Add watermark overlays with positioning and styling. Multiple watermarks are supported.

// Single watermark
SirvImage.WatermarkOptions opts = new SirvImage.WatermarkOptions()
    .position("southeast")
    .opacity(60)
    .scale(20)
    .offsetX(10)
    .offsetY(10);

new SirvImage(url).watermark("/logo.png", opts).toUrl();

// Multiple watermarks (automatically indexed)
new SirvImage(url)
    .watermark("/logo1.png", new SirvImage.WatermarkOptions().position("northeast"))
    .watermark("/logo2.png", new SirvImage.WatermarkOptions().position("southwest"))
    .toUrl();

WatermarkOptions Methods

Method	Description
position(String position)	Watermark position
opacity(int opacity)	Opacity (0-100)
scale(int scale)	Scale percentage (1-100)
offsetX(int x)	Horizontal offset
offsetY(int y)	Vertical offset

Canvas

Extend the image with a canvas background.

SirvImage.CanvasOptions opts = new SirvImage.CanvasOptions()
    .width(800)
    .height(600)
    .color("f5f5f5")
    .position("center")
    .borderWidth(2)
    .borderColor("000000");

new SirvImage(url).width(400).canvas(opts).toUrl();

CanvasOptions Methods

Method	Description
width(int w)	Canvas width
height(int h)	Canvas height
color(String color)	Background color (hex)
position(String position)	Image position within canvas
borderWidth(int width)	Border width in pixels
borderColor(String color)	Border color (hex)

Frame

Add a decorative frame around the image.

SirvImage.FrameOptions opts = new SirvImage.FrameOptions()
    .style("solid")
    .width(10)
    .color("333333")
    .rimColor("cccccc")
    .rimWidth(2);

new SirvImage(url).frame(opts).toUrl();

FrameOptions Methods

Method	Description
style(String style)	Frame style ("solid", "raised", "sunken")
width(int width)	Frame width in pixels
color(String color)	Frame color (hex)
rimColor(String color)	Rim color (hex)
rimWidth(int width)	Rim width in pixels

Other

Method	Description
page(int num)	Select page from multi-page documents (PDF, TIFF)
profile(String name)	Apply a named Sirv profile

new SirvImage("https://demo.sirv.com/doc.pdf").page(3).width(800).format("jpg").toUrl();
new SirvImage(url).profile("my-profile").toUrl();

URL Output

Method	Description
toUrl()	Returns the full transformation URL as a String
toString()	Same as toUrl()

Running Tests

mvn test

License

See the Sirv Terms of Service for usage terms.