pasteup 0.1.0__py3-none-any.whl

pasteup/routes/ui.py

@@ -0,0 +1,43 @@
+import os
+from pathlib import Path
+
+from fastapi import APIRouter, Request
+from fastapi.templating import Jinja2Templates
+
+from pasteup.services.cover_collage import COVER_COLLAGE_TEMPLATE_OPTIONS
+from mullion import DEFAULT_DPI
+
+# Prefills the input-folder field so a regular workflow does not need retyping on
+# every launch. It is read from the environment rather than written here because
+# any real value is somebody's home directory.
+INPUT_FOLDER_ENV_VAR = "PASTEUP_INPUT_FOLDER"
+
+router = APIRouter()
+templates = Jinja2Templates(directory=Path(__file__).resolve().parents[1] / "templates")
+
+
+@router.get("/")
+def index(request: Request):
+    return templates.TemplateResponse(
+        request=request,
+        name="index.html",
+        context={
+            "request": request,
+            "defaults": {
+                "input_folder": os.environ.get(INPUT_FOLDER_ENV_VAR, ""),
+                # app.js derives the output folder from the input folder on load.
+                "output_folder": "",
+                "page_width": 3000,
+                "page_height": 3000,
+                "gap": 30,
+                "margin": 60,
+                "format": "JPG",
+                "page_unit": "px",
+                "dpi": DEFAULT_DPI,
+            },
+            "cover_collage_templates": [
+                {"value": value, "name": name, "label": label}
+                for value, name, label in COVER_COLLAGE_TEMPLATE_OPTIONS
+            ],
+        },
+    )

pasteup/services/cover_collage.py

@@ -0,0 +1,379 @@
+"""Service for generating a full-page cover collage with seeded random placement."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+import logging
+from pathlib import Path
+import random
+import re
+from typing import Sequence
+
+from PIL import Image, UnidentifiedImageError
+
+from mullion import (
+    DEFAULT_TOLERANCE,
+    BackgroundCleanMode,
+    clean_background,
+    flatten_onto,
+    open_path,
+)
+
+logger = logging.getLogger(__name__)
+
+BACKGROUND_COLOR = (255, 255, 255)
+
+
+class CoverCollageFittingMode(StrEnum):
+    COVER = "cover"
+    CONTAIN = "contain"
+
+
+class CoverCollageTemplate(StrEnum):
+    RANDOMIZED_GRID = "randomized-grid"
+    FEATURE_SPREAD = "feature-spread"
+    CENTER_STAGE = "center-stage"
+
+
+@dataclass(frozen=True, slots=True)
+class CoverCollageTile:
+    x: int
+    y: int
+    width: int
+    height: int
+    role: str = "default"
+    fitting_mode: CoverCollageFittingMode | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CoverCollageLayoutTemplate:
+    name: str
+    tiles: list[CoverCollageTile]
+
+    @property
+    def slot_count(self) -> int:
+        return len(self.tiles)
+
+
+@dataclass(frozen=True, slots=True)
+class CoverCollageTileRect:
+    x: float
+    y: float
+    width: float
+    height: float
+    role: str = "default"
+    fitting_mode: CoverCollageFittingMode | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CoverCollageTemplateDefinition:
+    name: str
+    display_name: str
+    tiles: tuple[CoverCollageTileRect, ...]
+    default_fitting_mode: CoverCollageFittingMode | None = None
+
+    @property
+    def slot_count(self) -> int:
+        return len(self.tiles)
+
+
+@dataclass(slots=True)
+class CoverCollageSummary:
+    total_input_files: int
+    total_images_placed: int
+    total_images_skipped: int
+    output_created: bool
+    skipped_files: list[str]
+    background_cleaned: int = 0
+
+    @property
+    def user_message(self) -> str:
+        parts = [f"Generated 1 cover collage with {self.total_images_placed} image(s)."]
+        if self.total_images_skipped:
+            parts.append(f"Skipped {self.total_images_skipped} unreadable file(s).")
+        if self.background_cleaned:
+            parts.append(f"Cleaned the background on {self.background_cleaned} image(s).")
+        return " ".join(parts)
+
+
+def _load_image_rgb(image_path: str) -> Image.Image:
+    return open_path(image_path)
+
+
+def _resize_to_cover(image: Image.Image, width: int, height: int) -> Image.Image:
+    scale = max(width / image.width, height / image.height)
+    resized = image.resize(
+        (max(1, int(round(image.width * scale))), max(1, int(round(image.height * scale)))),
+        Image.Resampling.LANCZOS,
+    )
+
+    left = max(0, (resized.width - width) // 2)
+    top = max(0, (resized.height - height) // 2)
+    return resized.crop((left, top, left + width, top + height))
+
+
+def _resize_to_contain(
+    image: Image.Image,
+    width: int,
+    height: int,
+    background_color: tuple[int, int, int],
+) -> Image.Image:
+    scale = min(width / image.width, height / image.height)
+    resized = image.resize(
+        (max(1, int(round(image.width * scale))), max(1, int(round(image.height * scale)))),
+        Image.Resampling.LANCZOS,
+    )
+
+    canvas = Image.new("RGB", (width, height), color=background_color)
+    left = max(0, (width - resized.width) // 2)
+    top = max(0, (height - resized.height) // 2)
+    canvas.paste(resized, (left, top))
+    return canvas
+
+
+def _fit_tile_image(
+    image: Image.Image,
+    width: int,
+    height: int,
+    fitting_mode: CoverCollageFittingMode,
+    background_color: tuple[int, int, int],
+) -> Image.Image:
+    if fitting_mode == CoverCollageFittingMode.CONTAIN:
+        return _resize_to_contain(image, width, height, background_color)
+    return _resize_to_cover(image, width, height)
+
+
+def _build_feature_spread_tile_rects() -> tuple[CoverCollageTileRect, ...]:
+    """Return feature spread geometry separately from placement for easy future gap tuning."""
+    column_width = 1 / 4
+    row_height = 1 / 3
+
+    return (
+        CoverCollageTileRect(
+            0 * column_width,
+            0 * row_height,
+            2 * column_width,
+            2 * row_height,
+            role="feature",
+        ),
+        CoverCollageTileRect(
+            2 * column_width,
+            0 * row_height,
+            2 * column_width,
+            2 * row_height,
+            role="feature",
+        ),
+        CoverCollageTileRect(0 * column_width, 2 * row_height, 1 * column_width, 1 * row_height, role="bottom"),
+        CoverCollageTileRect(1 * column_width, 2 * row_height, 1 * column_width, 1 * row_height, role="bottom"),
+        CoverCollageTileRect(2 * column_width, 2 * row_height, 1 * column_width, 1 * row_height, role="bottom"),
+        CoverCollageTileRect(3 * column_width, 2 * row_height, 1 * column_width, 1 * row_height, role="bottom"),
+    )
+
+
+# Keep enum values, internal names, and display labels together so the API and UI can expose
+# the same template identifiers without drifting. Templates should only set tile-level
+# fitting overrides when they intentionally need behavior that differs from the request-level
+# `image_fit`; feature-spread now inherits the collage default so its large tiles do not
+# silently reintroduce letterboxing.
+TEMPLATE_REGISTRY: dict[CoverCollageTemplate, CoverCollageTemplateDefinition] = {
+    CoverCollageTemplate.RANDOMIZED_GRID: CoverCollageTemplateDefinition(
+        name="randomized_grid",
+        display_name="Randomized grid",
+        tiles=(
+            CoverCollageTileRect(0.0, 0.0, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(1 / 3, 0.0, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(2 / 3, 0.0, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(0.0, 1 / 3, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(1 / 3, 1 / 3, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(2 / 3, 1 / 3, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(0.0, 2 / 3, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(1 / 3, 2 / 3, 1 / 3, 1 / 3, role="grid"),
+            CoverCollageTileRect(2 / 3, 2 / 3, 1 / 3, 1 / 3, role="grid"),
+        ),
+    ),
+    CoverCollageTemplate.FEATURE_SPREAD: CoverCollageTemplateDefinition(
+        name="feature_spread",
+        display_name="Feature spread",
+        tiles=_build_feature_spread_tile_rects(),
+    ),
+    CoverCollageTemplate.CENTER_STAGE: CoverCollageTemplateDefinition(
+        name="center_stage",
+        display_name="Center stage",
+        tiles=(
+            CoverCollageTileRect(1 / 4, 0.0, 2 / 4, 1.0, role="feature"),
+            CoverCollageTileRect(0.0, 0.0, 1 / 4, 1 / 3, role="side"),
+            CoverCollageTileRect(0.0, 1 / 3, 1 / 4, 1 / 3, role="side"),
+            CoverCollageTileRect(0.0, 2 / 3, 1 / 4, 1 / 3, role="side"),
+            CoverCollageTileRect(3 / 4, 0.0, 1 / 4, 1 / 3, role="side"),
+            CoverCollageTileRect(3 / 4, 1 / 3, 1 / 4, 1 / 3, role="side"),
+            CoverCollageTileRect(3 / 4, 2 / 3, 1 / 4, 1 / 3, role="side"),
+        ),
+    ),
+}
+
+COVER_COLLAGE_TEMPLATE_OPTIONS: tuple[tuple[str, str, str], ...] = tuple(
+    (template.value, definition.name, definition.display_name)
+    for template, definition in TEMPLATE_REGISTRY.items()
+)
+
+
+def _resolve_layout_template(
+    page_width: int,
+    page_height: int,
+    template: CoverCollageTemplate,
+) -> CoverCollageLayoutTemplate:
+    definition = TEMPLATE_REGISTRY[template]
+    tiles: list[CoverCollageTile] = []
+    for tile_rect in definition.tiles:
+        left = int(round(page_width * tile_rect.x))
+        top = int(round(page_height * tile_rect.y))
+        right = int(round(page_width * (tile_rect.x + tile_rect.width)))
+        bottom = int(round(page_height * (tile_rect.y + tile_rect.height)))
+        tiles.append(
+            CoverCollageTile(
+                x=left,
+                y=top,
+                width=max(1, min(page_width, right) - left),
+                height=max(1, min(page_height, bottom) - top),
+                role=tile_rect.role,
+                fitting_mode=tile_rect.fitting_mode or definition.default_fitting_mode,
+            )
+        )
+
+    return CoverCollageLayoutTemplate(name=definition.name, tiles=tiles)
+
+
+def _build_tile_image_assignments(
+    image_paths: Sequence[str],
+    slot_count: int,
+    rng: random.Random,
+) -> tuple[list[str], list[str]]:
+    readable_paths: list[str] = []
+    skipped_files: list[str] = []
+
+    for image_path in image_paths:
+        try:
+            with Image.open(image_path) as source_image:
+                source_image.verify()
+        except (FileNotFoundError, PermissionError, OSError, UnidentifiedImageError, ValueError) as exc:
+            skipped_files.append(image_path)
+            logger.warning("Skipping unreadable image '%s': %s", image_path, exc)
+            continue
+
+        readable_paths.append(image_path)
+
+    if not readable_paths:
+        return [], skipped_files
+
+    if len(readable_paths) >= slot_count:
+        assignments = rng.sample(readable_paths, k=slot_count)
+        rng.shuffle(assignments)
+        return assignments, skipped_files
+
+    suffix_by_path = {path: _parse_trailing_numeric_token(path) for path in readable_paths}
+    assignments = []
+    previous_path: str | None = None
+    for _ in range(slot_count):
+        assignments.append(_choose_next_assignment(readable_paths, assignments, previous_path, suffix_by_path, rng))
+        previous_path = assignments[-1]
+
+    return assignments, skipped_files
+
+
+def _parse_trailing_numeric_token(image_path: str) -> int | None:
+    match = re.search(r"(\d+)$", Path(image_path).stem)
+    if match is None:
+        return None
+    return int(match.group(1))
+
+
+def _is_adjacent_sequence(previous_path: str | None, candidate_path: str, suffix_by_path: dict[str, int | None]) -> bool:
+    if previous_path is None:
+        return False
+
+    previous_suffix = suffix_by_path.get(previous_path)
+    candidate_suffix = suffix_by_path.get(candidate_path)
+    if previous_suffix is None or candidate_suffix is None:
+        return False
+    return abs(candidate_suffix - previous_suffix) == 1
+
+
+def _choose_next_assignment(
+    readable_paths: Sequence[str],
+    assignments: Sequence[str],
+    previous_path: str | None,
+    suffix_by_path: dict[str, int | None],
+    rng: random.Random,
+) -> str:
+    if not assignments:
+        return rng.choice(list(readable_paths))
+
+    non_repeating = [path for path in readable_paths if path != previous_path]
+    non_adjacent = [path for path in non_repeating if not _is_adjacent_sequence(previous_path, path, suffix_by_path)]
+
+    candidate_pool = non_adjacent or non_repeating or list(readable_paths)
+    return rng.choice(candidate_pool)
+
+
+def compose_cover_collage(
+    image_paths: Sequence[str],
+    page_width: float,
+    page_height: float,
+    rng: random.Random | None = None,
+    fitting_mode: CoverCollageFittingMode | str = CoverCollageFittingMode.COVER,
+    template: CoverCollageTemplate | str = CoverCollageTemplate.RANDOMIZED_GRID,
+    *,
+    background_clean_mode: BackgroundCleanMode | str = BackgroundCleanMode.OFF,
+    background_tolerance: int = DEFAULT_TOLERANCE,
+    background_feather: int = 1,
+) -> tuple[list[Image.Image], CoverCollageSummary]:
+    canvas_width = int(round(page_width))
+    canvas_height = int(round(page_height))
+    if canvas_width <= 0 or canvas_height <= 0:
+        raise ValueError("Page width and height must be greater than zero.")
+
+    fitting_mode = CoverCollageFittingMode(fitting_mode)
+    template = CoverCollageTemplate(template)
+    rng = rng or random.Random()
+    layout_template = _resolve_layout_template(canvas_width, canvas_height, template)
+    selected_paths, skipped_files = _build_tile_image_assignments(image_paths, layout_template.slot_count, rng)
+
+    normalized_clean_mode = BackgroundCleanMode(str(background_clean_mode))
+    collage = Image.new("RGB", (canvas_width, canvas_height), color=BACKGROUND_COLOR)
+
+    placed_count = 0
+    cleaned_count = 0
+
+    for tile, image_path in zip(layout_template.tiles, selected_paths):
+        image = _load_image_rgb(image_path)
+        if normalized_clean_mode is not BackgroundCleanMode.OFF:
+            image, clean_result = clean_background(
+                image,
+                mode=normalized_clean_mode,
+                tolerance=background_tolerance,
+                feather=background_feather,
+                matte=BACKGROUND_COLOR,
+            )
+            if clean_result.cleaned:
+                cleaned_count += 1
+            if image.mode != "RGB":
+                image = flatten_onto(image, BACKGROUND_COLOR)
+        tile_fitting_mode = tile.fitting_mode or fitting_mode
+        collage.paste(
+            _fit_tile_image(image, tile.width, tile.height, tile_fitting_mode, BACKGROUND_COLOR),
+            (tile.x, tile.y),
+        )
+        placed_count += 1
+
+    summary = CoverCollageSummary(
+        total_input_files=len(image_paths),
+        total_images_placed=placed_count,
+        total_images_skipped=len(skipped_files),
+        output_created=placed_count > 0,
+        skipped_files=[Path(path).name for path in skipped_files],
+        background_cleaned=cleaned_count,
+    )
+
+    pages = [collage] if placed_count > 0 else []
+    return pages, summary

pasteup/services/exporter.py

@@ -0,0 +1,113 @@
+"""Service for exporting generated outputs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Sequence
+
+from PIL import Image
+
+from mullion import DEFAULT_DPI, validate_dpi
+
+
+ExportFormat = Literal["PNG", "JPG"]
+PathMode = Literal["relative", "absolute"]
+
+
+def _next_available_index(
+    output_dir: Path,
+    prefix: str,
+    extension: str,
+    start_index: int = 1,
+) -> int:
+    """Find the next available sequential page index for conflict-safe exports."""
+    index = start_index
+    while (output_dir / f"{prefix}_{index:03d}.{extension}").exists():
+        index += 1
+    return index
+
+
+def _save_image(
+    page: Image.Image,
+    destination: Path,
+    export_format: ExportFormat,
+    *,
+    dpi: int = DEFAULT_DPI,
+) -> None:
+    """Save a single page with format-aware options.
+
+    ``dpi`` is written into the file's metadata (a ``pHYs`` chunk for PNG, a
+    JFIF density for JPEG). Without it a 3000x4000 export carries no resolution
+    at all, so print software falls back to 72 DPI and reads the page as
+    41.7x55.6in instead of 10x13.3in — the same pixels, described as a poster.
+    """
+    resolution = (dpi, dpi)
+
+    if export_format == "PNG":
+        page.save(
+            destination,
+            format="PNG",
+            optimize=True,
+            compress_level=6,
+            dpi=resolution,
+        )
+        return
+
+    # JPEG does not support alpha channels.
+    page.convert("RGB").save(
+        destination,
+        format="JPEG",
+        quality=95,
+        optimize=True,
+        subsampling=0,
+        dpi=resolution,
+    )
+
+
+def export_pages(
+    pages: Sequence[Image.Image],
+    output_dir: str | Path,
+    export_format: ExportFormat,
+    *,
+    path_mode: PathMode = "relative",
+    filename_prefix: str = "page",
+    dpi: int = DEFAULT_DPI,
+) -> list[str]:
+    """Export composed pages with sequential names and conflict-safe behavior.
+
+    Filenames are generated as `<prefix>_001.<ext>`, `<prefix>_002.<ext>`, etc.
+    The default prefix keeps standard exports as `page_001.<ext>`, `page_002.<ext>`, etc.
+    If files already exist, numbering continues from the next available index
+    rather than overwriting existing files.
+
+    ``dpi`` is stamped into every exported file so the page reports its intended
+    physical size to print software rather than defaulting to 72 DPI.
+    """
+    target_dir = Path(output_dir).expanduser()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    normalized_format = export_format.upper()
+    if normalized_format not in {"PNG", "JPG"}:
+        raise ValueError("Unsupported export format. Use 'PNG' or 'JPG'.")
+    if not filename_prefix:
+        raise ValueError("filename_prefix must be a non-empty string.")
+    resolved_dpi = validate_dpi(dpi)
+
+    extension = "png" if normalized_format == "PNG" else "jpg"
+    current_index = _next_available_index(target_dir, filename_prefix, extension)
+
+    saved_paths: list[str] = []
+    for page in pages:
+        output_path = target_dir / f"{filename_prefix}_{current_index:03d}.{extension}"
+        _save_image(page, output_path, normalized_format, dpi=resolved_dpi)
+
+        if path_mode == "absolute":
+            saved_paths.append(str(output_path.resolve()))
+        elif path_mode == "relative":
+            saved_paths.append(str(output_path))
+        else:
+            raise ValueError("Unsupported path_mode. Use 'relative' or 'absolute'.")
+
+        current_index += 1
+
+    return saved_paths

pasteup/services/folder_scanner.py

@@ -0,0 +1,164 @@
+"""Service for scanning image folders."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"}
+DEFAULT_SAMPLE_SIZE = 5
+IMAGES_PER_PAGE_ESTIMATE = 12
+# Batch scanning and validation must reject generated-output folders so the UI only
+# offers real source bundles. Keep this list here alongside the discovery helpers to
+# avoid reintroducing output directories such as `---Created---` into batch selection.
+EXCLUDED_GENERATED_FOLDER_NAMES = frozenset({"---Created---"})
+
+
+def scan_folder(folder_path: str, sample_size: int = DEFAULT_SAMPLE_SIZE) -> dict[str, object]:
+    """Scan a folder for supported image files.
+
+    The scan is non-recursive and only inspects files directly inside
+    ``folder_path``.
+    """
+    normalized_sample_size = max(0, sample_size)
+
+    # A blank path would otherwise resolve to the server's working directory and
+    # scan that instead.
+    if isinstance(folder_path, str) and not folder_path.strip():
+        return _build_response(
+            valid=False,
+            image_count=0,
+            sample_files=[],
+            estimated_pages=0,
+            available_subfolders=[],
+            message="Enter a folder path to scan.",
+        )
+
+    try:
+        folder = resolve_folder_path(folder_path)
+    except (TypeError, ValueError):
+        return _build_response(
+            valid=False,
+            image_count=0,
+            sample_files=[],
+            estimated_pages=0,
+            available_subfolders=[],
+            message="Invalid folder path.",
+        )
+
+    if not folder.exists():
+        return _build_response(
+            valid=False,
+            image_count=0,
+            sample_files=[],
+            estimated_pages=0,
+            available_subfolders=[],
+            message=f"Folder not found: {folder}. Check the path for typos.",
+        )
+
+    if not folder.is_dir():
+        return _build_response(
+            valid=False,
+            image_count=0,
+            sample_files=[],
+            estimated_pages=0,
+            available_subfolders=[],
+            message=f"Path is not a folder: {folder}",
+        )
+
+    image_names = [path.name for path in list_supported_image_paths(folder)]
+
+    image_count = len(image_names)
+    sample_files = image_names[:normalized_sample_size]
+
+    if image_count == 0:
+        available_subfolders = list_child_folder_paths(folder)
+        if available_subfolders:
+            return _build_response(
+                valid=False,
+                image_count=0,
+                sample_files=[],
+                estimated_pages=0,
+                available_subfolders=available_subfolders,
+                message=(
+                    "No supported image files were found at the top level, "
+                    "but direct subfolders are available to scan."
+                ),
+            )
+
+        return _build_response(
+            valid=False,
+            image_count=0,
+            sample_files=[],
+            estimated_pages=0,
+            available_subfolders=[],
+            message="No supported image files found (.jpg, .jpeg, .png, .webp).",
+        )
+
+    estimated_pages = image_count // IMAGES_PER_PAGE_ESTIMATE
+    return _build_response(
+        valid=True,
+        image_count=image_count,
+        sample_files=sample_files,
+        estimated_pages=estimated_pages,
+        available_subfolders=[],
+        message=f"Found {image_count} supported image file(s).",
+    )
+
+
+def _build_response(
+    *,
+    valid: bool,
+    image_count: int,
+    sample_files: list[str],
+    estimated_pages: int,
+    available_subfolders: list[dict[str, str]],
+    message: str,
+) -> dict[str, object]:
+    return {
+        "valid": valid,
+        "image_count": image_count,
+        "sample_files": sample_files,
+        "estimated_pages": estimated_pages,
+        "available_subfolders": available_subfolders,
+        "message": message,
+    }
+
+
+def resolve_folder_path(folder_path: str) -> Path:
+    return Path(folder_path).expanduser().resolve(strict=False)
+
+
+def list_supported_image_paths(folder: Path, *, recursive: bool = False) -> list[Path]:
+    iterator: Iterable[Path]
+    if recursive:
+        iterator = (item for item in folder.rglob("*") if item.is_file())
+    else:
+        iterator = folder.iterdir()
+
+    return sorted(
+        [
+            item
+            for item in iterator
+            if item.is_file() and item.suffix.lower() in SUPPORTED_EXTENSIONS
+        ],
+        key=lambda path: (path.name.lower(), path.name, str(path)),
+    )
+
+
+def is_generated_output_folder(folder: Path) -> bool:
+    return folder.name in EXCLUDED_GENERATED_FOLDER_NAMES
+
+
+def list_child_folder_paths(folder: Path) -> list[dict[str, str]]:
+    return [
+        {"display_name": path.name, "full_path": str(path)}
+        for path in sorted(
+            (
+                item.resolve(strict=False)
+                for item in folder.iterdir()
+                if item.is_dir() and not is_generated_output_folder(item)
+            ),
+            key=lambda path: (path.name.lower(), path.name, str(path)),
+        )
+    ]