imagekit2 0.1.5

A high-performance, Rust-powered image watermarking library. Supports text and logo watermarks, smart contrast, tiling, rotation, and precise positioning.

ImageKit2

ImageKit2 is a high-performance image watermarking engine built with Rust. It is designed for speed, memory safety, and professional typography rendering.

[!IMPORTANT] Migration Notice: This is the successor to the original imagekit, featuring a completely rewritten core for superior performance and modern text styling (shadows, alignment, smart contrast).

中文文档

✨ Why ImageKit2?

ImageKit2 is not just a wrapper around an image library; it is a purpose-built engine designed for high-quality watermarking tasks.

• 🚀 Blazing Fast & Memory Safe Built completely in Rust, ImageKit2 offers superior performance and memory safety compared to pure Python solutions (like Pillow), especially when processing large batches or high-resolution images.

• 🧠 Smart Contrast (Auto Color) Stop worrying about watermarks being invisible on dark or bright backgrounds. Use color="auto", and the engine will calculate the background luminance to automatically switch between black and white text.

• 🎨 Professional Typography Go beyond simple text drawing. ImageKit2 supports:

  • Drop Shadows for better readability.
  • Faux Bold (Stroke) to make thin fonts stand out.
  • Multi-line Alignment (Left/Center/Right).
  • Smart Padding to prevent text clipping.

• 🛡️ Production Ready

  • EXIF Correction: Automatically rotates images based on orientation tags.
  • Thread-Safe: Font loaders and processing pipelines are designed for concurrent environments (e.g., multi-threaded Python web servers).
  • Modern Formats: Full support for WebP, AVIF, JPEG, and PNG.

• 🧩 One Core, Three Interfaces Whether you need a Python SDK for your app, a CLI for your scripts, or a REST API Server for your microservices, ImageKit2 has you covered with a unified feature set.

---

Choose Your Usage Scenario

ImageKit2 adapts to your workflow. Whether you are building a Python app, running batch scripts, or deploying a microservice, pick the method that fits your needs.

Scenario 1: Python Application Integration

Best for: Data science pipelines, Django/FastAPI apps, in-memory processing.

Installation:

pip install imagekit2

Usage Example:

import imagekit2

# 1. Initialize (Point to your font files for best results)
# The library will search these paths/files for fonts.
wk = imagekit2.Watermarker(["/Library/Fonts/Arial.ttf", "./assets/fonts"])

# 2. Process
with open("input.jpg", "rb") as f:
    img_bytes = f.read()

processed_bytes = wk.process(
    img_bytes,
    text="Clean Watermark",
    position="br",
    padding=20,
    size=32.0,
    color="#FFFFFF",
    opacity=0.9,
    # Tip: Set stroke to 0 for crisp, modern text.
    stroke_width=0,
    # Add depth with shadows
    shadow_x=2,
    shadow_y=2,
    shadow_color="#00000080"
)

# 3. Save
with open("output.png", "wb") as f:
    f.write(processed_bytes)

Scenario 2: Local Batch Processing (CLI)

Best for: DevOps tasks, shell scripts, processing folders of images.

Installation:

1. Download the imagekit2 binary for your OS (Windows/Linux/macOS) from the GitHub Releases Page.
2. (Optional) Add it to your system PATH for global access.

Usage Example:

# Assuming the binary is in your current folder
./imagekit2 \
  --input "./input.jpg" \
  --output "./output.jpg" \
  --text "Copyright 2024" \
  --position "center" \
  --size 40 \
  --font "/Library/Fonts/Arial.ttf" \
  --color "#FFFFFF" \
  --shadow-x 2 \
  --shadow-y 2

Scenario 3: HTTP Microservice

Best for: Cloud deployment, decoupling image processing from main logic.

Installation & Start:

1. Download the imagekit2-server binary from the GitHub Releases Page.
2. Grant execution permissions (Linux/macOS): chmod +x imagekit2-server

Running the Server:

# Set font directory (Optional, defaults to ./assets/fonts)
export FONT_DIR="./assets/fonts"

# Start server (Listens on port 3000)
./imagekit2-server

API Contract:

• Endpoint: POST /process
• Content-Type: multipart/form-data
• Payload:
  • file: The image file.
  • params: JSON string (e.g., {"mode": "text", "text": "Hello", "size": 30}).

Example (cURL):

curl -X POST http://localhost:3000/process \
  -F "file=@input.jpg" \
  -F "params={\"mode\":\"text\",\"text\":\"API Test\",\"position\":\"br\",\"shadow_x\":2}" \
  --output result.jpg

---

Font Configuration (Recommended)

1. Default (Latin/English Support)

If your watermark text consists only of Latin characters (English, Numbers, Punctuation), you do not need to configure a font.

ImageKit2 embeds Inter Regular (Inter_24pt-Regular.ttf) by default—a high-quality, modern sans-serif font that looks professional out of the box.

2. Custom Fonts (Required for CJK / Styling)

You MUST provide a custom font file (.ttf / .otf) in the following cases:

• Non-Latin Characters: If your text contains Chinese, Japanese, Korean (CJK), or other non-Latin characters (the default Inter font does not contain these glyphs).
• Specific Styles: If you need a Bold, Italic, or Serif look (e.g., Roboto-Bold.ttf).

Where to get fonts?

• Google Fonts: A massive collection of free fonts.
  • Recommendations: Roboto, Open Sans, Montserrat, or Lato.
  • Tip: Download the Medium or Bold weights for better visibility on images.

How to load a custom font:

• Python: Watermarker(["/path/to/YourFont-Bold.ttf"])
• CLI: --font "/path/to/YourFont-Bold.ttf"
• Server: Place the file in the FONT_DIR folder.

---

Appendix: Parameter Reference

1. Common Parameters (Text & Logo)

Parameter	Default	Description
position	br	tl, tr, bl, br, center, tile, or manual coords.
padding	20	Distance from the edge (pixels).
opacity	0.8	0.0 to 1.0.
angle	0.0	Rotation angle in degrees.
resize_width	None	Resize input width before processing.
output_format	png	jpg, png, webp, etc.
quality	80	Compression quality (1-100).

2. Text Parameters

Parameter	Default	Description
text	-	The watermark content.
size	24.0	Font size in pixels.
color	#FFFFFF	Hex color. Use "auto" for smart contrast.
align	left	left, center, right.
stroke_width	0	Outline width. Keep 0 for clean modern style.
stroke_color	#000000	Outline color.
shadow_x	0	Horizontal shadow offset.
shadow_y	0	Vertical shadow offset.
shadow_color	#000000	Shadow color (supports alpha).

3. Logo Parameters

Parameter	Default	Description
logo	-	The source image path/bytes.
scale	None	Scale relative to background width (e.g., 0.1 = 10%).

---

Development & Contribution

We welcome contributions! Whether it's fixing bugs, adding features, or improving documentation, here's how to set up your environment.

1. Prerequisites

• Rust: Install via rustup.rs (Stable channel).
• Python: Version 3.8+ (Required for building bindings).
• Maturin: Required for compiling the Python extension (pip install maturin).

2. Build the Workspace

This project is organized as a Cargo workspace containing core, cli, server, and bindings/python.

# Clone the repository
git clone https://github.com/hzbd/imagekit2.git
cd imagekit2

# Build Core, CLI, and Server
cargo build --workspace

# Run tests (Core logic)
cargo test --workspace

3. Developing Python Bindings

To test changes in the Python SDK, you need to build the wheel locally using maturin.

# Navigate to the bindings directory (Optional, or run from root with -m)
# Recommended: Create a virtual environment first
python -m venv .venv
source .venv/bin/activate

# Build and install into the current environment
maturin develop -m bindings/python/Cargo.toml --release

4. Contribution Workflow

1. Fork the repository on GitHub.
2. Create a new Feature Branch (git checkout -b feature/amazing-feature).
3. Commit your changes.
4. Push to the branch and open a Pull Request.

---

License

This project is licensed under the MIT License.