How to Customize Watermark Font Size in ImageKit: CLI and Rust API Guide

You can customize the watermark font size in ImageKit by setting the --font-size CLI flag (default 24) or passing a u32 value to the add_watermark function in the Rust API.

ImageKit is a Rust-based image processing library that supports dynamic text watermarking with configurable font sizing. When you need to customize the watermark font size in ImageKit, you interact with the font_size parameter defined in the source code. This guide explains the exact implementation details found in the hzbd/imagekit repository, covering both command-line and programmatic interfaces.

Configuring Font Size via Command Line

The ImageKit CLI exposes the watermark font size through the --font-size argument. This flag accepts an integer value that sets the base point size for the rendered text.

According to the source code in src/cli.rs, the parameter defaults to 24 points when not specified. You can override this default by providing any positive integer value.

Controlling Size Programmatically in Rust

When using ImageKit as a library, the add_watermark function in src/processor.rs handles font sizing through its font_size: u32 parameter.

The function converts this integer into a Scale value that drives the glyph layout engine. This approach ensures type-safe sizing while maintaining compatibility with the underlying font rasterization libraries.

Auto-Scaling Protection for Large Text

ImageKit implements overflow protection to prevent watermarks from extending beyond image boundaries. If the requested font_size would cause text to overflow, the library automatically calculates a scale_factor and applies a reduced font size.

This safety mechanism in src/processor.rs ensures that watermarks remain fully visible regardless of the input dimensions, while still respecting your initial size preference as a maximum bound.

Code Examples

CLI Usage

Apply a 48-point watermark to a batch of images:

imagekit \
  --input-dir ./example/img-src \
  --output-dir ./example/img-out \
  --watermark-text "My Brand" \
  --font-size 48 \
  --watermark-position se

The --font-size 48 argument overrides the default 24-point size defined in src/cli.rs.

Rust API Integration

Set a custom 36-point watermark programmatically:

use imagekit::processor::add_watermark;
use imagekit::cli::{HexColor, WatermarkPosition};
use image::{DynamicImage, open};

let mut img = open("example/img-src/photo.jpg").unwrap();
let fonts: Vec<Font<'static>> = vec![/* load your .ttf/.otf fonts here */];

// Configure custom font size
let font_size = 36u32;

add_watermark(
    &mut img,
    "Custom Size",
    &fonts,
    font_size,
    WatermarkPosition::Se,
    HexColor(image::Rgba([255, 255, 255, 128])),
);

The font_size parameter controls the initial size before any auto-scaling logic applies.

Summary

• CLI customization: Use the --font-size flag (default 24) defined in src/cli.rs to set base watermark text size.
• API control: Pass a u32 value to the add_watermark function in src/processor.rs to specify font size programmatically.
• Overflow handling: ImageKit automatically scales down watermarks that would exceed image boundaries, calculating a scale_factor in src/processor.rs to ensure visibility.
• Type safety: The Rust API enforces unsigned 32-bit integers for font sizes, preventing invalid negative values.

Frequently Asked Questions

What is the default watermark font size in ImageKit?

The default font size is 24 points, as defined in the CLI argument structure in src/cli.rs. If you do not specify the --font-size flag when using the command-line interface, or if you pass 24 explicitly to the API, the watermark renders at this base size.

How does ImageKit prevent watermarks from overflowing the image?

The add_watermark function in src/processor.rs calculates a scale_factor when the requested text dimensions exceed the available image space. This automatic scaling reduces the effective font size to ensure the watermark remains fully visible within the image boundaries, applying the adjustment before final rasterization.

Can I use decimal values for font sizes in the ImageKit API?

No. The add_watermark function signature in src/processor.rs specifies font_size: u32, which requires an unsigned 32-bit integer. While the internal scaling calculations use floating-point arithmetic for the Scale type, the public API accepts only whole numbers for the initial size specification.

Where is the watermark font size parameter defined in the source code?

The font size parameter is defined in two primary locations: the --font-size CLI flag in src/cli.rs, and the add_watermark function signature in src/processor.rs. The CLI argument passes through to the processor, where it is converted into a Scale value for the text layout engine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}