sticker-generator 0.1.0__tar.gz

sticker_generator-0.1.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Generated stickers (for testing)
+*.png
+!tests/fixtures/*.png
+
+# OS
+.DS_Store
+Thumbs.db
+CLAUDE.md

sticker_generator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sticker_generator-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: sticker-generator
+Version: 0.1.0
+Summary: Generate stickers with transparent backgrounds using Gemini AI
+Project-URL: Homepage, https://github.com/ali/sticker-generator
+Project-URL: Repository, https://github.com/ali/sticker-generator
+Project-URL: Issues, https://github.com/ali/sticker-generator/issues
+Author: Ali
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,gemini,image-generation,sticker,transparent-background
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sticker Generator
+
+Generate stickers with transparent backgrounds using Google's Gemini AI.
+
+## Installation
+
+```bash
+pip install sticker-generator
+```
+
+## Setup
+
+Set your Gemini API key as an environment variable:
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+```
+
+Or pass it directly to the functions/CLI.
+
+## Usage
+
+### Command Line
+
+```bash
+# Basic usage
+sticker-generator "a cute happy cat with big eyes"
+
+# Specify output file
+sticker-generator "a rocket ship" -o rocket.png
+
+# Use reference images
+sticker-generator "similar style illustration" -i reference1.png -i reference2.png
+
+# Custom aspect ratio
+sticker-generator "a wide banner" --aspect-ratio 16:9
+
+# Save raw image before processing
+sticker-generator "a dog" --save-raw
+```
+
+### Python API
+
+```python
+from sticker_generator import create_sticker
+
+# Basic usage
+sticker = create_sticker(
+    prompt="a cute happy cat with big eyes",
+    output="cat.png"
+)
+
+# With reference images
+sticker = create_sticker(
+    prompt="similar style illustration",
+    output="custom.png",
+    input_images=["reference1.png", "reference2.png"]
+)
+
+# Just get the image without saving
+sticker = create_sticker(
+    prompt="a rocket ship",
+    output=None  # Returns PIL Image
+)
+```
+
+### Image Processing Only
+
+If you have your own green-screen images:
+
+```python
+from PIL import Image
+from sticker_generator import remove_green_screen_hsv, cleanup_edges
+
+# Load your image
+img = Image.open("green_background.png")
+
+# Remove green background
+transparent = remove_green_screen_hsv(img)
+
+# Clean up edges
+clean = cleanup_edges(transparent, threshold=64)
+
+# Save
+clean.save("transparent.png")
+```
+
+## How It Works
+
+1. **Generation**: Uses Gemini AI to generate an image with a chromakey green (#00FF00) background
+2. **Green Removal**: Converts to HSV color space and removes pixels matching green hue
+3. **Edge Cleanup**: Removes semi-transparent edge artifacts for clean results
+
+## License
+
+MIT

sticker_generator-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Sticker Generator
+
+Generate stickers with transparent backgrounds using Google's Gemini AI.
+
+## Installation
+
+```bash
+pip install sticker-generator
+```
+
+## Setup
+
+Set your Gemini API key as an environment variable:
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+```
+
+Or pass it directly to the functions/CLI.
+
+## Usage
+
+### Command Line
+
+```bash
+# Basic usage
+sticker-generator "a cute happy cat with big eyes"
+
+# Specify output file
+sticker-generator "a rocket ship" -o rocket.png
+
+# Use reference images
+sticker-generator "similar style illustration" -i reference1.png -i reference2.png
+
+# Custom aspect ratio
+sticker-generator "a wide banner" --aspect-ratio 16:9
+
+# Save raw image before processing
+sticker-generator "a dog" --save-raw
+```
+
+### Python API
+
+```python
+from sticker_generator import create_sticker
+
+# Basic usage
+sticker = create_sticker(
+    prompt="a cute happy cat with big eyes",
+    output="cat.png"
+)
+
+# With reference images
+sticker = create_sticker(
+    prompt="similar style illustration",
+    output="custom.png",
+    input_images=["reference1.png", "reference2.png"]
+)
+
+# Just get the image without saving
+sticker = create_sticker(
+    prompt="a rocket ship",
+    output=None  # Returns PIL Image
+)
+```
+
+### Image Processing Only
+
+If you have your own green-screen images:
+
+```python
+from PIL import Image
+from sticker_generator import remove_green_screen_hsv, cleanup_edges
+
+# Load your image
+img = Image.open("green_background.png")
+
+# Remove green background
+transparent = remove_green_screen_hsv(img)
+
+# Clean up edges
+clean = cleanup_edges(transparent, threshold=64)
+
+# Save
+clean.save("transparent.png")
+```
+
+## How It Works
+
+1. **Generation**: Uses Gemini AI to generate an image with a chromakey green (#00FF00) background
+2. **Green Removal**: Converts to HSV color space and removes pixels matching green hue
+3. **Edge Cleanup**: Removes semi-transparent edge artifacts for clean results
+
+## License
+
+MIT

sticker_generator-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sticker-generator"
+version = "0.1.0"
+description = "Generate stickers with transparent backgrounds using Gemini AI"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Ali" }
+]
+keywords = ["sticker", "gemini", "ai", "image-generation", "transparent-background"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "google-genai>=1.0.0",
+    "Pillow>=10.0.0",
+    "numpy>=1.24.0",
+    "scipy>=1.10.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.scripts]
+sticker-generator = "sticker_generator.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ali/sticker-generator"
+Repository = "https://github.com/ali/sticker-generator"
+Issues = "https://github.com/ali/sticker-generator/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sticker_generator"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "UP",     # pyupgrade
+]
+ignore = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["sticker_generator"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["src/sticker_generator"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]

sticker_generator-0.1.0/src/sticker_generator/__init__.py

@@ -0,0 +1,17 @@
+"""Sticker Generator - Create stickers with transparent backgrounds using Gemini AI."""
+
+from sticker_generator.core import create_sticker, generate_sticker
+from sticker_generator.image_processing import (
+    cleanup_edges,
+    remove_green_screen_aggressive,
+    remove_green_screen_hsv,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "create_sticker",
+    "generate_sticker",
+    "remove_green_screen_hsv",
+    "remove_green_screen_aggressive",
+    "cleanup_edges",
+]

sticker_generator-0.1.0/src/sticker_generator/cli.py

@@ -0,0 +1,89 @@
+"""Command-line interface for sticker generation."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from sticker_generator.core import create_sticker
+
+
+def main() -> int:
+    """Main entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="sticker-generator",
+        description="Generate stickers with transparent backgrounds using Gemini AI",
+    )
+    parser.add_argument(
+        "prompt",
+        help="Description of the sticker to generate",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="sticker.png",
+        help="Output filename (default: sticker.png)",
+    )
+    parser.add_argument(
+        "-i",
+        "--image",
+        action="append",
+        dest="images",
+        help="Reference image path (can be specified multiple times)",
+    )
+    parser.add_argument(
+        "--aspect-ratio",
+        default="1:1",
+        help="Image aspect ratio (default: 1:1)",
+    )
+    parser.add_argument(
+        "--save-raw",
+        action="store_true",
+        help="Save the raw image before green screen removal",
+    )
+    parser.add_argument(
+        "--edge-threshold",
+        type=int,
+        default=64,
+        help="Alpha threshold for edge cleanup, 0-255 (default: 64)",
+    )
+    parser.add_argument(
+        "--api-key",
+        help="Gemini API key (or set GEMINI_API_KEY environment variable)",
+    )
+
+    args = parser.parse_args()
+
+    # Validate reference images exist
+    if args.images:
+        for img_path in args.images:
+            if not Path(img_path).exists():
+                print(f"Error: Reference image not found: {img_path}", file=sys.stderr)
+                return 1
+
+    try:
+        print(f"Generating sticker: {args.prompt}")
+        if args.images:
+            print(f"Using {len(args.images)} reference image(s)")
+
+        create_sticker(
+            prompt=args.prompt,
+            output=args.output,
+            aspect_ratio=args.aspect_ratio,
+            save_raw=args.save_raw,
+            input_images=args.images,
+            api_key=args.api_key,
+            edge_threshold=args.edge_threshold,
+        )
+
+        print(f"Sticker saved to: {args.output}")
+        return 0
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sticker_generator-0.1.0/src/sticker_generator/core.py

@@ -0,0 +1,199 @@
+"""Core sticker generation functionality using Gemini AI."""
+
+from __future__ import annotations
+
+import base64
+import io
+import mimetypes
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from google import genai
+from PIL import Image
+
+from sticker_generator.image_processing import (
+    cleanup_edges,
+    remove_green_screen_aggressive,
+    remove_green_screen_hsv,
+    save_transparent_png,
+)
+
+if TYPE_CHECKING:
+    from os import PathLike
+
+MODEL_ID = "gemini-2.5-flash-image"
+
+# fmt: off
+# ruff: noqa: E501
+CHROMAKEY_PROMPT_TEMPLATE = """Create a sticker illustration of: {prompt}
+
+CRITICAL CHROMAKEY REQUIREMENTS:
+1. BACKGROUND: Solid, flat, uniform chromakey green color. Use EXACTLY hex color #00FF00 (RGB 0, 255, 0).
+   The entire background must be this single pure green color with NO variation, NO gradients, NO shadows, NO lighting effects.
+
+2. WHITE OUTLINE: The subject MUST have a clean white outline/border (2-3 pixels wide) separating it from the green background.
+   This white border prevents color bleeding between the subject and background.
+
+3. NO GREEN ON SUBJECT: The subject itself should NOT contain any green colors to avoid confusion with the chromakey.
+   If the subject needs green (like leaves), use a distinctly different shade like dark forest green or teal.
+
+4. SHARP EDGES: The subject should have crisp, sharp, well-defined edges - no soft or blurry boundaries.
+
+5. CENTERED: Subject should be centered with padding around all sides.
+
+6. STYLE: Vibrant, clean, cartoon/illustration sticker style with bold colors.
+
+This is for chromakey extraction - the green background will be removed programmatically."""
+# fmt: on
+
+
+def decode_image(data: str | bytes) -> Image.Image:
+    """Decode image data to PIL Image.
+
+    Args:
+        data: Base64-encoded string or raw bytes.
+
+    Returns:
+        PIL Image object.
+    """
+    if isinstance(data, str):
+        image_bytes = base64.b64decode(data)
+    else:
+        image_bytes = data
+    return Image.open(io.BytesIO(image_bytes))
+
+
+def load_image_as_content(image_path: str | PathLike) -> genai.types.Part:
+    """Load an image file and return as API content block.
+
+    Args:
+        image_path: Path to the image file.
+
+    Returns:
+        Part formatted for Gemini API content.
+    """
+    path = Path(image_path)
+    mime_type, _ = mimetypes.guess_type(str(path))
+    if mime_type is None:
+        mime_type = "image/jpeg"
+
+    with open(path, "rb") as f:
+        image_data = f.read()
+
+    return genai.types.Part.from_bytes(data=image_data, mime_type=mime_type)
+
+
+def generate_sticker(
+    prompt: str,
+    aspect_ratio: str = "1:1",
+    input_images: list[str | PathLike] | None = None,
+    api_key: str | None = None,
+) -> Image.Image:
+    """Generate a sticker image with chromakey green background.
+
+    Args:
+        prompt: Description of the sticker to generate.
+        aspect_ratio: Image aspect ratio (default "1:1").
+        input_images: Optional list of reference image paths.
+        api_key: Optional Gemini API key (uses GEMINI_API_KEY env var if not provided).
+
+    Returns:
+        PIL Image with green background (before processing).
+
+    Raises:
+        ValueError: If no image was generated.
+    """
+    client = genai.Client(api_key=api_key) if api_key else genai.Client()
+
+    enhanced_prompt = CHROMAKEY_PROMPT_TEMPLATE.format(prompt=prompt)
+
+    input_content: str | list = enhanced_prompt
+    if input_images:
+        content_list: list = []
+        for img_path in input_images:
+            content_list.append(load_image_as_content(img_path))
+        content_list.append(enhanced_prompt)
+        input_content = content_list
+
+    response = client.models.generate_content(
+        model=MODEL_ID,
+        contents=input_content,
+        config=genai.types.GenerateContentConfig(
+            response_modalities=["TEXT", "IMAGE"],
+        ),
+    )
+
+    if response.candidates:
+        for part in response.candidates[0].content.parts:  # type: ignore[union-attr]
+            if part.inline_data is not None:
+                print(f"Found image: mime_type={part.inline_data.mime_type}")
+                return decode_image(part.inline_data.data)  # type: ignore[arg-type]
+            elif part.text:
+                print(f"Text response: {part.text[:200]}...")
+
+    raise ValueError("No image was generated")
+
+
+def create_sticker(
+    prompt: str,
+    output: str | PathLike | None = None,
+    aspect_ratio: str = "1:1",
+    save_raw: bool = False,
+    input_images: list[str | PathLike] | None = None,
+    api_key: str | None = None,
+    edge_threshold: int = 64,
+) -> Image.Image:
+    """Generate a sticker with transparent background.
+
+    Complete workflow: generates image with green background, removes green,
+    cleans edges, and optionally saves to file.
+
+    Args:
+        prompt: Description of the sticker to generate.
+        output: Optional output filename (PNG recommended).
+        aspect_ratio: Image aspect ratio (default "1:1").
+        save_raw: If True, save the raw image before processing.
+        input_images: Optional list of reference image paths.
+        api_key: Optional Gemini API key (uses GEMINI_API_KEY env var if not provided).
+        edge_threshold: Alpha threshold for edge cleanup (0-255).
+
+    Returns:
+        PIL Image with transparent background.
+    """
+    raw_image = generate_sticker(
+        prompt=prompt,
+        aspect_ratio=aspect_ratio,
+        input_images=input_images,
+        api_key=api_key,
+    )
+
+    if save_raw and output:
+        output_path = Path(output)
+        raw_filename = output_path.with_stem(output_path.stem + "_raw")
+        raw_image.save(raw_filename)
+
+    # HSV-based green removal (permissive settings for various green shades)
+    transparent_image = remove_green_screen_hsv(
+        raw_image,
+        hue_center=115,
+        hue_range=35,
+        min_saturation=25,
+        min_value=40,
+        dilation_iterations=2,
+        erosion_iterations=0,
+    )
+
+    # Second pass: aggressive removal for remaining greens
+    transparent_image = remove_green_screen_aggressive(
+        transparent_image,
+        green_threshold=1.1,
+        edge_pixels=1,
+    )
+
+    # Edge cleanup
+    transparent_image = cleanup_edges(transparent_image, threshold=edge_threshold)
+
+    if output:
+        save_transparent_png(transparent_image, str(output))
+
+    return transparent_image

sticker_generator-0.1.0/src/sticker_generator/image_processing.py

@@ -0,0 +1,171 @@
+"""Image processing utilities for green screen removal and edge cleanup."""
+
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+
+
+def rgb_to_hsv_array(rgb_array: np.ndarray) -> np.ndarray:
+    """Convert RGB array to HSV array efficiently.
+
+    Args:
+        rgb_array: NumPy array of RGB values (H, W, 3).
+
+    Returns:
+        NumPy array of HSV values (H, W, 3) with H in [0, 360], S and V in [0, 100].
+    """
+    rgb_normalized = rgb_array.astype(np.float32) / 255.0
+    r, g, b = rgb_normalized[:, :, 0], rgb_normalized[:, :, 1], rgb_normalized[:, :, 2]
+
+    max_c = np.maximum(np.maximum(r, g), b)
+    min_c = np.minimum(np.minimum(r, g), b)
+    delta = max_c - min_c
+
+    h = np.zeros_like(max_c)
+    mask_r = (max_c == r) & (delta != 0)
+    h[mask_r] = (60 * ((g[mask_r] - b[mask_r]) / delta[mask_r]) + 360) % 360
+
+    mask_g = (max_c == g) & (delta != 0)
+    h[mask_g] = 60 * ((b[mask_g] - r[mask_g]) / delta[mask_g]) + 120
+
+    mask_b = (max_c == b) & (delta != 0)
+    h[mask_b] = 60 * ((r[mask_b] - g[mask_b]) / delta[mask_b]) + 240
+
+    s = np.zeros_like(max_c)
+    s[max_c != 0] = delta[max_c != 0] / max_c[max_c != 0]
+
+    v = max_c
+    return np.stack([h, s * 100, v * 100], axis=-1)
+
+
+def remove_green_screen_hsv(
+    image: Image.Image,
+    hue_center: float = 120,
+    hue_range: float = 25,
+    min_saturation: float = 75,
+    min_value: float = 70,
+    dilation_iterations: int = 2,
+    erosion_iterations: int = 0,
+) -> Image.Image:
+    """Remove green screen using HSV color space detection.
+
+    Args:
+        image: PIL Image to process.
+        hue_center: Center hue value for green (default 120 degrees).
+        hue_range: Tolerance around hue center in degrees.
+        min_saturation: Minimum saturation percentage to consider as green.
+        min_value: Minimum value/brightness percentage to consider as green.
+        dilation_iterations: Number of dilation passes to catch anti-aliased edges.
+        erosion_iterations: Number of erosion passes.
+
+    Returns:
+        PIL Image with green background removed (RGBA with transparency).
+    """
+    if image.mode != "RGBA":
+        image = image.convert("RGBA")
+
+    data = np.array(image)
+    rgb = data[:, :, :3]
+    hsv = rgb_to_hsv_array(rgb)
+    h, s, v = hsv[:, :, 0], hsv[:, :, 1], hsv[:, :, 2]
+
+    hue_diff = np.abs(h - hue_center)
+    hue_diff = np.minimum(hue_diff, 360 - hue_diff)
+
+    green_mask = (hue_diff < hue_range) & (s > min_saturation) & (v > min_value)
+
+    if dilation_iterations > 0 or erosion_iterations > 0:
+        from scipy import ndimage
+
+        if dilation_iterations > 0:
+            green_mask = ndimage.binary_dilation(
+                green_mask, iterations=dilation_iterations
+            )
+        if erosion_iterations > 0:
+            green_mask = ndimage.binary_erosion(
+                green_mask, iterations=erosion_iterations
+            )
+
+    alpha = data[:, :, 3].copy()
+    alpha[green_mask] = 0
+    data[:, :, 3] = alpha
+
+    return Image.fromarray(data)
+
+
+def remove_green_screen_aggressive(
+    image: Image.Image,
+    green_threshold: float = 1.2,
+    edge_pixels: int = 0,
+) -> Image.Image:
+    """Aggressive green removal detecting dominant green pixels.
+
+    This method catches darker greens and tinted shadows that HSV might miss.
+
+    Args:
+        image: PIL Image to process.
+        green_threshold: Ratio threshold for green channel dominance.
+        edge_pixels: Number of dilation iterations for edge expansion.
+
+    Returns:
+        PIL Image with green background removed (RGBA with transparency).
+    """
+    if image.mode != "RGBA":
+        image = image.convert("RGBA")
+
+    data = np.array(image)
+    r = data[:, :, 0].astype(float)
+    g = data[:, :, 1].astype(float)
+    b = data[:, :, 2].astype(float)
+
+    rb_max = np.maximum(r, b) + 1
+    green_ratio = g / rb_max
+    green_dominant = (g > r) & (g > b)
+    green_mask = (green_ratio > green_threshold) & green_dominant
+
+    if edge_pixels > 0:
+        from scipy import ndimage
+
+        green_mask = ndimage.binary_dilation(green_mask, iterations=edge_pixels)
+
+    alpha = data[:, :, 3].copy()
+    alpha[green_mask] = 0
+    data[:, :, 3] = alpha
+
+    return Image.fromarray(data)
+
+
+def cleanup_edges(image: Image.Image, threshold: int = 128) -> Image.Image:
+    """Clean up semi-transparent edge pixels by thresholding alpha.
+
+    Args:
+        image: PIL Image to process.
+        threshold: Alpha values below this become fully transparent,
+                   values at or above become fully opaque.
+
+    Returns:
+        PIL Image with cleaned edges.
+    """
+    if image.mode != "RGBA":
+        return image
+
+    data = np.array(image)
+    alpha = data[:, :, 3]
+    alpha[alpha < threshold] = 0
+    alpha[alpha >= threshold] = 255
+
+    data[:, :, 3] = alpha
+    return Image.fromarray(data)
+
+
+def save_transparent_png(image: Image.Image, filename: str) -> None:
+    """Save image as PNG with transparency preserved.
+
+    Args:
+        image: PIL Image to save.
+        filename: Output filename.
+    """
+    if image.mode != "RGBA":
+        image = image.convert("RGBA")
+    image.save(filename, "PNG")