pasteup 0.1.0__py3-none-any.whl

pasteup/services/grid_composer.py

@@ -0,0 +1,199 @@
+"""Service for composing 4x3 image grids."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from pathlib import Path
+from typing import Sequence
+
+from PIL import Image, UnidentifiedImageError
+
+from mullion import (
+    DEFAULT_TOLERANCE,
+    BackgroundCleanMode,
+    clean_background,
+    flatten_onto,
+    open_path,
+)
+
+GRID_COLUMNS = 4
+GRID_ROWS = 3
+CELLS_PER_PAGE = GRID_COLUMNS * GRID_ROWS
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class ComposeSummary:
+    """Summary of a grid composition run."""
+
+    total_input_files: int
+    total_images_placed: int
+    total_images_skipped: int
+    pages_generated: int
+    skipped_files: list[str]
+    total_images_dropped: int = 0
+    background_cleaned: int = 0
+
+    @property
+    def user_message(self) -> str:
+        """Human-friendly summary for API/UI responses."""
+        parts = [
+            f"Generated {self.pages_generated} page(s) with "
+            f"{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).")
+        if self.total_images_dropped:
+            # This used to happen silently, which read as images going missing.
+            parts.append(
+                f"Left out {self.total_images_dropped} trailing image(s) that did not "
+                f"fill a complete {GRID_COLUMNS}x{GRID_ROWS} page — enable "
+                f"'include partial page' to render them."
+            )
+        return " ".join(parts)
+
+
+def _create_canvas(page_width: float, page_height: float) -> Image.Image:
+    """Create a white page canvas from user settings."""
+    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.")
+    return Image.new("RGB", (canvas_width, canvas_height), color="white")
+
+
+def _compute_cell_geometry(
+    page_width: float,
+    page_height: float,
+    margin: float,
+    gap: float,
+) -> tuple[float, float]:
+    """Compute cell geometry for a fixed 4x3 grid."""
+    cell_width = (page_width - 2 * margin - (GRID_COLUMNS - 1) * gap) / GRID_COLUMNS
+    cell_height = (page_height - 2 * margin - (GRID_ROWS - 1) * gap) / GRID_ROWS
+    if cell_width <= 0 or cell_height <= 0:
+        raise ValueError(
+            "Computed cell size is invalid. "
+            "Adjust page size, margin, or gap values."
+        )
+    return cell_width, cell_height
+
+
+def _load_image_rgb(image_path: str) -> Image.Image:
+    """Load an image as RGB, raising on unreadable/corrupt content.
+
+    Delegates to :mod:`mullion` so transparent PNGs land on
+    white rather than black, and EXIF-rotated photos land upright. See that
+    module for why a bare ``convert("RGB")`` is wrong here.
+    """
+    return open_path(image_path)
+
+
+def compose_image_grids(
+    image_paths: Sequence[str],
+    page_width: float,
+    page_height: float,
+    margin: float,
+    gap: float,
+    *,
+    background_clean_mode: BackgroundCleanMode | str = BackgroundCleanMode.OFF,
+    background_tolerance: int = DEFAULT_TOLERANCE,
+    background_feather: int = 1,
+    include_partial_page: bool = False,
+) -> tuple[list[Image.Image], ComposeSummary]:
+    """Compose input images into one or more white 4x3 grid pages.
+
+    Images are proportionally resized to fit in each cell without distortion, then
+    centered in their assigned cell. Unreadable image files are skipped and logged.
+
+    Trailing images that do not complete a full 12-cell page are left out unless
+    ``include_partial_page`` is set, in which case the final page is rendered
+    with its unused cells left white. Either way the count is reported on the
+    summary rather than being dropped silently.
+
+    ``background_clean_mode`` runs each tile through
+    :func:`mullion.clean_background` before it is
+    placed, so an off-white source background blends into the page instead of
+    reading as a faint rectangle around the tile.
+    """
+    cell_width, cell_height = _compute_cell_geometry(page_width, page_height, margin, gap)
+
+    normalized_clean_mode = BackgroundCleanMode(str(background_clean_mode))
+
+    pages: list[Image.Image] = []
+    skipped_files: list[str] = []
+    placed_count = 0
+    cleaned_count = 0
+
+    current_page = _create_canvas(page_width, page_height)
+    slot_index = 0
+
+    for image_path in image_paths:
+        try:
+            image = _load_image_rgb(image_path)
+        except (FileNotFoundError, PermissionError, OSError, UnidentifiedImageError, ValueError) as exc:
+            skipped_files.append(image_path)
+            logger.warning("Skipping unreadable image '%s': %s", image_path, exc)
+            continue
+
+        if normalized_clean_mode is not BackgroundCleanMode.OFF:
+            image, clean_result = clean_background(
+                image,
+                mode=normalized_clean_mode,
+                tolerance=background_tolerance,
+                feather=background_feather,
+            )
+            if clean_result.cleaned:
+                cleaned_count += 1
+            # A transparent-mode result still has to land on the opaque page.
+            if image.mode != "RGB":
+                image = flatten_onto(image)
+
+        row = slot_index // GRID_COLUMNS
+        col = slot_index % GRID_COLUMNS
+
+        cell_x = margin + col * (cell_width + gap)
+        cell_y = margin + row * (cell_height + gap)
+
+        scale = min(cell_width / image.width, cell_height / image.height)
+        resized_width = max(1, int(round(image.width * scale)))
+        resized_height = max(1, int(round(image.height * scale)))
+
+        resized_image = image.resize((resized_width, resized_height), Image.Resampling.LANCZOS)
+
+        paste_x = int(round(cell_x + (cell_width - resized_width) / 2))
+        paste_y = int(round(cell_y + (cell_height - resized_height) / 2))
+        current_page.paste(resized_image, (paste_x, paste_y))
+
+        placed_count += 1
+        slot_index += 1
+
+        if slot_index == CELLS_PER_PAGE:
+            pages.append(current_page)
+            current_page = _create_canvas(page_width, page_height)
+            slot_index = 0
+
+    dropped_count = 0
+    if slot_index > 0:
+        if include_partial_page:
+            # Unused cells keep the canvas white, which is what the README has
+            # always described.
+            pages.append(current_page)
+        else:
+            placed_count -= slot_index
+            dropped_count = slot_index
+
+    summary = ComposeSummary(
+        total_input_files=len(image_paths),
+        total_images_placed=max(0, placed_count),
+        total_images_skipped=len(skipped_files),
+        pages_generated=len(pages),
+        skipped_files=[Path(path).name for path in skipped_files],
+        total_images_dropped=dropped_count,
+        background_cleaned=cleaned_count,
+    )
+
+    return pages, summary

pasteup/services/image_batcher.py

@@ -0,0 +1,21 @@
+"""Service for grouping images into page-sized batches."""
+
+from __future__ import annotations
+
+
+IMAGES_PER_PAGE = 12
+
+
+def build_image_batches(image_paths: list[str]) -> list[list[str]]:
+    """Split image paths into ordered full-page batches using a fixed 4x3 layout."""
+    full_page_count = len(image_paths) // IMAGES_PER_PAGE
+    return [
+        image_paths[index : index + IMAGES_PER_PAGE]
+        for index in range(0, full_page_count * IMAGES_PER_PAGE, IMAGES_PER_PAGE)
+    ]
+
+
+def estimate_page_count(image_count: int) -> int:
+    """Return the number of full 4x3 pages that can be generated."""
+    normalized_count = max(0, image_count)
+    return normalized_count // IMAGES_PER_PAGE

pasteup/services/video_exporter.py

@@ -0,0 +1,227 @@
+"""Service for building preview videos from exported page images."""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from PIL import Image
+
+VideoTransition = Literal["none", "crossfade", "flip"]
+
+# A conventional frame rate, so players and upload pipelines handle the file.
+# Slideshow timing is expressed as frame counts, not by slowing the rate down.
+FRAME_RATE = 30
+# A preview, not a print master: listing sites show video at about 1080p, and
+# full print-size frames take several times longer to encode and can exceed
+# what H.264 decoders accept. Smaller pages are never scaled up.
+MAX_VIDEO_SIDE = 1920
+# Transitions are short and fixed, and never take more than a third of a page's
+# share of the video, so the pages fill it rather than the blends between them.
+MAX_TRANSITION_SECONDS = 0.5
+_XFADE_TRANSITIONS = {"crossfade": "fade", "flip": "squeezev"}
+
+
+@dataclass(frozen=True, slots=True)
+class _Timeline:
+    total_frames: int
+    # Frames each page's clip runs, including its overlap with the next page.
+    clip_frames: int
+    # The last clip also absorbs the rounding remainder, so the total is exact.
+    last_clip_frames: int
+    transition_frames: int
+
+
+def build_preview_video(
+    page_paths: list[str],
+    output_dir: str | Path,
+    duration_seconds: float,
+    transition: str,
+    filename: str,
+) -> str:
+    """Build an MP4 preview from exported page images.
+
+    Args:
+        page_paths: Paths to exported page image files.
+        output_dir: Directory where the output MP4 should be written.
+        duration_seconds: Desired total video duration.
+        transition: Transition mode ("none", "crossfade", "flip").
+        filename: Output MP4 filename.
+
+    Returns:
+        The absolute output path for the generated MP4.
+
+    Raises:
+        ValueError: If pages are empty, duration is invalid, paths are invalid,
+            or transition mode is unsupported.
+        RuntimeError: If ffmpeg is unavailable or video encoding fails.
+    """
+    validated_page_paths = _validate_page_paths(page_paths)
+    # ffmpeg overwrites its output, so the video must not land outside output_dir.
+    if filename in {"", ".", ".."} or Path(filename).name != filename:
+        raise ValueError("filename must be a plain file name inside output_dir.")
+    if duration_seconds <= 0:
+        raise ValueError("duration_seconds must be greater than 0.")
+
+    if transition not in {"none", "crossfade", "flip"}:
+        raise ValueError("transition must be one of: 'none', 'crossfade', 'flip'.")
+
+    ffmpeg_binary = shutil.which("ffmpeg")
+    if ffmpeg_binary is None:
+        raise RuntimeError("ffmpeg is required to export preview videos but was not found on PATH")
+
+    target_dir = Path(output_dir).expanduser()
+    target_dir.mkdir(parents=True, exist_ok=True)
+    output_path = target_dir / filename
+
+    timeline = _plan_timeline(len(validated_page_paths), duration_seconds, transition)
+    width, height = _video_frame_size(validated_page_paths[0])
+
+    command = [ffmpeg_binary, "-y", "-hide_banner", "-loglevel", "error"]
+    for index, page_path in enumerate(validated_page_paths):
+        # One decoded frame a second is plenty for a still; the fps filter
+        # repeats it, and trim cuts the clip to its exact frame count.
+        clip_seconds = _clip_frames(timeline, index, len(validated_page_paths)) / FRAME_RATE
+        command += ["-loop", "1", "-framerate", "1", "-t", f"{clip_seconds + 1:.6f}", "-i", str(page_path)]
+
+    filter_graph, output_label = _build_filter_graph(
+        timeline,
+        page_count=len(validated_page_paths),
+        xfade_transition=_XFADE_TRANSITIONS.get(transition),
+        width=width,
+        height=height,
+    )
+    command += [
+        "-filter_complex",
+        filter_graph,
+        "-map",
+        f"[{output_label}]",
+        "-frames:v",
+        str(timeline.total_frames),
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-r",
+        str(FRAME_RATE),
+        "-movflags",
+        "+faststart",
+        str(output_path),
+    ]
+
+    try:
+        subprocess.run(command, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as exc:
+        raise RuntimeError(f"ffmpeg failed to encode the preview video: {_first_error_line(exc.stderr)}") from exc
+    except OSError as exc:
+        raise RuntimeError(f"ffmpeg could not be started: {exc}") from exc
+
+    return str(output_path.resolve())
+
+
+def _validate_page_paths(page_paths: list[str]) -> list[Path]:
+    if not page_paths:
+        raise ValueError("page_paths cannot be empty.")
+
+    validated_paths = sorted(Path(path).expanduser() for path in page_paths)
+    missing_paths = [str(path) for path in validated_paths if not path.exists()]
+    if missing_paths:
+        raise ValueError(f"One or more page_paths do not exist: {', '.join(missing_paths)}")
+
+    return validated_paths
+
+
+def _plan_timeline(page_count: int, duration_seconds: float, transition: str) -> _Timeline:
+    # Every page needs at least one frame, even if that runs past the duration.
+    total_frames = max(page_count, round(duration_seconds * FRAME_RATE))
+
+    transition_frames = 0
+    if transition != "none" and page_count > 1:
+        transition_frames = min(
+            round(MAX_TRANSITION_SECONDS * FRAME_RATE),
+            total_frames // (page_count * 3),
+        )
+
+    # Consecutive clips overlap by one transition, so together they cover more
+    # frames than the video holds.
+    covered_frames = total_frames + (page_count - 1) * transition_frames
+    clip_frames = covered_frames // page_count
+    return _Timeline(
+        total_frames=total_frames,
+        clip_frames=clip_frames,
+        last_clip_frames=clip_frames + covered_frames % page_count,
+        transition_frames=transition_frames,
+    )
+
+
+def _clip_frames(timeline: _Timeline, index: int, page_count: int) -> int:
+    return timeline.last_clip_frames if index == page_count - 1 else timeline.clip_frames
+
+
+def _video_frame_size(first_page: Path) -> tuple[int, int]:
+    try:
+        with Image.open(first_page) as page:
+            width, height = page.size
+    except OSError as exc:
+        raise RuntimeError(f"Could not read page {first_page.name}: {exc}") from exc
+
+    scale = min(1.0, MAX_VIDEO_SIDE / max(width, height))
+    # yuv420p stores colour at half resolution, so libx264 refuses odd sizes.
+    return max(2, int(width * scale) // 2 * 2), max(2, int(height * scale) // 2 * 2)
+
+
+def _build_filter_graph(
+    timeline: _Timeline,
+    *,
+    page_count: int,
+    xfade_transition: str | None,
+    width: int,
+    height: int,
+) -> tuple[str, str]:
+    # Fit each page into the frame without distortion; pages from one run share
+    # a size, so the padding only shows if a caller mixes sizes.
+    fit = (
+        f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
+        f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2:color=white"
+    )
+    parts = [
+        (
+            f"[{index}:v]{fit},setsar=1,format=yuv420p,fps={FRAME_RATE},"
+            f"trim=end_frame={_clip_frames(timeline, index, page_count)},setpts=PTS-STARTPTS[p{index}]"
+        )
+        for index in range(page_count)
+    ]
+
+    if page_count == 1:
+        return ";".join(parts), "p0"
+
+    if xfade_transition is None or timeline.transition_frames == 0:
+        clips = "".join(f"[p{index}]" for index in range(page_count))
+        parts.append(f"{clips}concat=n={page_count}:v=1:a=0[video]")
+        return ";".join(parts), "video"
+
+    transition_seconds = timeline.transition_frames / FRAME_RATE
+    current_label = "p0"
+    for index in range(1, page_count):
+        offset_seconds = index * (timeline.clip_frames - timeline.transition_frames) / FRAME_RATE
+        output_label = f"x{index}"
+        parts.append(
+            f"[{current_label}][p{index}]xfade=transition={xfade_transition}:"
+            f"duration={transition_seconds:.6f}:offset={offset_seconds:.6f}[{output_label}]"
+        )
+        current_label = output_label
+
+    return ";".join(parts), current_label
+
+
+def _first_error_line(stderr: str | None) -> str:
+    """ffmpeg reports the specific failure first and generic wrappers after it."""
+    for line in (stderr or "").splitlines():
+        if line.strip():
+            # Drop the memory address ffmpeg prints beside each component's name.
+            return re.sub(r" @ 0x[0-9a-f]+", "", line.strip())
+    return "no error output"

pasteup/shortcut.py

@@ -0,0 +1,97 @@
+"""`pasteup --shortcut`: a launcher that starts Pasteup with a double-click.
+
+The launcher runs this installation's Python by its full path, so it works
+without a terminal or a PATH set up for `pasteup`. Run the command again after
+moving or reinstalling Pasteup somewhere else.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+NOTE = "Starts Pasteup. Made by `pasteup --shortcut`; run that again if Pasteup moves."
+
+
+def create_shortcut(platform: str | None = None) -> str:
+    """Write a launcher for this platform and return a sentence saying where it is."""
+    platform = platform or sys.platform
+
+    if platform == "darwin":
+        # Double-clicking a .command file runs it in Terminal.
+        path = _existing_dir(Path.home() / "Desktop") / "Pasteup.command"
+        _write(path, f"#!/bin/sh\n# {NOTE}\nexec {shlex.quote(sys.executable)} -m pasteup\n", executable=True)
+        return f"Made {path}. Double-click it to start Pasteup."
+
+    if platform == "win32":
+        path = _windows_desktop() / "Pasteup.bat"
+        python = sys.executable.replace("%", "%%")
+        # chcp 65001 makes cmd read the rest as UTF-8, for a path with accents in
+        # it; the pause keeps an error on screen instead of closing the window.
+        script = (
+            f'@echo off\r\nchcp 65001 >nul\r\nrem {NOTE}\r\n"{python}" -m pasteup\r\nif errorlevel 1 pause\r\n'
+        )
+        _write(path, script)
+        return f"Made {path}. Double-click it to start Pasteup."
+
+    data_home = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share")
+    path = data_home / "applications" / "pasteup.desktop"
+    _write(path, _desktop_entry(), executable=True)
+    return f"Added Pasteup to your applications menu ({path})."
+
+
+def _desktop_entry() -> str:
+    lines = [
+        "[Desktop Entry]",
+        "Type=Application",
+        "Name=Pasteup",
+        "Comment=Turn a folder of clip art into listing images",
+        f"Exec={_desktop_exec_argument(sys.executable)} -m pasteup",
+        "Terminal=true",
+        "Categories=Graphics;",
+    ]
+    icon = Path(str(files("pasteup") / "static" / "favicon.svg"))
+    if icon.is_file():
+        lines.append(f"Icon={icon}")
+    return "\n".join(lines) + "\n"
+
+
+def _desktop_exec_argument(value: str) -> str:
+    """Quote one Exec argument as the desktop entry specification requires."""
+    for reserved in ("\\", '"', "`", "$"):
+        value = value.replace(reserved, "\\" + reserved)
+    # "%" starts a field code, and the value as a whole escapes backslashes again.
+    return f'"{value}"'.replace("%", "%%").replace("\\", "\\\\")
+
+
+def _windows_desktop() -> Path:
+    # The Desktop folder can be moved, most often into OneDrive; the registry
+    # says where it is now.
+    try:
+        import winreg
+
+        with winreg.OpenKey(
+            winreg.HKEY_CURRENT_USER, r"Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders"
+        ) as key:
+            desktop = Path(os.path.expandvars(winreg.QueryValueEx(key, "Desktop")[0]))
+        if desktop.is_dir():
+            return desktop
+    except (ImportError, OSError):
+        pass
+    return _existing_dir(Path.home() / "Desktop")
+
+
+def _existing_dir(preferred: Path) -> Path:
+    return preferred if preferred.is_dir() else Path.home()
+
+
+def _write(path: Path, content: str, *, executable: bool = False) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # newline="" keeps the line endings written above, CRLF included.
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        handle.write(content)
+    if executable:
+        path.chmod(0o755)