How to Set Watermark Color Using Hex Codes in ImageKit

ImageKit accepts hex-encoded RGBA values via the --watermark_color CLI flag or the HexColor struct in Rust, supporting 6-digit RGB or 8-digit RGBA strings with an optional leading # and defaulting to 50% opacity when alpha is omitted.

ImageKit is a Rust-based image processing toolkit that allows you to overlay text watermarks with precise color control. Whether you are using the command-line interface or integrating the library into your Rust application, you can specify watermark colors using standard hex color codes. This guide explains how the hex parsing works and how to apply it based on the hzbd/imagekit source code.

Understanding the HexColor Implementation

The HexColor type in ImageKit is a thin wrapper around Rgba<u8> that provides safe parsing of hex strings. It is defined and implemented in src/cli.rs, where it serves as the bridge between user input and the internal color representation used during image processing.

Parsing Logic in src/cli.rs

The HexColor struct implements the FromStr trait to handle string-to-color conversion. According to the source code in src/cli.rs (lines 46-66), the parser performs the following steps:

1. Strips the optional # prefix from the input string.
2. Validates length: Accepts exactly 6 digits (RGB) or 8 digits (RGBA).
3. Converts hex pairs to u8 values for each channel.
4. Defaults alpha to 128 (approximately 50% opacity) when only 6 digits are provided.

If the input fails these checks, the parser returns a ParseColorError defined in src/errors.rs.

Setting Watermark Color via CLI

When using the ImageKit binary, pass your hex color to the --watermark_color flag. The default value defined in src/cli.rs (lines 33-35) is #ffffff80, which renders white text at 50% opacity.

# Red watermark, fully opaque (alpha = ff)

imagekit -i ./photos -o ./output \
    --watermark_text "My Brand" \
    --watermark_color "#ff0000ff"

# Semi-transparent blue watermark (alpha = 80 ≈ 50%)

imagekit -i ./photos -o ./output \
    --watermark_text "My Brand" \
    --watermark_color "#0000ff80"

# Green without alpha defaults to 50% opacity

imagekit -i ./photos -o ./output \
    --watermark_text "My Brand" \
    --watermark_color "00ff00"

Using HexColor in Rust Programs

For library consumers, HexColor provides a type-safe way to transport color data from configuration to the processing engine.

Parsing from Strings

You can construct a HexColor by parsing a string slice. This leverages the same FromStr implementation used by the CLI:

use imagekit::cli::HexColor;

// Parse 8-digit RGBA
let color: HexColor = "#00ff00c0".parse().unwrap(); // green, 75% opacity

// Parse 6-digit RGB (alpha defaults to 128)
let color2: HexColor = "ff0000".parse().unwrap(); // red, 50% opacity

Direct Construction

If you already have byte values, construct the struct directly without parsing:

use imagekit::cli::HexColor;
use image::Rgba;

// Orange with ~78% opacity
let color = HexColor(Rgba([255, 165, 0, 200]));

How the Color is Applied to the Image

The add_watermark function in src/processor.rs (lines 36-84) receives the HexColor value and extracts the raw Rgba<u8> tuple via let watermark_color = color.0;. During the rasterization loop, this color is blended onto each target pixel according to the glyph's coverage value (v), ensuring the watermark respects the specified alpha channel.

Summary

• Hex format: ImageKit accepts #RRGGBB or #RRGGBBAA (with or without the # prefix) through the HexColor parser in src/cli.rs.
• Default alpha: Omitting the alpha channel defaults to 128 (50% opacity), while the CLI flag itself defaults to #ffffff80 (white, 50% opacity).
• Programmatic usage: Use "#hex".parse::<HexColor>() in Rust or construct HexColor(Rgba([r, g, b, a])) directly.
• Application: The add_watermark function in src/processor.rs uses the parsed color to blend text onto images.

Frequently Asked Questions

What hex format does ImageKit expect for watermark colors?

ImageKit expects either 6-digit RGB (e.g., #ff0000) or 8-digit RGBA (e.g., #ff000080) hex strings. The leading # is optional. This parsing logic is implemented in the FromStr trait for HexColor located in src/cli.rs.

What happens if I don't specify an alpha value in the hex code?

If you provide only 6 digits (RGB), the parser automatically sets the alpha channel to 128 (decimal), which is approximately 50% opacity. This ensures watermarks are semi-transparent by default unless you explicitly define full opacity with an ff alpha byte.

How do I set a watermark color programmatically in Rust?

Import imagekit::cli::HexColor and parse a string using .parse(), or construct it directly with HexColor(Rgba([r, g, b, a])). Pass the resulting value to add_watermark along with your image buffer and font configuration.

Where is the watermark color blending logic implemented?

The blending occurs in src/processor.rs within the add_watermark function (lines 36-84). The function extracts the Rgba<u8> from the HexColor struct and composites the watermark text onto the image pixels using the specified alpha value.

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