quickthumb 0.4.0__tar.gz → 0.6.0__tar.gz

{quickthumb-0.4.0 → quickthumb-0.6.0}/.github/workflows/publish.yaml

@@ -23,7 +23,7 @@ jobs:
 
       - name: Test
         run: |
-          uv run pytest tests/ --ignore=tests/test_rendering.py
+          uv run --extra cli pytest tests/ --ignore=tests/test_rendering.py
 
       - name: Determine Version Change
         id: version_check

quickthumb-0.6.0/PKG-INFO

@@ -0,0 +1,563 @@
+Metadata-Version: 2.4
+Name: quickthumb
+Version: 0.6.0
+Summary: Programmatic thumbnail and social image generation with layered Python and JSON APIs
+Project-URL: Homepage, https://github.com/sjquant/quickthumb
+Project-URL: Repository, https://github.com/sjquant/quickthumb
+Project-URL: Issues, https://github.com/sjquant/quickthumb/issues
+Project-URL: Documentation, https://github.com/sjquant/quickthumb#readme
+Author: Seonu Jang
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,graphics,image-generation,pillow,social-media,thumbnail,thumbnails
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pillow<11.0.0,>=10.4.0
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Requires-Dist: typing-extensions<5.0.0,>=4.15.0
+Provides-Extra: cli
+Requires-Dist: typer<1.0,>=0.24.1; extra == 'cli'
+Requires-Dist: watchfiles<2.0.0,>=1.0.0; extra == 'cli'
+Provides-Extra: pptx
+Requires-Dist: python-pptx<2.0,>=1.0.2; extra == 'pptx'
+Provides-Extra: rembg
+Requires-Dist: onnxruntime<2.0.0,>=1.24.1; extra == 'rembg'
+Requires-Dist: rembg<3.0.0,>=2.0.50; extra == 'rembg'
+Provides-Extra: svg
+Requires-Dist: cairosvg<3.0.0,>=2.7.0; extra == 'svg'
+Description-Content-Type: text/markdown
+
+# quickthumb
+
+quickthumb is a Python library for programmatic thumbnail, social card, and promo image generation.
+It is designed for code-first and JSON-first workflows, with a layer-based API that works well for human-authored scripts and AI-generated specs.
+
+## Gallery
+
+| YouTube Thumbnail | Burnout Thumbnail | Instagram News Card |
+| --- | --- | --- |
+| ![YouTube thumbnail example](examples/youtube_thumbnail_01.png) | ![Burnout thumbnail example](examples/youtube_thumbnail_02.png) | ![Instagram news card example](examples/instagram_news_card.png) |
+
+| Talking Head | Reaction / Commentary | Tutorial / Explainer |
+| --- | --- | --- |
+| ![Talking head thumbnail example](examples/youtube_talking_head.png) | ![Reaction thumbnail example](examples/youtube_reaction.png) | ![Tutorial thumbnail example](examples/youtube_tutorial_explainer.png) |
+
+![Launch announcement example built with auto-layout groups, theme tokens, star shapes, and SVG layers](examples/launch_announcement.png)
+
+*One JSON spec, zero hand-placed text coordinates: [`examples/launch_announcement.json`](examples/launch_announcement.json) combines auto-layout groups, theme tokens, star shapes, SVG layers, grain, and `diagnose()`.*
+
+## Why quickthumb
+
+- Built for thumbnails and social graphics, not just generic image composition
+- Works with Python method chaining and JSON serialization/deserialization
+- Handles gradients, remote images, rich text, shapes, blend modes, and export helpers
+- Good fit for AI-assisted workflows that need deterministic image specs
+
+## Installation
+
+```bash
+uv pip install quickthumb
+```
+
+Optional background removal support:
+
+```bash
+uv pip install "quickthumb[rembg]"
+```
+
+Optional SVG layer support:
+
+```bash
+uv pip install "quickthumb[svg]"
+```
+
+Optional PowerPoint (PPTX) export support:
+
+```bash
+uv pip install "quickthumb[pptx]"
+```
+
+## Quick Start
+
+```python
+from quickthumb import Background, Canvas, Filter, Shadow, Stroke, TextPart
+
+canvas = (
+    Canvas.from_aspect_ratio("16:9", base_width=1280)
+    .background(
+        image="https://images.unsplash.com/photo-1516321318423-f06f85e504b3",
+        effects=[Filter(brightness=0.65)],
+    )
+    .background(color="#000000", opacity=0.45)
+    .text(
+        content=[
+            TextPart(
+                text="BUILD THUMBNAILS\nFAST\n",
+                color="#B8FF00",
+                effects=[Stroke(width=8, color="#000000")],
+            ),
+            TextPart(
+                text="With Python or JSON specs",
+                color="#F5F5F5",
+                size=44,
+                effects=[Shadow(offset_x=2, offset_y=2, color="#000000", blur_radius=4)],
+            ),
+        ],
+        size=112,
+        position=("8%", "50%"),
+        align=("left", "middle"),
+        weight=900,
+    )
+    .outline(width=14, color="#B8FF00")
+)
+
+canvas.render("thumbnail.png")
+```
+
+## Core API
+
+### Create a canvas
+
+```python
+from quickthumb import Canvas
+
+canvas = Canvas(1280, 720)
+square = Canvas.from_aspect_ratio("1:1", base_width=1080)
+vertical = Canvas.from_aspect_ratio("9:16", base_width=1080)
+```
+
+### Background layers
+
+```python
+from quickthumb import Canvas, Filter, FitMode, LinearGradient
+
+canvas = (
+    Canvas(1280, 720)
+    .background(color="#101828")
+    .background(
+        gradient=LinearGradient(
+            angle=120,
+            stops=[("#0F172A", 0.0), ("#0F172A00", 1.0)],
+        ),
+    )
+    .background(
+        image="hero.jpg",
+        fit=FitMode.COVER,
+        blend_mode="multiply",
+        effects=[Filter(blur=4, brightness=0.75, contrast=1.1, saturation=0.9)],
+    )
+)
+```
+
+### Text layers and rich text
+
+```python
+from quickthumb import Background, Canvas, Glow, Shadow, Stroke, TextPart
+
+canvas = Canvas(1280, 720).text(
+    content=[
+        TextPart(text="5 ", color="#FBBF24", weight=900),
+        TextPart(text="WARNING SIGNS", color="#FFFFFF", weight=900),
+    ],
+    size=72,
+    position=(80, 540),
+    effects=[
+        Background(color="#111827CC", padding=(16, 22), border_radius=12),
+        Stroke(width=2, color="#000000"),
+        Shadow(offset_x=4, offset_y=4, color="#000000", blur_radius=8),
+        Glow(color="#F59E0B", radius=14, opacity=0.35),
+    ],
+)
+```
+
+### Gradient and image-filled text
+
+Fill text with a gradient or image instead of a flat color. Works on the whole text layer or per `TextPart`.
+
+```python
+from quickthumb import Canvas, LinearGradient, RadialGradient, TextFillImage, TextPart
+
+# Gradient headline
+canvas = Canvas(1280, 720).text(
+    content="GRADIENT TITLE",
+    size=120,
+    fill=LinearGradient(
+        angle=90,
+        stops=[("#FF6B6B", 0.0), ("#FFE66D", 0.5), ("#4ECDC4", 1.0)],
+    ),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Image-filled text
+canvas = Canvas(1280, 720).text(
+    content="TEXTURE",
+    size=140,
+    fill=TextFillImage(path="fire_texture.jpg", fit="cover"),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Per-segment fills using TextPart
+canvas = Canvas(1280, 720).text(
+    content=[
+        TextPart(
+            text="HOT ",
+            fill=LinearGradient(angle=45, stops=[("#FF4500", 0.0), ("#FFD700", 1.0)]),
+            weight=900,
+        ),
+        TextPart(
+            text="COLD",
+            fill=LinearGradient(angle=45, stops=[("#00BFFF", 0.0), ("#8A2BE2", 1.0)]),
+            weight=900,
+        ),
+    ],
+    size=110,
+    position=("50%", "50%"),
+    align="center",
+)
+```
+
+`fill` accepts `LinearGradient`, `RadialGradient`, or `TextFillImage`. It is mutually independent of `color` — when `fill` is set it takes visual precedence. A `fill` on a `TextPart` overrides the layer-level `fill` for that segment only.
+
+### Image layers
+
+```python
+from quickthumb import Canvas, Filter
+
+canvas = Canvas(1280, 720).image(
+    path="portrait.png",
+    position=("73%", "52%"),
+    width=420,
+    height=520,
+    fit="cover",
+    align=("center", "middle"),
+    border_radius=24,
+    remove_background=True,
+    blend_mode="normal",
+    effects=[Filter(contrast=1.1, saturation=1.05)],
+)
+```
+
+### Shape layers
+
+```python
+from quickthumb import Canvas, Shadow, Stroke
+
+canvas = Canvas(1280, 720).shape(
+    shape="rectangle",
+    position=(64, 60),
+    width=320,
+    height=88,
+    color="#CC0000",
+    border_radius=10,
+    effects=[
+        Stroke(width=2, color="#FFFFFF"),
+        Shadow(offset_x=0, offset_y=6, color="#000000", blur_radius=12),
+    ],
+)
+```
+
+Beyond `rectangle` and `ellipse`, shape layers support `pill`, `triangle`, `star`, and `polygon`:
+
+```python
+canvas = (
+    Canvas(1280, 720)
+    .shape(shape="pill", position=(64, 60), width=200, height=56, color="#B8FF00")
+    .shape(shape="star", position=(400, 60), width=120, height=120, color="#FFD700",
+           star_points=6, inner_radius=0.4)
+    .shape(
+        shape="polygon",  # normalized 0..1 points inside the shape box
+        position=(600, 60),
+        width=160,
+        height=100,
+        color="#53BF9D",
+        points=[(0.0, 0.25), (0.6, 0.25), (0.6, 0.0), (1.0, 0.5), (0.6, 1.0), (0.6, 0.75), (0.0, 0.75)],
+    )
+)
+```
+
+### SVG layers
+
+Rasterize SVG icons and logos at render time (requires `quickthumb[svg]`):
+
+```python
+canvas = Canvas(1280, 720).svg(
+    path="logo.svg",
+    position=("90%", "8%"),
+    width=120,
+    align=("right", "top"),
+)
+```
+
+`width`/`height` control the raster size (aspect ratio is preserved when only one is set). SVG layers support `opacity`, `rotation`, `align`, `blend_mode`, and the same `effects` as image layers.
+
+### Group layers (auto layout)
+
+Stop hand-placing coordinates: a `group` measures its children and stacks them along a row or column. Specs survive content-length changes, which makes them much more reliable for LLM-generated layouts.
+
+```python
+canvas = Canvas(1280, 720).background(color="#16213E").group(
+    children=[
+        {"type": "shape", "shape": "pill", "width": 120, "height": 36, "color": "#E94560"},
+        {"type": "text", "content": "AUTO LAYOUT", "size": 96, "color": "#FFFFFF", "weight": 900},
+        {"type": "text", "content": "No coordinates were harmed", "size": 40, "color": "#A2A8D3"},
+    ],
+    direction="column",
+    gap=24,
+    position=("8%", "50%"),
+    align=("left", "middle"),
+)
+```
+
+- `direction`: `"column"` (default) or `"row"`
+- `gap`: pixels between children; `padding`: int, `(vertical, horizontal)`, or `(top, right, bottom, left)`
+- `item_align`: cross-axis placement per child — `"start"`, `"center"`, or `"end"`
+- `position` + `align` anchor the whole group box, like image layers
+- Children may be `text`, `image`, `shape`, `svg`, or nested `group` layers; they must not set their own `position`
+
+### Theme tokens
+
+Define brand tokens once in a JSON spec and reference them anywhere with `$theme.path`:
+
+```json
+{
+  "width": 1280,
+  "height": 720,
+  "theme": {
+    "colors": {"primary": "#B8FF00", "ink": "#111111"},
+    "sizes": {"title": 96}
+  },
+  "layers": [
+    {"type": "background", "color": "$theme.colors.ink"},
+    {"type": "text", "content": "Hello", "size": "$theme.sizes.title", "color": "$theme.colors.primary"}
+  ]
+}
+```
+
+Whole-string references keep their native JSON type (numbers, lists); scalar tokens can also be embedded inside longer strings. Unknown tokens raise `ValidationError`. Theme tokens work alongside `$var` template substitution.
+
+### Diagnostics
+
+`canvas.diagnose()` checks a composition for common problems without writing a file — ideal for agent loops (render → diagnose → fix):
+
+```python
+for finding in canvas.diagnose():
+    print(finding.severity, finding.code, finding.message)
+```
+
+Findings: `off-canvas` (layer outside the canvas), `tiny-text` (under 2.5% of canvas height), `text-overflow` (a word wider than `max_width`), and `low-contrast` (text vs the composited layers below it). The CLI equivalent is `quickthumb lint spec.json` (exit codes: 0 clean, 1 invalid spec, 2 render failure, 3 findings).
+
+### Grain / noise effect
+
+Add film-grain noise to background or image layers via `effects=[Grain(...)]`.
+
+```python
+from quickthumb import Canvas, Grain
+
+canvas = (
+    Canvas(1280, 720)
+    .background(
+        color="#1A1A2E",
+        effects=[Grain(intensity=0.12, monochrome=True)],
+    )
+    .image(
+        path="portrait.png",
+        position=("70%", "50%"),
+        width=400,
+        height=500,
+        align=("center", "middle"),
+        effects=[Grain(intensity=0.08, monochrome=False, blend_mode="overlay", opacity=0.6)],
+    )
+)
+```
+
+`Grain` parameters:
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intensity` | `float` | required | Noise amplitude, `0.0`–`1.0` |
+| `monochrome` | `bool` | `True` | `True` = luminance noise; `False` = per-channel color noise |
+| `blend_mode` | `str` | `"overlay"` | `"overlay"`, `"screen"`, `"multiply"`, or `"normal"` |
+| `opacity` | `float` | `1.0` | Overall grain strength, `0.0`–`1.0` |
+| `seed` | `int \| None` | `None` | Optional RNG seed for deterministic output |
+
+`Grain` is valid in `effects` on **background** and **image** layers. It is serialized with `"type": "grain"` in JSON.
+
+### Export helpers
+
+```python
+png_base64 = canvas.to_base64(format="PNG")
+jpeg_data_url = canvas.to_data_url(format="JPEG", quality=90)
+canvas.render("output.webp", format="WEBP", quality=90)
+```
+
+### SVG and PPTX renderers
+
+The same canvas renders to vector and document formats, detected from the file extension:
+
+```python
+canvas.render("card.svg")    # vector SVG with native shapes, gradients, and selectable text
+canvas.render("card.pptx")   # PowerPoint slide with editable text boxes and autoshapes
+
+svg_markup = canvas.to_svg(embed_fonts=True)  # inline @font-face for portable text
+pptx_bytes = canvas.to_pptx()                 # requires quickthumb[pptx]
+```
+
+Layers the target format can express (backgrounds, gradients, outlines, shapes, text — including wrapping, rich parts, letter spacing, and effects) are exported natively and stay editable; everything else (raster images, blend modes, custom layers) is embedded as pixel-exact PNG fragments rendered by the regular pipeline. See the [export docs](https://sjquant.github.io/quickthumb/exports/) for the full mapping.
+
+## JSON-First Workflow
+
+quickthumb can round-trip most canvases through JSON:
+
+```python
+from quickthumb import Canvas
+
+config = """
+{
+  "width": 1280,
+  "height": 720,
+  "layers": [
+    {
+      "type": "background",
+      "color": "#111827"
+    },
+    {
+      "type": "text",
+      "content": "Hello quickthumb",
+      "size": 72,
+      "color": "#FFFFFF",
+      "align": "center",
+      "position": ["50%", "50%"]
+    },
+    {
+      "type": "outline",
+      "width": 10,
+      "color": "#22C55E"
+    }
+  ]
+}
+"""
+
+canvas = Canvas.from_json(config)
+canvas.render("hello.png")
+
+serialized = canvas.to_json()
+```
+
+Notes:
+
+- JSON uses top-level `width`, `height`, and `layers`
+- Named custom layers added with `canvas.custom(fn, name="...", kwargs={...})` are JSON-serializable via the registry; unnamed custom layers are not
+- Enum-like values such as `blend_mode`, `fit`, and `align` can be passed as strings
+
+## AI-Friendly Workflows
+
+quickthumb is a good target when you want an LLM to generate image specs that are deterministic and easy to validate.
+
+Prompt pattern for Python generation:
+
+```text
+Generate quickthumb Python code for a 1280x720 YouTube thumbnail.
+Use layered composition only.
+Keep text on the left, subject image on the right, and use high-contrast typography.
+Return runnable code that ends with canvas.render("thumbnail.png").
+```
+
+Prompt pattern for JSON generation:
+
+```text
+Generate a quickthumb JSON config with top-level width, height, and layers.
+Use one background image layer, one dark overlay background layer, two text layers, and one outline layer.
+Only use valid quickthumb layer types and effect names.
+```
+
+Recommended workflow:
+
+1. Have the model produce quickthumb Python or JSON.
+2. Validate or render it locally.
+3. Adjust only the content, colors, and assets instead of rewriting layout logic from scratch.
+
+## Environment Variables
+
+quickthumb looks for fonts using these environment variables:
+
+- `QUICKTHUMB_FONT_DIR`: directory that contains font files
+- `QUICKTHUMB_DEFAULT_FONT`: default font family/name to use when `font` is omitted
+
+Example:
+
+```python
+import os
+
+os.environ["QUICKTHUMB_FONT_DIR"] = "assets/fonts"
+os.environ["QUICKTHUMB_DEFAULT_FONT"] = "Roboto"
+```
+
+## Feature Matrix
+
+| Area | Supported |
+| --- | --- |
+| Canvas sizing | Explicit width/height, `from_aspect_ratio()` |
+| Backgrounds | Solid colors, linear gradients, radial gradients, local/remote images |
+| Background controls | Opacity, blend modes, fit modes, blur, brightness, contrast, saturation |
+| Text | Positioning, alignment, wrapping, letter spacing, line height, rotation, auto-scale |
+| Rich text | Per-segment `TextPart` styling |
+| Text fills | Gradient (`LinearGradient`, `RadialGradient`) and image (`TextFillImage`) fills; per-`TextPart` override |
+| Text effects | Stroke, shadow, glow, background fill |
+| Fonts | Local fonts, CSS-style weights, italic/bold flags, webfont URLs, fallback mapping |
+| Images | Local/remote images, sizing, fit modes, alignment, opacity, rotation |
+| Image effects | Stroke, shadow, glow, filter effects, border radius, background removal |
+| Grain / noise | Per-layer `Grain` effect on background and image layers; monochrome or color noise |
+| Shapes | Rectangle, ellipse, pill, triangle, star, and polygon primitives with stroke/shadow/glow support |
+| SVG | `svg` layers rasterized via optional `quickthumb[svg]` extra |
+| Auto layout | `group` layers: row/column stacking, gap, padding, item alignment, nesting |
+| Theme tokens | Top-level `theme` block with `$theme.path` references in JSON specs |
+| Diagnostics | `canvas.diagnose()` and `quickthumb lint`: off-canvas, tiny text, overflow, low contrast |
+| Export | PNG, JPEG, WebP, file output, base64, data URLs |
+| Document renderers | SVG (`to_svg()`), editable PPTX via optional `quickthumb[pptx]` extra |
+| Serialization | `to_json()` / `from_json()` for built-in layer types and named custom layers |
+
+## Real Example Scripts
+
+See the shipped examples in [`examples/README.md`](examples/README.md):
+
+- `examples/youtube_thumbnail_01.py`
+- `examples/youtube_thumbnail_02.py`
+- `examples/instagram_news_card.py`
+- `examples/launch_announcement.py` — the 0.5 feature set (groups, theme tokens, shapes, SVG, diagnostics) in one JSON spec
+
+## Gotchas
+
+- `weight` and `bold=True` are mutually exclusive on text layers and `TextPart`
+- `auto_scale=True` requires `max_width`
+- `position` percentage values must be strings like `"50%"`
+- `fill` and `color` are independent fields; when `fill` is set it takes visual precedence over `color`
+- `canvas.custom(fn)` without a `name` runs during render order but cannot be serialized to JSON; pass `name=` and register the function with `Canvas.register_layer_fn()` to enable serialization
+- `Grain` is valid only on background and image layer `effects`; it is not a valid text or shape effect
+- `Grain(intensity=0.0)` is a no-op (no noise is generated or composited)
+- Group children must not set `position`; the group assigns positions (their `align` is also ignored — use `item_align`)
+- `svg` layers raise `RenderingError` unless `quickthumb[svg]` (cairosvg) is installed
+- `theme` blocks are resolved at parse time; `to_json()` emits resolved values without the `theme` block
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ty quickthumb/
+```
+
+## Reference
+
+- License: [LICENSE](LICENSE)