spriteworkflow 0.1.0__tar.gz

spriteworkflow-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,215 @@
+# 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/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spriteworkflow"
+version = "0.1.0"
+description = "Simple video to spritesheet workflow library."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+authors = [
+    { name = "jhonvillanueva-hash", email = "jhon.villanueva.lozano.v@gmail.com" }
+]
+
+dependencies = [
+    "opencv-python>=4.8.0",
+    "pillow>=10.0.0",
+    "imageio-ffmpeg>=0.6.0"
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/jhonvillanueva-hash/spriteworkflow"
+
+[project.scripts]
+spriteworkflow = "spriteworkflow.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["spriteworkflow"]

spriteworkflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spriteworkflow-0.1.0/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",
+]