spriteworkflow 0.1.0__py3-none-any.whl

spriteworkflow/__init__.py

@@ -0,0 +1,23 @@
+"""SpriteWorkflow — convert video frames into linear spritesheets.
+
+Provides :func:`extract_frames` (extract frames from video via FFmpeg),
+:func:`create_spritesheet_lineal` (stitch frames into a horizontal
+spritesheet), :func:`remove_background` (chroma-key background removal
+on frames), :func:`create_spritesheet_grid` (arrange frames in a
+rows × columns grid), and :func:`generate_report` (inspect frames and
+produce a JSON validation report).
+"""
+
+from .extractor import extract_frames
+from .spritesheet_lineal import create_spritesheet_lineal
+from .matte import remove_background
+from .spritesheet_grid import create_spritesheet_grid
+from .report import generate_report
+
+__all__ = [
+    "extract_frames",
+    "create_spritesheet_lineal",
+    "remove_background",
+    "create_spritesheet_grid",
+    "generate_report",
+]

spriteworkflow/cli.py

@@ -0,0 +1,202 @@
+"""SpriteWorkflow CLI — build spritesheets from video via the command line.
+
+Usage::
+
+    spriteworkflow build <video> [options]
+
+Subcommands
+-----------
+build       Extract frames (optionally remove background), assemble into a
+            spritesheet, and optionally produce a validation report.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from spriteworkflow import (
+    extract_frames,
+    remove_background,
+    create_spritesheet_lineal,
+    create_spritesheet_grid,
+    generate_report,
+)
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the argument parser for the ``build`` subcommand.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+    """
+    parser = argparse.ArgumentParser(
+        prog="spriteworkflow",
+        description="Convert video frames into linear or grid spritesheets.",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+    build = sub.add_parser("build", help="Build a spritesheet from a video")
+
+    # Positional
+    build.add_argument(
+        "video",
+        help="Path to the input video file",
+    )
+
+    # Output
+    build.add_argument(
+        "--output", "-o",
+        default="spritesheet.png",
+        help="Output spritesheet path (default: %(default)s)",
+    )
+
+    # Layout
+    build.add_argument(
+        "--layout",
+        choices=("lineal", "grid"),
+        default="lineal",
+        help="Spritesheet layout (default: %(default)s)",
+    )
+    build.add_argument(
+        "--columns",
+        type=int,
+        default=None,
+        help="Grid columns — auto-calculated as ceil(sqrt(N)) when not set. "
+             "Only relevant with --layout=grid.",
+    )
+    build.add_argument(
+        "--padding",
+        type=int,
+        default=0,
+        help="Padding pixels between grid cells (default: %(default)s). "
+             "Only relevant with --layout=grid.",
+    )
+
+    # Chroma-key (matte)
+    build.add_argument(
+        "--matte",
+        action="store_true",
+        default=False,
+        help="Enable chroma-key background removal between extraction and "
+             "spritesheet assembly",
+    )
+    build.add_argument(
+        "--bg-color",
+        nargs=3,
+        type=int,
+        default=None,
+        metavar=("R", "G", "B"),
+        help="RGB triplet for chroma-key color, e.g. --bg-color 0 255 0. "
+             "Auto-detected from corner pixels when not set.",
+    )
+    build.add_argument(
+        "--tolerance",
+        type=int,
+        default=30,
+        help="Chroma-key euclidean tolerance (default: %(default)s)",
+    )
+    build.add_argument(
+        "--feather",
+        type=int,
+        default=0,
+        help="Chroma-key feather width in pixels (default: %(default)s)",
+    )
+
+    # Report
+    build.add_argument(
+        "--report-file",
+        default=None,
+        help="Path for JSON validation report (omitted when not set)",
+    )
+
+    # Internal
+    build.add_argument(
+        "--temp-dir",
+        default="temp",
+        help="Temporary directory for extracted frames (default: %(default)s)",
+    )
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main(argv=None) -> None:
+    """CLI entry point.
+
+    Parameters
+    ----------
+    argv : list of str, optional
+        Command-line arguments.  If ``None`` (default), ``sys.argv[1:]`` is
+        read.  Passing an explicit list enables testing without I/O.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # argparse requires a subcommand — safety net for edge cases
+    if args.command != "build":
+        parser.print_help()
+        sys.exit(2)
+
+    try:
+        # ---- Step 1 : Extract frames ------------------------------------
+        print("> Extracting frames from video...")
+        frames = extract_frames(args.video, output_dir=args.temp_dir)
+        print(f"  {len(frames)} frames extracted.")
+
+        # ---- Step 2 (optional) : Remove background ----------------------
+        if args.matte:
+            print("> Removing background via chroma-key...")
+            bg = tuple(args.bg_color) if args.bg_color else None
+            frames = remove_background(
+                frames=frames,
+                bg_color=bg,
+                tolerance=args.tolerance,
+                feather=args.feather,
+                output_dir=str(Path(args.temp_dir) / "matted"),
+            )
+            print(f"  {len(frames)} frames processed.")
+
+        # ---- Step 3 : Build spritesheet ---------------------------------
+        print(f"> Building {args.layout} spritesheet...")
+
+        if args.layout == "grid":
+            sheet = create_spritesheet_grid(
+                frames=frames,
+                columns=args.columns,
+                padding=args.padding,
+                output_file=args.output,
+            )
+        else:
+            sheet = create_spritesheet_lineal(
+                frames=frames,
+                output_file=args.output,
+            )
+
+        print(f"  -> Spritesheet saved: {sheet}")
+
+        # ---- Step 4 (optional) : Generate report ------------------------
+        if args.report_file:
+            print("> Generating validation report...")
+            report = generate_report(
+                frames=frames,
+                spritesheet_path=sheet,
+                output_file=args.report_file,
+            )
+            print(f"  -> Report saved: {report}")
+
+    except (ValueError, FileNotFoundError, NotADirectoryError,
+            RuntimeError, PermissionError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

spriteworkflow/extractor.py

@@ -0,0 +1,64 @@
+from pathlib import Path
+import subprocess
+from spriteworkflow.ffmpeg_manager import get_ffmpeg_path
+import tempfile
+
+def extract_frames(video_name, output_dir="temp"):
+    
+    ffmpeg_path = get_ffmpeg_path()
+    
+    video_path = Path(video_name)
+    
+    if not video_path.exists():
+        raise FileNotFoundError(f"Video file not found: {video_name}")
+    
+    if not video_path.is_file():
+        raise ValueError(f"Path is not a valid file: {video_name}")
+    
+    if video_path.stat().st_size <= 0:
+        raise ValueError(f"Video file is empty: {video_name}")
+    
+    try:
+        with open(video_path, "rb"):
+            pass
+    except PermissionError as e:
+        raise PermissionError(f"Video file is not readable: {video_name}") from e
+        
+    temp_root = Path(output_dir)
+    temp_root.mkdir(parents=True, exist_ok=True)
+    
+    temp_dir = tempfile.mkdtemp(prefix="frames_", dir=temp_root)
+    
+    output_path = Path(temp_dir)
+        
+    frame_pattern = output_path / "frame_%04d.png"
+    
+    command = [
+        ffmpeg_path,
+        "-v",
+        "error",
+        "-i",
+        str(video_path),
+        str(frame_pattern)
+    ]
+    
+    try:
+        subprocess.run(command, check=True, stderr=subprocess.PIPE, text=True)
+    except subprocess.CalledProcessError as e:
+        stderr = e.stderr.strip()
+        raise RuntimeError(f"FFmpeg failed:\n{stderr}") from e
+
+    frames = sorted(output_path.glob("*.png"))
+    
+    if not frames:
+        raise RuntimeError(
+            "No frames were extracted. "
+            "Possible causes:\n"
+            "- Corrupted video\n"
+            "- Unsupported codec\n"
+            "- Zero-duration video\n"
+            "- FFmpeg decoding issue\n"
+            "- Permission problems"
+        )
+    
+    return frames

spriteworkflow/ffmpeg_manager.py

@@ -0,0 +1,9 @@
+import imageio_ffmpeg
+
+def get_ffmpeg_path():
+    try:
+        ffmpeg_path = imageio_ffmpeg.get_ffmpeg_exe()
+    except RuntimeError as e:
+        raise RuntimeError("Failed to initialize FFmpeg automatically.") from e
+
+    return ffmpeg_path

spriteworkflow/matte.py

@@ -0,0 +1,152 @@
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+def remove_background(frames=None, frames_dir=None, bg_color=None, tolerance=30, feather=0, output_dir="matted"):
+    """Remove background from frames via chroma-key (euclidean distance in RGB).
+
+    Parameters
+    ----------
+    frames : list of Path or str, optional
+        List of paths to individual frame images.
+    frames_dir : Path or str, optional
+        Directory containing PNG frames. Mutually exclusive with *frames*.
+    bg_color : tuple of int, optional
+        RGB triplet (0-255 each). If ``None`` it is auto-detected by
+        averaging the four corner pixels of the first frame.
+    tolerance : int
+        Maximum euclidean distance from *bg_color* for a pixel to be
+        considered background (made transparent). Default 30.
+    feather : int
+        Width of the linear feather ramp around *tolerance*. With
+        ``feather=0`` (default) the alpha mask is binary. With
+        ``feather > 0`` pixels whose distance falls inside the ramp
+        ``[tolerance - feather, tolerance + feather]`` get a smoothly
+        interpolated alpha value between 0 and 255.
+    output_dir : Path or str
+        Directory where the processed RGBA PNGs are saved. Created if it
+        does not exist. Default ``"matted"``.
+
+    Returns
+    -------
+    list of Path
+        Sorted list of paths to the generated RGBA PNG files.
+
+    Raises
+    ------
+    ValueError
+        If neither *frames* nor *frames_dir* is provided, if both are
+        provided, if *frames_dir* points to an empty directory, if
+        *bg_color* is not a valid RGB triplet, or if *feather* is not a
+        non-negative integer.
+    FileNotFoundError
+        If *frames_dir* does not exist.
+    NotADirectoryError
+        If *frames_dir* is a file, not a directory.
+    """
+    # ------------------------------------------------------------------
+    # Validación de entrada (mismo estilo que create_spritesheet_lineal)
+    # ------------------------------------------------------------------
+    if frames is None and frames_dir is None:
+        raise ValueError("Either 'frames' or 'frames_dir' must be provided.")
+
+    if frames is not None and frames_dir is not None:
+        raise ValueError("Only one of 'frames' or 'frames_dir' should be provided, not both.")
+
+    if frames_dir is not None:
+        frames_path = Path(frames_dir)
+
+        if not frames_path.exists():
+            raise FileNotFoundError(f"The directory '{frames_dir}' does not exist.")
+
+        if not frames_path.is_dir():
+            raise NotADirectoryError(f"The path '{frames_dir}' is not a directory.")
+
+        frames = sorted(frames_path.glob("*.png"))
+
+    if not frames:
+        raise ValueError("No frames found to process for background removal.")
+
+    # Normalise frame paths
+    frame_paths = [Path(f) for f in frames]
+
+    # ------------------------------------------------------------------
+    # Color de fondo — autodetección o validación
+    # ------------------------------------------------------------------
+    if bg_color is None:
+        bgr = cv2.imread(str(frame_paths[0]), cv2.IMREAD_COLOR)
+        if bgr is None:
+            raise ValueError(f"Cannot read frame '{frame_paths[0]}' with OpenCV.")
+
+        h, w = bgr.shape[:2]
+        corners_bgr = [
+            bgr[0, 0],
+            bgr[0, w - 1],
+            bgr[h - 1, 0],
+            bgr[h - 1, w - 1],
+        ]
+        avg_bgr = np.mean(corners_bgr, axis=0).astype(int)
+        bg_color = tuple(avg_bgr[::-1])  # BGR → RGB
+    else:
+        if not isinstance(bg_color, tuple) or len(bg_color) != 3:
+            raise ValueError("bg_color must be a tuple of 3 integers (R, G, B).")
+
+        if not all(isinstance(c, int) and 0 <= c <= 255 for c in bg_color):
+            raise ValueError("bg_color values must be integers in the range 0-255.")
+
+    # ------------------------------------------------------------------
+    # Validación de feather
+    # ------------------------------------------------------------------
+    if not isinstance(feather, int) or feather < 0:
+        raise ValueError("feather must be a non-negative integer.")
+
+    # ------------------------------------------------------------------
+    # Procesar cada frame
+    # ------------------------------------------------------------------
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    bg_array = np.array(bg_color, dtype=np.uint8)  # RGB
+    result_paths = []
+
+    for frame_path in frame_paths:
+        if not frame_path.exists():
+            raise FileNotFoundError(f"The frame '{frame_path}' does not exist.")
+
+        bgr = cv2.imread(str(frame_path), cv2.IMREAD_COLOR)
+        if bgr is None:
+            raise ValueError(f"Cannot read frame '{frame_path}' with OpenCV.")
+
+        # Convert BGR → RGB for the distance computation
+        rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
+
+        # Euclidean distance per pixel against bg_color
+        diff = rgb.astype(np.float32) - bg_array.astype(np.float32)
+        dist = np.sqrt(np.sum(diff ** 2, axis=2))
+
+        # Alpha mask: binary (feather=0) or linear ramp (feather>0)
+        if feather == 0:
+            alpha = np.where(dist <= tolerance, 0, 255).astype(np.uint8)
+        else:
+            lower = max(0, tolerance - feather)
+            upper = tolerance + feather
+            alpha = np.where(
+                dist <= lower,
+                np.uint8(0),
+                np.where(
+                    dist >= upper,
+                    np.uint8(255),
+                    ((dist - lower) / (upper - lower) * 255).astype(np.uint8),
+                ),
+            )
+
+        rgba = np.dstack([rgb, alpha])
+
+        out_file = output_path / frame_path.name
+        Image.fromarray(rgba, "RGBA").save(out_file)
+        result_paths.append(out_file)
+
+    return sorted(result_paths)

spriteworkflow/report.py

@@ -0,0 +1,142 @@
+import json
+from datetime import datetime
+from pathlib import Path
+
+from PIL import Image
+
+
+def generate_report(frames=None, frames_dir=None, spritesheet_path=None, output_file="report.json"):
+    """Inspect frames and produce a JSON validation report.
+
+    Use this function *after* creating a spritesheet to detect issues
+    such as mismatched frame dimensions, verify the output file, and
+    produce a portable metadata record.
+
+    Unlike :func:`create_spritesheet_lineal` and
+    :func:`create_spritesheet_grid`, this function **does not** raise
+    when frames have different sizes — mismatches are recorded in the
+    report instead, which is the whole point of validation.
+
+    Parameters
+    ----------
+    frames : list of Path or str, optional
+        List of paths to individual frame images.
+    frames_dir : Path or str, optional
+        Directory containing PNG frames. Mutually exclusive with *frames*.
+    spritesheet_path : Path or str, optional
+        Path to a spritesheet file to include its dimensions in the report.
+    output_file : Path or str
+        Path for the generated JSON report. Default ``"report.json"``.
+
+    Returns
+    -------
+    Path
+        Path to the generated JSON report file.
+
+    Raises
+    ------
+    ValueError
+        If neither *frames* nor *frames_dir* is provided, if both are
+        provided, or if *frames_dir* points to an empty directory.
+    FileNotFoundError
+        If *frames_dir* or *spritesheet_path* does not exist.
+    NotADirectoryError
+        If *frames_dir* is a file, not a directory.
+    """
+    # ------------------------------------------------------------------
+    # Validación de entrada (mismo estilo que spritesheet_lineal)
+    # ------------------------------------------------------------------
+    if frames is None and frames_dir is None:
+        raise ValueError("Either 'frames' or 'frames_dir' must be provided.")
+
+    if frames is not None and frames_dir is not None:
+        raise ValueError("Only one of 'frames' or 'frames_dir' should be provided, not both.")
+
+    if frames_dir is not None:
+        frames_path = Path(frames_dir)
+
+        if not frames_path.exists():
+            raise FileNotFoundError(f"The directory '{frames_dir}' does not exist.")
+
+        if not frames_path.is_dir():
+            raise NotADirectoryError(f"The path '{frames_dir}' is not a directory.")
+
+        frames = sorted(frames_path.glob("*.png"))
+
+    if not frames:
+        raise ValueError("No frames found to report.")
+
+    # ------------------------------------------------------------------
+    # Validación de spritesheet_path
+    # ------------------------------------------------------------------
+    if spritesheet_path is not None:
+        sprite_path = Path(spritesheet_path)
+        if not sprite_path.exists():
+            raise FileNotFoundError(f"The spritesheet '{spritesheet_path}' does not exist.")
+        if not sprite_path.is_file():
+            raise ValueError(f"The path '{spritesheet_path}' is not a valid file.")
+
+    # ------------------------------------------------------------------
+    # Procesar frames
+    # ------------------------------------------------------------------
+    frame_paths = [Path(f) for f in frames]
+
+    frame_entries = []
+    mismatched = []
+    reference_size = None
+
+    for idx, frame_path in enumerate(frame_paths):
+        img = Image.open(frame_path)
+        w, h = img.size
+
+        frame_entries.append({
+            "file": frame_path.name,
+            "width": w,
+            "height": h,
+        })
+
+        if idx == 0:
+            reference_size = [w, h]
+        elif [w, h] != reference_size:
+            mismatched.append(frame_path.name)
+
+    # ------------------------------------------------------------------
+    # Información del spritesheet (opcional)
+    # ------------------------------------------------------------------
+    spritesheet_size = None
+    sprite_path_str = None
+
+    if spritesheet_path is not None:
+        sprite_path = Path(spritesheet_path)
+        sprite_img = Image.open(sprite_path)
+        spritesheet_size = list(sprite_img.size)
+        sprite_path_str = str(sprite_path)
+
+    # ------------------------------------------------------------------
+    # Construir y guardar el reporte
+    # ------------------------------------------------------------------
+    report = {
+        "total_frames": len(frame_paths),
+        "frames": frame_entries,
+        "consistent_dimensions": len(mismatched) == 0,
+        "reference_size": reference_size,
+        "mismatched_frames": mismatched,
+        "spritesheet_path": sprite_path_str,
+        "spritesheet_size": spritesheet_size,
+        "generated_at": datetime.now().isoformat(),
+    }
+
+    output_path = Path(output_file)
+
+    if output_path.suffix == "":
+        output_path = output_path.with_suffix(".json")
+
+    if output_path.exists():
+        print(f"Warning: The file '{output_file}' already exists and will be overwritten.")
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(report, f, indent=2)
+
+    return output_path

spriteworkflow/spritesheet_grid.py

@@ -0,0 +1,132 @@
+import math
+from pathlib import Path
+
+from PIL import Image
+
+
+def create_spritesheet_grid(frames=None, frames_dir=None, columns=None, padding=0,
+                             background=(0, 0, 0, 0), output_file="spritesheet_grid.png"):
+    """Arrange frames into a grid spritesheet (rows × columns).
+
+    Parameters
+    ----------
+    frames : list of Path or str, optional
+        List of paths to individual frame images.
+    frames_dir : Path or str, optional
+        Directory containing PNG frames. Mutually exclusive with *frames*.
+    columns : int, optional
+        Number of columns in the grid. If ``None`` it is auto-calculated as
+        ``ceil(sqrt(total_frames))``.
+    padding : int
+        Pixels of empty space between adjacent cells. Default 0.
+    background : tuple of int
+        RGBA quadruplet used to fill the background canvas and any unused
+        cells. Default ``(0, 0, 0, 0)`` (fully transparent).
+    output_file : Path or str
+        Path for the generated spritesheet. Default ``"spritesheet_grid.png"``.
+
+    Returns
+    -------
+    Path
+        Path to the generated grid spritesheet.
+
+    Raises
+    ------
+    ValueError
+        If neither *frames* nor *frames_dir* is provided, if both are
+        provided, if *frames_dir* points to an empty directory, if
+        *columns* is not an integer ≥ 1, or if a frame has a different
+        size than the first frame.
+    FileNotFoundError
+        If *frames_dir* does not exist.
+    NotADirectoryError
+        If *frames_dir* is a file, not a directory.
+    """
+    # ------------------------------------------------------------------
+    # Validación de entrada (mismo estilo que create_spritesheet_lineal)
+    # ------------------------------------------------------------------
+    if frames is None and frames_dir is None:
+        raise ValueError("Either 'frames' or 'frames_dir' must be provided.")
+
+    if frames is not None and frames_dir is not None:
+        raise ValueError("Only one of 'frames' or 'frames_dir' should be provided, not both.")
+
+    if frames_dir is not None:
+        frames_path = Path(frames_dir)
+
+        if not frames_path.exists():
+            raise FileNotFoundError(f"The directory '{frames_dir}' does not exist.")
+
+        if not frames_path.is_dir():
+            raise NotADirectoryError(f"The path '{frames_dir}' is not a directory.")
+
+        frames = sorted(frames_path.glob("*.png"))
+
+    if not frames:
+        raise ValueError("No frames found to create the spritesheet.")
+
+    # ------------------------------------------------------------------
+    # Validación de columns
+    # ------------------------------------------------------------------
+    if columns is None:
+        columns = math.ceil(math.sqrt(len(frames)))
+    elif not isinstance(columns, int) or columns < 1:
+        raise ValueError("columns must be an integer >= 1.")
+
+    # ------------------------------------------------------------------
+    # Calcular dimensiones del grid
+    # ------------------------------------------------------------------
+    frame_paths = [Path(f) for f in frames]
+
+    first_frame_path = frame_paths[0]
+    if not first_frame_path.exists():
+        raise FileNotFoundError(f"The frame '{first_frame_path}' does not exist.")
+
+    first_frame = Image.open(first_frame_path)
+    frame_width, frame_height = first_frame.size
+
+    total_frames = len(frame_paths)
+    rows = math.ceil(total_frames / columns)
+
+    sheet_width = columns * frame_width + padding * (columns - 1)
+    sheet_height = rows * frame_height + padding * (rows - 1)
+
+    spritesheet = Image.new("RGBA", (sheet_width, sheet_height), background)
+
+    # ------------------------------------------------------------------
+    # Colocar frames en el grid
+    # ------------------------------------------------------------------
+    for index, frame_path in enumerate(frame_paths):
+        frame_path = Path(frame_path)
+
+        if not frame_path.exists():
+            raise FileNotFoundError(f"The frame '{frame_path}' does not exist.")
+
+        frame = Image.open(frame_path)
+
+        if frame.size != (frame_width, frame_height):
+            raise ValueError(f"Frame '{frame_path}' has a different size than the first frame.")
+
+        col = index % columns
+        row = index // columns
+        x = col * (frame_width + padding)
+        y = row * (frame_height + padding)
+
+        spritesheet.paste(frame, (x, y))
+
+    # ------------------------------------------------------------------
+    # Guardar (mismo patrón que spritesheet_lineal)
+    # ------------------------------------------------------------------
+    output_path = Path(output_file)
+
+    if output_path.suffix == "":
+        output_path = output_path.with_suffix(".png")
+
+    if output_path.exists():
+        print(f"Warning: The file '{output_file}' already exists and will be overwritten.")
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    spritesheet.save(output_path)
+
+    return output_path

spriteworkflow/spritesheet_lineal.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+from PIL import Image
+
+def create_spritesheet_lineal(frames=None, frames_dir=None, output_file="spritesheet.png"):
+    if frames is None and frames_dir is None:
+        raise ValueError("Either 'frames' or 'frames_dir' must be provided.")
+    
+    if frames is not None and frames_dir is not None:
+        raise ValueError("Only one of 'frames' or 'frames_dir' should be provided, not both.")
+    
+    if frames_dir is not None:
+        frames_path = Path(frames_dir)
+        
+        if not frames_path.exists():
+            raise FileNotFoundError(f"The directory '{frames_dir}' does not exist.")
+        
+        if not frames_path.is_dir():
+            raise NotADirectoryError(f"The path '{frames_dir}' is not a directory.")
+        
+        frames = sorted(frames_path.glob("*.png"))
+
+    if not frames:
+        raise ValueError("No frames found to create the spritesheet.")
+
+    first_frame_path = Path(frames[0])
+    
+    if not first_frame_path.exists():
+        raise FileNotFoundError(f"The frame '{frames[0]}' does not exist.")
+
+    first_frame = Image.open(first_frame_path)
+    frame_width, frame_height = first_frame.size
+    
+    total_frames = len(frames)
+
+    sheet_width = frame_width * total_frames
+    sheet_height = frame_height
+    
+    spritesheet = Image.new("RGBA", (sheet_width, sheet_height))
+
+    for index, frame_path in enumerate(frames):
+        frame_path = Path(frame_path)
+        
+        if not frame_path.exists():
+            raise FileNotFoundError(f"The frame '{frame_path}' does not exist.")
+        
+        frame = Image.open(frame_path)
+        
+        if frame.size != (frame_width, frame_height):
+            raise ValueError(f"Frame '{frame_path}' has a different size than the first frame.")
+        
+        x_position = index * frame_width
+        y_position = 0
+        
+        spritesheet.paste(frame, (x_position, y_position))
+
+    output_path = Path(output_file)
+    
+    if output_path.suffix == "":
+        output_path = output_path.with_suffix(".png")
+    
+    if output_path.exists():
+        print(f"Warning: The file '{output_file}' already exists and will be overwritten.")
+        
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    spritesheet.save(output_path)
+    
+    return output_path

spriteworkflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: spriteworkflow
+Version: 0.1.0
+Summary: Simple video to spritesheet workflow library.
+Author-email: jhonvillanueva-hash <jhon.villanueva.lozano.v@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jhonvillanueva-hash/spriteworkflow
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: imageio-ffmpeg>=0.6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# SpriteWorkflow
+
+Biblioteca Python para convertir videos en spritesheets (hojas de sprites).
+Extrae fotogramas de un video, opcionalmente remueve el fondo por chroma-key,
+y los ensambla en un spritesheet lineal (horizontal) o en cuadrícula (grid).
+Incluye un reporte de validación en formato JSON.
+
+## Instalación
+
+```bash
+pip install spriteworkflow
+```
+
+Requiere **Python ≥ 3.10** y dependencias: `opencv-python`, `pillow`, `imageio-ffmpeg`.
+
+### Dependencias de sistema
+
+- **FFmpeg**: necesario para la extracción de fotogramas. La biblioteca lo
+  localiza automáticamente con `imageio-ffmpeg`, pero si no está disponible
+  puedes instalarlo manualmente:
+  - Windows: `winget install ffmpeg`
+  - macOS: `brew install ffmpeg`
+  - Linux: `sudo apt install ffmpeg`
+
+---
+
+## Funciones de la biblioteca
+
+### `extract_frames(video_name, output_dir="temp")`
+
+Extrae fotogramas de un video en archivos PNG numerados.
+
+| Parámetro      | Tipo              | Default   | Descripción                              |
+|----------------|-------------------|-----------|------------------------------------------|
+| `video_name`   | `str` o `Path`    | —         | Ruta al archivo de video                 |
+| `output_dir`   | `str` o `Path`    | `"temp"`  | Directorio de salida (se crea si no existe) |
+
+- **Retorna**: `list[Path]` — rutas a los PNG extraídos, ordenados.
+- **Excepciones**: `FileNotFoundError` (video no existe),
+  `ValueError` (archivo inválido o vacío), `PermissionError` (sin permiso),
+  `RuntimeError` (FFmpeg falla o no se extrajeron fotogramas).
+
+### `remove_background(frames=None, frames_dir=None, bg_color=None, tolerance=30, feather=0, output_dir="matted")`
+
+Elimina el fondo de fotogramas mediante chroma-key (distancia euclidiana en RGB).
+
+| Parámetro     | Tipo              | Default     | Descripción                                    |
+|---------------|-------------------|-------------|------------------------------------------------|
+| `frames`      | `list[Path]`      | `None`      | Lista de rutas a los fotogramas PNG            |
+| `frames_dir`  | `str` o `Path`    | `None`      | Directorio con PNG (alternativa a `frames`)    |
+| `bg_color`    | `tuple[int,int,int]` | `None`   | RGB del chroma-key; auto-detectado si es `None`|
+| `tolerance`   | `int`             | `30`        | Distancia euclídea máxima del color de fondo   |
+| `feather`     | `int`             | `0`         | Ancho del difuminado lineal alrededor de `tolerance`|
+| `output_dir`  | `str` o `Path`    | `"matted"`  | Directorio para los PNG con canal alpha        |
+
+- **Retorna**: `list[Path]` — rutas a los PNG procesados (RGBA), ordenados.
+- **Excepciones**: `ValueError` (parámetros inválidos),
+  `FileNotFoundError` (`frames_dir` no existe),
+  `NotADirectoryError` (`frames_dir` no es directorio).
+
+### `create_spritesheet_lineal(frames=None, frames_dir=None, output_file="spritesheet.png")`
+
+Ensambla fotogramas en un spritesheet horizontal (una fila).
+
+| Parámetro      | Tipo              | Default              | Descripción                              |
+|----------------|-------------------|----------------------|------------------------------------------|
+| `frames`       | `list[Path]`      | `None`               | Lista de rutas a los fotogramas PNG      |
+| `frames_dir`   | `str` o `Path`    | `None`               | Directorio con PNG (alternativa a `frames`)|
+| `output_file`  | `str` o `Path`    | `"spritesheet.png"`  | Ruta del spritesheet generado            |
+
+- **Retorna**: `Path` — ruta al archivo generado.
+- **Excepciones**: `ValueError`, `FileNotFoundError`, `NotADirectoryError`.
+
+### `create_spritesheet_grid(frames=None, frames_dir=None, columns=None, padding=0, background=(0,0,0,0), output_file="spritesheet_grid.png")`
+
+Ensambla fotogramas en un spritesheet en cuadrícula (filas × columnas).
+
+| Parámetro      | Tipo               | Default                    | Descripción                              |
+|----------------|--------------------|----------------------------|------------------------------------------|
+| `frames`       | `list[Path]`       | `None`                     | Lista de rutas a los fotogramas PNG      |
+| `frames_dir`   | `str` o `Path`     | `None`                     | Directorio con PNG (alternativa a `frames`)|
+| `columns`      | `int` o `None`     | `None`                     | N° de columnas; `None` = `ceil(sqrt(N))`|
+| `padding`      | `int`              | `0`                        | Píxeles de espacio entre celdas         |
+| `background`   | `tuple[int,int,int,int]` | `(0,0,0,0)`         | RGBA de relleno para celdas vacías       |
+| `output_file`  | `str` o `Path`     | `"spritesheet_grid.png"`   | Ruta del spritesheet generado            |
+
+- **Retorna**: `Path` — ruta al archivo generado.
+- **Excepciones**: `ValueError`, `FileNotFoundError`, `NotADirectoryError`.
+
+### `generate_report(frames=None, frames_dir=None, spritesheet_path=None, output_file="report.json")`
+
+Inspecciona fotogramas y produce un reporte de validación JSON.
+
+| Parámetro          | Tipo              | Default        | Descripción                              |
+|--------------------|-------------------|----------------|------------------------------------------|
+| `frames`           | `list[Path]`      | `None`         | Lista de rutas a los fotogramas PNG      |
+| `frames_dir`       | `str` o `Path`    | `None`         | Directorio con PNG (alternativa)         |
+| `spritesheet_path` | `str` o `Path`    | `None`         | Ruta al spritesheet (opcional)           |
+| `output_file`      | `str` o `Path`    | `"report.json"`| Ruta del archivo JSON generado           |
+
+- **Retorna**: `Path` — ruta al archivo JSON.
+- **Excepciones**: `ValueError`, `FileNotFoundError`, `NotADirectoryError`.
+
+El reporte incluye: `total_frames`, `frames[]` (archivo, ancho, alto),
+`consistent_dimensions`, `reference_size`, `mismatched_frames`,
+`spritesheet_path`, `spritesheet_size`, y `generated_at`.
+
+---
+
+## Ejemplo de uso (como biblioteca)
+
+```python
+from spriteworkflow import extract_frames, remove_background
+from spriteworkflow import create_spritesheet_grid, generate_report
+
+# 1. Extraer fotogramas de un video
+frames = extract_frames("gameplay.mp4", output_dir="temp")
+print(f"Extraídos {len(frames)} fotogramas")
+
+# 2. Remover fondo verde (chroma-key)
+frames_matted = remove_background(
+    frames=frames,
+    bg_color=(0, 255, 0),
+    tolerance=40,
+    output_dir="matted",
+)
+
+# 3. Crear spritesheet en grilla (3 columnas)
+sheet = create_spritesheet_grid(
+    frames=frames_matted,
+    columns=3,
+    padding=2,
+    background=(0, 0, 0, 0),
+    output_file="hoja_sprites.png",
+)
+print(f"Spritesheet guardado: {sheet}")
+
+# 4. Generar reporte de validación
+report = generate_report(
+    frames=frames_matted,
+    spritesheet_path=sheet,
+    output_file="reporte.json",
+)
+print(f"Reporte guardado: {report}")
+```
+
+---
+
+## Uso desde CLI
+
+El paquete instala el comando `spriteworkflow` con un subcomando `build` que
+encadena el pipeline completo:
+
+```bash
+spriteworkflow build <video> [opciones]
+```
+
+### Argumentos
+
+| Argumento / Flag        | Descripción                                   | Default                 |
+|-------------------------|-----------------------------------------------|-------------------------|
+| `video`                 | Ruta al video de entrada (requerido)          | —                       |
+| `--output`, `-o`        | Ruta del spritesheet generado                 | `spritesheet.png`       |
+| `--layout`              | Lineal o grid (`lineal`, `grid`)              | `lineal`                |
+| `--columns`             | Columnas para grilla (auto si no se indica)   | auto `ceil(sqrt(N))`    |
+| `--padding`             | Píxeles de separación entre celdas            | `0`                     |
+| `--matte`               | Activa remoción de fondo por chroma-key       | desactivado             |
+| `--bg-color`            | RGB para chroma-key, ej: `--bg-color 0 255 0`| auto-detectado          |
+| `--tolerance`           | Tolerancia euclídea de chroma-key             | `30`                    |
+| `--feather`             | Difuminado del borde del chroma-key           | `0`                     |
+| `--report-file`         | Ruta del reporte JSON de validación           | no se genera            |
+| `--temp-dir`            | Directorio temporal para fotogramas extraídos | `temp`                  |
+
+### Ejemplos
+
+```bash
+# Pipeline mínimo: extraer y ensamblar spritesheet lineal
+spriteworkflow build partida.mp4
+
+# Especificar ruta de salida
+spriteworkflow build partida.mp4 -o assets/hoja.png
+
+# Spritesheet en grilla de 4 columnas con padding
+spriteworkflow build partida.mp4 --layout grid --columns 4 --padding 2
+
+# Remover chroma-key verde, luego ensamblar spritesheet
+spriteworkflow build partida.mp4 --matte --bg-color 0 255 0
+
+# Pipeline completo con reporte
+spriteworkflow build partida.mp4 \
+    --layout grid --columns 4 --padding 2 \
+    --matte --tolerance 40 \
+    --report-file reporte.json
+```
+
+## Ejecutar pruebas
+
+El proyecto usa `pytest`. Para ejecutar la suite completa:
+
+```bash
+pip install -e ".[test]"
+pytest -v
+```
+
+Para ejecutar un archivo de pruebas específico:
+
+```bash
+pytest tests/cli_test.py -v
+```
+
+---
+
+## Licencia
+
+MIT

spriteworkflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+spriteworkflow/__init__.py,sha256=nSIW9LISN71kS-YUGl-ALiRN8X2i48smgB7KjYZFrR0,828
+spriteworkflow/cli.py,sha256=2J1NLSy4nqvdSN9NG4NDGkDxNFp7YjF8w9x8HVGPWXc,5869
+spriteworkflow/extractor.py,sha256=kMcXwfGGYgbF2d-TYFY0sGKb-sIv3wMzRcyxF5lpvAI,1847
+spriteworkflow/ffmpeg_manager.py,sha256=OUceUEx6VdTqB7IpA2_hg5u0mVmp_kO18OAqnLgtYD8,250
+spriteworkflow/matte.py,sha256=euZfqo2Qd4y2UhJGJFjEMxz5S6o0P8N4y1ehbHjC5sc,5900
+spriteworkflow/report.py,sha256=hRVxP5nB5j7aAvIYILJBuRQRs5OJRaBxLeDwVg8hLSM,5144
+spriteworkflow/spritesheet_grid.py,sha256=f3StB0JOk-VyB9mryvnhv3R2MKFkgg5qM0AlzhQ2bnQ,4976
+spriteworkflow/spritesheet_lineal.py,sha256=DkVRTDyPBOmHllwmdAzD6CdCIcDdhBrmnq86Ta5EMFE,2365
+spriteworkflow-0.1.0.dist-info/licenses/LICENSE,sha256=Md8q0sNdvz6S9YWEeOpWmx-D13KRlsObRU_vO8bo0wg,1076
+spriteworkflow-0.1.0.dist-info/METADATA,sha256=1Emo4MNKKRu5u6lj7whfUx5aq_v4GofYKbGavkuPf60,10276
+spriteworkflow-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+spriteworkflow-0.1.0.dist-info/entry_points.txt,sha256=bQKlkkSyEbCjGfG9g2vnGbJ4BUZBr9EM14FlVQ83GoM,59
+spriteworkflow-0.1.0.dist-info/top_level.txt,sha256=oc7QpLj3pf83efWq9YEbzn7KrUwMsLjRSYUV7i7HmfM,15
+spriteworkflow-0.1.0.dist-info/RECORD,,

spriteworkflow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spriteworkflow-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spriteworkflow = spriteworkflow.cli:main

spriteworkflow-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhonvillanueva-hash
+
+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.

spriteworkflow-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spriteworkflow