Interactive Icon

Turn any character image into a polished avatar icon with shaped frames and gradient backgrounds. Interactive Icon automatically detects the character's head position, frames it perfectly, and composites it onto a portal-shaped background with SVG masking.

Features

• Auto-framing -- automatically positions and scales characters based on head bounding box detection
• SVG masking -- crisp portal and clipping shapes at any resolution via CairoSVG
• Gradient fills -- built-in presets (orange, blue, green, purple, red) or custom hex colors
• Image fills -- use any image as the portal background
• Batch processing -- CLI generates multiple gradient variants in one run
• Web UI -- Gradio interface with live preview and full parameter control
• Sub-pixel rendering -- 2x internal rendering for precise mask alignment

Demo

Screenshots and demo videos coming soon. To see it in action, follow the Setup instructions below.

Setup

Requires Python 3.8+.

# Clone the repo
git clone https://github.com/davidmarchenko/interactive-icon.git
cd interactive-icon

# Option A: Use the helper scripts (auto-creates venv)
./run.sh character.png output.png

# Option B: Manual setup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install cairosvg gradio  # optional: SVG support + web UI

Dependencies

Package	Purpose	Required
Pillow	Image processing	Yes
requests	URL image fetching	Yes
cairosvg	CairoSVG (a library for converting SVG files to raster images)	Recommended
gradio	Gradio (a Python library for building quick web UIs)	Optional

Usage

Command Line

# Basic usage -- generates avatar with orange gradient + blue/green/purple variants
./run.sh character.png output.png

# Custom image fill
./run.sh character.png output.png --fill background.png

# Higher resolution (2x)
./run.sh character.png output.png --scale 2.0

Web UI

./run_ui.sh
# Opens at http://localhost:7860

The web UI lets you:

• Upload a character image (transparent PNG recommended)
• Switch between gradient and image fill
• Pick gradient colors with color pickers
• Adjust character scale, rotation, and position
• Tune mask and portal offsets
• Set output scale (0.5x to 4x)
• See live preview as you change any setting

Python API

from avatar_compositor import composite_avatar, compute_auto_config, PortalGradient
from PIL import Image

# Simple usage with built-in gradient
avatar = composite_avatar("character.png", PortalGradient.orange())
avatar.save("avatar.png")

# Auto-framing with head bounding box
img = Image.open("character.png")
head_bbox = [407, 105, 686, 510]  # [x1, y1, x2, y2] from a vision model
config = compute_auto_config(img.size, head_bbox)
avatar = composite_avatar("character.png", PortalGradient.blue(), config=config)
avatar.save("avatar_auto.png")

# Custom gradient
custom = PortalGradient(start_color="#FF0000", end_color="#0000FF")
avatar = composite_avatar("character.png", custom)

# Image fill (local file or URL)
avatar = composite_avatar("character.png", "landscape.png")

How It Works

The compositing pipeline has five stages:

1. Portal layer -- renders the portal SVG shape and fills it with a gradient or image
2. Character layer -- loads the character image, scales it to fit, and applies rotation
3. Mask clipping -- renders the mask SVG shape and multiplies it with the character's alpha channel to clip the character to the portal boundary
4. Compositing -- layers the masked character over the portal on a transparent canvas
5. Downscale -- if sub-pixel offsets were used, the 2x internal render is downscaled to the target resolution with Lanczos filtering

Auto-Framing Algorithm

When a head bounding box is provided, compute_auto_config() calculates optimal framing:

1. Defines a "frame region" from the top of the head to the shoulders (head bottom + configurable extension)
2. Computes a scale factor so the frame region fits a target height (default 450px)
3. Centers the character horizontally and positions the frame at the top of the portal
4. Works for any character shape -- humanoids, mascots, or abstract characters -- without classification

Project Structure

interactive-icon/
  avatar_compositor.py   # Core compositing engine + auto-framing
  ui.py                  # Gradio web UI
  run.sh                 # CLI entry point (auto-installs deps)
  run_ui.sh              # Web UI entry point (auto-installs deps)
  portal_shape.svg       # Portal background shape (egg-shaped)
  mask_shape.svg         # Character clipping mask shape
  bounding-boxes.json    # Sample head bounding boxes for testing
  requirements.txt       # Python dependencies

Bounding Box Format

Head bounding boxes use [x1, y1, x2, y2] coordinates:

{
  "character_name": {
    "bbox": [407, 105, 686, 510],
    "label": "head",
    "confidence": 0.67
  }
}

These can be obtained from any object detection or vision model that supports bounding box queries.

License

MIT