Metadata-Version: 2.4
Name: comfyui-overlaysuite
Version: 0.4.0
Summary: Professional text overlays, image watermarks, tiled proofing stamps, and 3D LUT color grading for ComfyUI.
License-Expression: MIT
Project-URL: Repository, https://gitlab.com/Cpt.Jack/ComfyUI-OverlaySuite
Keywords: comfyui,watermark,text-overlay,compositing,custom-nodes
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: Pillow>=9.5.0
Dynamic: license-file

# ComfyUI-OverlaySuite

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Version: 0.4.0](https://img.shields.io/badge/Version-0.4.0-teal.svg)](CHANGELOG.md)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-brightgreen.svg)](https://www.python.org/)
[![ComfyUI](https://img.shields.io/badge/ComfyUI-Custom--Node-purple.svg)](https://github.com/comfyanonymous/ComfyUI)

A modular, high-performance custom node pack for **[ComfyUI](https://github.com/comfyanonymous/ComfyUI)** dedicated to professional text overlays, dynamic image watermarking, logo placement, batch rendering, and visual compositing.

---

## Features

- 🖋️ **Advanced Text Typography**: Multiline text rendering, custom & system font loader, font size, color parsing (HEX, RGB, RGBA), letter outline/stroke, gaussian drop shadows, and rounded background bounding boxes/pills.
- 🖼️ **Image & Logo Watermarking**: Flexible logo placement with intelligent scaling (fit, fill, percentage of base image, aspect-ratio preserved), monochrome/duotone tinting, and opacity control.
- 🎨 **Photoshop-Grade Blend Modes**: High-precision float32 blending math including `Normal`, `Multiply`, `Screen`, `Overlay`, `Soft Light`, `Hard Light`, `Difference`, `Additive / Linear Dodge`, and `Color Burn`.
- 📐 **Intuitive 9-Point Positioning System**: Anchor presets (`top-left`, `center`, `bottom-right`, etc.), combined with normalized percentage ratios `[0.0, 1.0]` or absolute pixel offsets & margins.
- 🔒 **Tiled Security Watermarking**: Diagonal repeating grid patterns and staggered brick layouts for copyright proofing, stock photography stamps, and draft watermarks.
- ⚡ **Batch Broadcasting Support**: Automatically matches mismatched batch sizes (e.g., overlay a single logo across a batch of 8 generated images seamlessly).
- 🏷️ **Dynamic Text Tags**: `{date}`, `{index}`, `{width}`, and custom `{seed}`/`{prompt}` placeholders resolved per image in the batch.
- 🧩 **Alpha Mask Outputs**: Every node provides a dedicated `MASK` output socket representing the composited elements for downstream inpainting, grading, or conditioning.

![Before, text overlay, image watermark, and tiled watermark](assets/demo/comparison.png)

*Top-left: original · top-right: Text Overlay · bottom-left: Image Watermark · bottom-right: Tiled Watermark. Regenerate with `python scripts/generate_assets.py`.*

---

## Table of Contents

1. [Installation](#installation)
2. [Included Nodes](#included-nodes)
   - [Text Overlay](#1-text-overlay-overlaysuite_textoverlay)
   - [Image Watermark](#2-image-watermark-overlaysuite_imagewatermark)
   - [Tiled Watermark](#3-tiled-watermark-overlaysuite_tiledwatermark)
   - [Color Grading & LUT](#4-color-grading--lut-overlaysuite_colorgrading)
3. [Positioning & Anchor Coordinates](#positioning--anchor-coordinates)
4. [Blend Modes Reference](#blend-modes-reference)
5. [Font Management & Custom Fonts](#font-management--custom-fonts)
6. [Batch Processing & Broadcasting](#batch-processing--broadcasting)
7. [Detailed Documentation](#detailed-documentation)
8. [Roadmap & Changelog](#roadmap--changelog)
9. [License](#license)

---

## Installation

### Method 1: ComfyUI Manager *(once published to the registry)*
1. Open ComfyUI.
2. Launch the **ComfyUI Manager**.
3. Search for `ComfyUI-OverlaySuite`.
4. Click **Install** and restart ComfyUI.

### Method 2: Git Clone
Clone the repository directly into your ComfyUI `custom_nodes` folder:

```bash
cd ComfyUI/custom_nodes/
git clone https://gitlab.com/Cpt.Jack/ComfyUI-OverlaySuite.git
cd ComfyUI-OverlaySuite
pip install -r requirements.txt
```

Restart your ComfyUI server.

---

## Included Nodes

### 1. Text Overlay (`OverlaySuite_TextOverlay`)
*Category: `OverlaySuite/Text`*

Renders antialiased multiline text with complete typographical control, optional background boxes, stroke outlines, and soft drop shadows.

```text
               +-----------------------------+
   IMAGE ----> |                             | ----> IMAGE (Composited)
  (Optional)   |  Text Overlay               | ----> MASK  (Text Alpha)
   MASK -----> |  (OverlaySuite)             |
               +-----------------------------+
```

#### Inputs
| Pin / Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `image` | `IMAGE` | *Required* | Base input image batch (`[B, H, W, 3]`). |
| `text` | `STRING` | `"Watermark"` | Text content to render (multiline supported). |
| `font_name` | `COMBO` | `"Roboto-Regular"` | Discovered font (bundled `fonts/` first, then OS fonts), shown by readable name with a live preview in the dropdown. |
| `font_size` | `INT` | `48` | Font size in points/pixels (range: 4 to 2048). |
| `font_color` | `STRING` | `"#FFFFFF"` | Font color in HEX (`#RRGGBB` or `#RRGGBBAA`) or RGB notation. |
| `opacity` | `FLOAT` | `1.0` | Global opacity multiplier (`0.0` to `1.0`). |
| `alignment` | `COMBO` | `"left"` | Alignment for multiline text (`left`, `center`, `right`). |
| `line_spacing` | `INT` | `4` | Extra vertical spacing between lines in pixels. |
| `position_mode` | `COMBO` | `"Anchor Preset"` | Coordinate mode: `Anchor Preset`, `Normalized (0-1)`, or `Absolute Pixels`. |
| `anchor` | `COMBO` | `"bottom-right"` | 9-point anchor preset (`top-left`, `center`, `bottom-right`, etc.). |
| `offset_x` | `FLOAT` | `20.0` | Horizontal displacement from anchor point (pixels or normalized ratio). |
| `offset_y` | `FLOAT` | `20.0` | Vertical displacement from anchor point (pixels or normalized ratio). |
| `rotation` | `FLOAT` | `0.0` | Rotation angle in degrees (`-360.0` to `360.0`). |
| `stroke_width` | `INT` | `0` | Outer text border thickness (`0` to `100`). |
| `stroke_color` | `STRING` | `"#000000"` | Stroke outline color (HEX or RGB notation). |
| `shadow_offset_x` | `INT` | `0` | Horizontal shadow displacement in pixels. |
| `shadow_offset_y` | `INT` | `0` | Vertical shadow displacement in pixels. |
| `shadow_blur` | `INT` | `0` | Shadow blur radius in pixels. |
| `shadow_color` | `STRING` | `"#000000"` | Shadow color. |
| `shadow_opacity`| `FLOAT` | `0.5` | Shadow opacity multiplier (`0.0` to `1.0`). |
| `box_enabled` | `BOOLEAN` | `False` | Render a background pill or bounding box behind the text. |
| `box_color` | `STRING` | `"#000000"` | Background box fill color. |
| `box_opacity` | `FLOAT` | `0.6` | Background box opacity (`0.0` to `1.0`). |
| `box_padding` | `INT` | `12` | Padding around text in pixels. |
| `box_corner_radius` | `INT` | `8` | Corner rounding radius for pill/card effect. |
| `template_vars` | `STRING` | `""` | *Optional.* `key=value` lines defining custom `{tags}` (e.g. `seed=1234`). Built-ins: `{date}`, `{time}`, `{index}`, `{batch}`, `{width}`, `{height}`. See [Template Tags](docs/NODES.md#template-tags). |

---

### 2. Image Watermark (`OverlaySuite_ImageWatermark`)
*Category: `OverlaySuite/Watermark`*

Overlays a logo, graphic, or secondary image onto a base image with full control over scaling, aspect ratios, blend modes, anchor positions, and color tinting.

#### Inputs
| Pin / Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `base_image` | `IMAGE` | *Required* | Base image batch onto which the watermark is placed. |
| `watermark_image` | `IMAGE` | *Required* | Watermark or logo image batch. |
| `mask` | `MASK` | *Optional* | Optional custom alpha mask for the watermark. |
| `blend_mode` | `COMBO` | `"normal"` | Blending formula (`normal`, `multiply`, `screen`, `overlay`, `soft_light`, `hard_light`, `difference`, `additive`, `color_burn`). |
| `scale_mode` | `COMBO` | `"scale_by_width_percentage"` | Resizing strategy (`scale_by_width_percentage`, `scale_by_height_percentage`, `scale_by_factor`, `fit_within_box`, `stretch`, `original_size`). |
| `scale_factor` | `FLOAT` | `0.20` | Scale multiplier (e.g., `0.20` = 20% of base image dimension). |
| `keep_aspect_ratio`| `BOOLEAN` | `True` | Prevents non-uniform distortion during scaling. |
| `opacity` | `FLOAT` | `1.0` | Watermark transparency level (`0.0` to `1.0`). |
| `position_mode` | `COMBO` | `"Anchor Preset"` | Coordinate mode (`Anchor Preset`, `Normalized (0-1)`, `Absolute Pixels`). |
| `anchor` | `COMBO` | `"bottom-right"` | Reference anchor point on the canvas. |
| `margin_x` | `FLOAT` | `24.0` | Margin distance from left/right canvas boundary. |
| `margin_y` | `FLOAT` | `24.0` | Margin distance from top/bottom canvas boundary. |
| `rotation` | `FLOAT` | `0.0` | Rotation angle in degrees (`-360.0` to `360.0`). |
| `tint_color` | `STRING` | `""` | Optional HEX color code to recolor monochrome logos (e.g. `"#FFD700"`). Leave empty for original colors. |

---

### 3. Tiled Watermark (`OverlaySuite_TiledWatermark`)
*Category: `OverlaySuite/Tiling`*

Generates a continuous repeating grid pattern of logos or text diagonally across the canvas, ideal for stock photo previews, security markings, and client draft approvals.

#### Inputs
| Pin / Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `image` | `IMAGE` | *Required* | Base input image batch. |
| `watermark_image` | `IMAGE` | *Optional* | Image logo to repeat (leave empty if using text). |
| `text` | `STRING` | `""` | Text string to tile if no watermark image is connected. |
| `font_name` / `font_color` | `COMBO` / `STRING` | first font / `"#FFFFFF"` | Font and color when tiling text. |
| `font_size` | `INT` | `36` | Text size when tiling text. |
| `tile_scale` | `FLOAT` | `0.15` | Logo tile width as a fraction of the base image width (image tiling). |
| `template_vars` | `STRING` | `""` | Optional `key=value` lines defining custom `{tags}` for the text. |
| `rotation` | `FLOAT` | `-30.0` | Diagonal tiling angle in degrees. |
| `spacing_x` | `INT` | `180` | Horizontal gap between repeated tiles in pixels. |
| `spacing_y` | `INT` | `120` | Vertical gap between repeated tile rows in pixels. |
| `stagger_rows` | `BOOLEAN` | `True` | Staggers alternating rows by half-width (brick layout). |
| `opacity` | `FLOAT` | `0.15` | Subtle proofing opacity (`0.0` to `1.0`). |
| `blend_mode` | `COMBO` | `"overlay"` | Blending formula for the pattern. |

---

### 4. Color Grading & LUT (`OverlaySuite_ColorGrading`)
*Category: `OverlaySuite/Color`*

Applies hardware-accelerated 3D Look-Up Tables (`.cube` files, HaldCLUT images) and photographic adjustments (exposure, contrast, saturation, white balance temperature & tint, vignette) with selective alpha masking.

#### Inputs
| Pin / Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `image` | `IMAGE` | *Required* | Base input image batch (`[B, H, W, 3]`). |
| `lut_name` | `COMBO` | `"None"` | Discovered 3D LUT preset from `luts/` directory (`cinematic_teal_orange`, `film_warm_vintage`, `moody_cyberpunk`, `bw_high_contrast`, `bleach_bypass`, or custom `.cube`). |
| `strength` | `FLOAT` | `1.0` | Master grading effect strength (`0.0` to `1.0`). |
| `exposure` | `FLOAT` | `0.0` | Exposure adjustment in f-stops (`-4.0` to `+4.0`). |
| `contrast` | `FLOAT` | `1.0` | Photographic contrast multiplier (`0.0` to `3.0`, `1.0` is neutral). |
| `saturation` | `FLOAT` | `1.0` | Color saturation multiplier based on Rec.709 luma (`0.0` to `3.0`). |
| `temperature`| `FLOAT` | `0.0` | White balance temperature (`-100.0` cool/blue to `+100.0` warm/amber). |
| `tint` | `FLOAT` | `0.0` | White balance tint (`-100.0` green to `+100.0` magenta). |
| `vignette_intensity`| `FLOAT`| `0.0`| Radial edge darkening intensity (`0.0` to `1.0`). |
| `vignette_roundness`| `FLOAT`| `1.0`| Radial aspect ratio for the vignette falloff (`0.2` to `2.0`). |
| `mask` | `MASK` | *Optional* | Optional mask to apply the color grade selectively to specific areas. |
| `hald_clut` | `IMAGE` | *Optional* | Optional 2D HaldCLUT image to use as a custom 3D LUT. |

#### Outputs
- `image` (`IMAGE`): Graded composite result.
- `mask` (`MASK`): Effective opacity mask of the applied color grade.

---

## Positioning & Anchor Coordinates

OverlaySuite supports 3 positioning modes to accommodate static pixel requirements as well as variable-aspect generation workflows:

```text
 top-left (0,0) ----------- top-center ----------- top-right (W,0)
       |                                                 |
       |                                                 |
  center-left                   center              center-right
       |                                                 |
       |                                                 |
bottom-left (0,H) -------- bottom-center -------- bottom-right (W,H)
```

1. **`Anchor Preset`**: Automatically docks the overlay to one of the 9 anchor points, applying `margin_x` and `margin_y` inward from the image boundaries.
2. **`Normalized (0-1)`**: Offsets are specified as ratios of the base image dimensions (`0.5, 0.5` is the exact geometric center regardless of image resolution).
3. **`Absolute Pixels`**: Exact pixel coordinates for pixel-perfect placement.

---

## Blend Modes Reference

All blend operations are computed in normalized high-precision float32 color space:

- **Normal**: Standard alpha compositing:
  $$C = C_{src} \cdot \alpha + C_{dst} \cdot (1 - \alpha)$$
- **Multiply**: Multiplies base and overlay pixel values. Perfect for dark logos or dark signatures on light backgrounds:
  $$C = C_{dst} \cdot C_{src}$$
- **Screen**: Inverts, multiplies, and inverts. Ideal for light logos on dark imagery:
  $$C = 1 - (1 - C_{dst}) \cdot (1 - C_{src})$$
- **Overlay**: Combines Multiply and Screen based on base image luminance. Adds contrast:
  $$C = \begin{cases} 2 \cdot C_{dst} \cdot C_{src} & \text{if } C_{dst} < 0.5 \\ 1 - 2 \cdot (1 - C_{dst}) \cdot (1 - C_{src}) & \text{otherwise} \end{cases}$$
- **Soft Light**: Gentler variation of Overlay; produces subtle contrast enhancement.
- **Additive / Linear Dodge**: Direct sum of channel values clamped to 1.0. Excellent for glowing watermarks and neon logos.
- **Difference**: Highlights dissimilarities between images, useful for alignment verification.

---

## Font Management & Custom Fonts

OverlaySuite automatically discovers fonts from two sources:
1. **Bundled Fonts**: Any `.ttf`, `.otf`, or `.ttc` file placed in the `ComfyUI-OverlaySuite/fonts/` directory is discovered and listed first in the `font_name` dropdown. Roboto Regular ships by default.
2. **Operating System Fonts**: Automatically searches standard system directories:
   - **Windows**: `C:\Windows\Fonts`, `%LOCALAPPDATA%\Microsoft\Windows\Fonts`
   - **macOS**: `/Library/Fonts`, `/System/Library/Fonts`, `~/Library/Fonts`
   - **Linux**: `/usr/share/fonts`, `/usr/local/share/fonts`, `~/.fonts`, `~/.local/share/fonts`

**Readable names**: fonts are listed by their embedded family and style, e.g. `Roboto-Regular`, `Arial-Narrow-Bold-Italic`, instead of file names like `ARIALNB`. Each face of a `.ttc` collection is listed separately. Workflows saved with the old file-name values (`ARIALNB`, `arialnb.ttf`) still resolve, and lookup ignores case, spaces, hyphens and underscores.

**Category separation**: fonts are automatically organized into typographic categories:
- ⭐ **Bundled**: Default and custom project fonts located in `fonts/`.
- 🔤 **Sans-Serif**: Arial, Bahnschrift, Calibri, Segoe UI, Tahoma, Trebuchet, Verdana, etc.
- 📜 **Serif**: Book Antiqua, Bodoni, Cambria, Georgia, Times New Roman, etc.
- 💻 **Monospace**: Cascadia Mono, Consolas, Courier New, Lucida Console, etc.
- ✍️ **Script**: Bradley Hand, Brush Script, Freestyle Script, Ink Free, Segoe Script, etc.
- 🎨 **Display**: Comic Sans, Gabriola, Impact, etc.

**Photoshop-style dropdown**: opening the `font_name` dropdown on the Text Overlay and Tiled Watermark nodes features:
- **Category Filter Pills**: Interactive buttons at the top (`All`, `⭐ Bundled`, `Sans-Serif`, `Serif`, `Monospace`, `Script`, `Display`) to instantly filter the list.
- **Search Bar**: Real-time font search filtering with key-event isolation so ComfyUI hotkeys aren't triggered.
- **Category Headers & Badges**: Distinct visual section headers dividing each category with font count tallies, plus category badge pills next to each font name.
- **Font Previews**: Live rendered samples of each font (loaded lazily as you scroll) served via `/overlaysuite/font_preview`. If the frontend extension doesn't load, the dropdown still works as a structured category-grouped plain list.

> [!TIP]
> If a requested font is missing or cannot be loaded, OverlaySuite automatically falls back to the bundled Roboto Regular without crashing the workflow.

---

## Batch Processing & Broadcasting

OverlaySuite natively handles ComfyUI batching:
- **1 Watermark $\to$ $N$ Base Images**: If you generate a batch of 4 or 8 images and feed a single watermark image, the watermark is automatically broadcast across every frame.
- **$N$ Watermarks $\to$ $N$ Base Images**: Pairs each watermark frame with the corresponding base image.
- **Mismatch Protection**: If batch sizes do not match (e.g. 2 watermarks with 4 base images), the suite safely processes up to the available frames and issues an informative console log.

---

## Detailed Documentation

For in-depth references, please explore:
- [Node API Reference](docs/NODES.md): Exhaustive parameter and socket specification.
- [Blend Modes & Compositing Math](docs/BLEND_MODES.md): Mathematical formulations and alpha blending rules.
- [Workflow Blueprints](docs/WORKFLOWS.md): Step-by-step connection guides for common workflows.
- [`assets/workflows/`](assets/workflows/): Importable ComfyUI API-format example workflows.

---

## Development

All tests run offline: no ComfyUI server is needed, and `torch`, `numpy`, and `Pillow` are the only requirements.

```bash
python -m unittest discover tests                                       # unit + node tests
python .agents/skills/comfyui-overlay-dev/scripts/validate_nodes.py     # node contract check
python scripts/generate_assets.py                                       # rebuild assets/workflows and assets/demo
python scripts/build.py --clean                                         # full validation, test & dist build
```

The repo root is loaded as a package (as ComfyUI does it), so code inside the pack uses **relative imports**. Absolute `import utils` / `import nodes` would collide with ComfyUI's own modules.

---

## Roadmap & Changelog

- Check [TODO.md](TODO.md) for the active development roadmap, implementation phases, and QA checklist.
- Check [CHANGELOG.md](CHANGELOG.md) for version release notes, breaking changes, and migration guides.

---

## License

This project is licensed under the [MIT License](LICENSE).

