schenesort 2.3.0__tar.gz → 2.4.0__tar.gz

{schenesort-2.3.0 → schenesort-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: schenesort
-Version: 2.3.0
+Version: 2.4.0
 Summary: Wallpaper collection management CLI tool
 License-File: LICENSE
 Requires-Python: >=3.13
@@ -12,12 +12,14 @@ Requires-Dist: textual>=0.95.0
 Requires-Dist: typer>=0.21.1
 Description-Content-Type: text/markdown
 
-# Schenesort v2.3.0
+# Schenesort v2.4.0
 
-A CLI tool for managing wallpaper collections with model generated metadata, terminal UI browsing, and SQLite-based
-querying.
+![Collage example](docs/collage.png)
+
+A cli tool for managing wallpaper collections with model generated metadata, sweet tui, and sql metadata querying.
+
+schenesort takes a directory of random wallpapers, with random filenames, and uses olama with a decent vision model to:
 
-schenesort takes a directory of random wallpapers, with random filenames, and uses olama with a decent vision model to
 - look at each wallpaper
 - rename the wallpaper to something sensible
 - drop a XMP sidecar with metadata about the file
@@ -51,12 +53,18 @@ setup](./ollama-setup.md).
 # Generate metadata for images
 schenesort metadata generate ~/wallpapers -r
 
-# Browse with TUI
-schenesort browse ~/wallpapers
-
 # Index the collection
 schenesort index ~/wallpapers
 
+# Generate thumbnails for gallery
+schenesort thumbnail ~/wallpapers -r
+
+# Browse with gallery (thumbnail grid with filters)
+schenesort gallery
+
+# Browse single images with TUI
+schenesort browse ~/wallpapers
+
 # Query wallpapers
 schenesort get --mood peaceful --screen 4K
 schenesort get -1 -p | xargs feh  # random wallpaper
@@ -67,6 +75,8 @@ schenesort get -1 -p | xargs feh  # random wallpaper
 | Command                      | Description                                         |
 |------------------------------|-----------------------------------------------------|
 | `browse`                     | Terminal UI browser with image preview and metadata |
+| `gallery`                    | Thumbnail grid browser with filters                 |
+| `thumbnail`                  | Generate thumbnail cache for gallery                |
 | `index`                      | Build SQLite index for fast querying                |
 | `get`                        | Query wallpapers by metadata attributes             |
 | `stats`                      | Show collection statistics from index               |
@@ -100,6 +110,7 @@ schenesort get --mood peaceful -b  # browse query results
 ![Browse example - Stallman](docs/browse-stallman.png)
 
 **Keyboard shortcuts:**
+
 | Key          | Action         |
 |--------------|----------------|
 | `j` / `Down` | Next image     |
@@ -111,6 +122,63 @@ schenesort get --mood peaceful -b  # browse query results
 
 The TUI uses textual-image for rendering, which auto-detects terminal graphics support (Sixel, iTerm2, Kitty).
 
+## Gallery Browser
+
+Browse your indexed collection with a thumbnail grid and filter panel:
+
+```bash
+# Open gallery browser
+schenesort gallery
+
+# Pre-filter results
+schenesort gallery --mood peaceful
+schenesort gallery --tag nature --style photography
+```
+
+The gallery requires an indexed collection (`schenesort index`) and cached thumbnails for fast loading.
+
+### Generate Thumbnails
+
+```bash
+# Generate thumbnails for a directory
+schenesort thumbnail ~/wallpapers
+
+# Recursive with progress bar
+schenesort thumbnail ~/wallpapers -r
+
+# Force regenerate all thumbnails
+schenesort thumbnail ~/wallpapers --force
+
+# Clear thumbnail cache
+schenesort thumbnail ~/wallpapers --clear
+```
+
+Thumbnails are cached at `~/.cache/schenesort/thumbnails/` (320x200 JPEG).
+
+**Gallery keyboard shortcuts:**
+
+| Key              | Action                |
+|------------------|-----------------------|
+| `j` / `Down`     | Move down             |
+| `k` / `Up`       | Move up               |
+| `h` / `Left`     | Move left             |
+| `l` / `Right`    | Move right            |
+| `g` / `Home`     | First image           |
+| `G` / `End`      | Last image            |
+| `Enter`          | Open detail view      |
+| `Tab`            | Switch panel          |
+| `Escape`         | Clear filters         |
+| `r`              | Refresh               |
+| `q` / `Ctrl+C`   | Quit                  |
+
+**Detail view shortcuts:**
+
+| Key              | Action                |
+|------------------|-----------------------|
+| `j` / `Down`     | Next image            |
+| `k` / `Up`       | Previous image        |
+| `Escape` / `q`   | Back to grid          |
+
 ## Collection Indexing and Querying
 
 Build a SQLite index for fast querying across your entire collection:
@@ -167,7 +235,9 @@ schenesort collage collage.png --tile-width 640 --tile-height 360
 schenesort collage night_cities.png --time night --subject urban --cols 3 --rows 2
 ```
 
-![Collage example](docs/collage.png)
+`schenesort collage landscape.png --cols 4 --rows 4 --tile-width 640 --tile-height 360 --tag landscape`
+
+![Collage example](docs/landscape.png)
 
 | Option          | Description                          | Default |
 |-----------------|--------------------------------------|---------|
@@ -277,6 +347,7 @@ schenesort cleanup ~/wallpapers -r
 ## Configuration
 
 Schenesort follows XDG Base Directory spec:
+
 - Config: `$XDG_CONFIG_HOME/schenesort/config.toml` (default: `~/.config/schenesort/config.toml`)
 - Data: `$XDG_DATA_HOME/schenesort/index.db` (default: `~/.local/share/schenesort/index.db`)
 
@@ -354,7 +425,7 @@ See [schenesort.yazi/README.md](schenesort.yazi/README.md) for details.
 
 ## XMP Sidecar Format
 
-```
+```text
 ~/wallpapers/
 ├── mountain_sunset.jpg
 ├── mountain_sunset.jpg.xmp   ← metadata stored here

{schenesort-2.3.0 → schenesort-2.4.0}/README.md

@@ -1,9 +1,11 @@
-# Schenesort v2.3.0
+# Schenesort v2.4.0
 
-A CLI tool for managing wallpaper collections with model generated metadata, terminal UI browsing, and SQLite-based
-querying.
+![Collage example](docs/collage.png)
+
+A cli tool for managing wallpaper collections with model generated metadata, sweet tui, and sql metadata querying.
+
+schenesort takes a directory of random wallpapers, with random filenames, and uses olama with a decent vision model to:
 
-schenesort takes a directory of random wallpapers, with random filenames, and uses olama with a decent vision model to
 - look at each wallpaper
 - rename the wallpaper to something sensible
 - drop a XMP sidecar with metadata about the file
@@ -37,12 +39,18 @@ setup](./ollama-setup.md).
 # Generate metadata for images
 schenesort metadata generate ~/wallpapers -r
 
-# Browse with TUI
-schenesort browse ~/wallpapers
-
 # Index the collection
 schenesort index ~/wallpapers
 
+# Generate thumbnails for gallery
+schenesort thumbnail ~/wallpapers -r
+
+# Browse with gallery (thumbnail grid with filters)
+schenesort gallery
+
+# Browse single images with TUI
+schenesort browse ~/wallpapers
+
 # Query wallpapers
 schenesort get --mood peaceful --screen 4K
 schenesort get -1 -p | xargs feh  # random wallpaper
@@ -53,6 +61,8 @@ schenesort get -1 -p | xargs feh  # random wallpaper
 | Command                      | Description                                         |
 |------------------------------|-----------------------------------------------------|
 | `browse`                     | Terminal UI browser with image preview and metadata |
+| `gallery`                    | Thumbnail grid browser with filters                 |
+| `thumbnail`                  | Generate thumbnail cache for gallery                |
 | `index`                      | Build SQLite index for fast querying                |
 | `get`                        | Query wallpapers by metadata attributes             |
 | `stats`                      | Show collection statistics from index               |
@@ -86,6 +96,7 @@ schenesort get --mood peaceful -b  # browse query results
 ![Browse example - Stallman](docs/browse-stallman.png)
 
 **Keyboard shortcuts:**
+
 | Key          | Action         |
 |--------------|----------------|
 | `j` / `Down` | Next image     |
@@ -97,6 +108,63 @@ schenesort get --mood peaceful -b  # browse query results
 
 The TUI uses textual-image for rendering, which auto-detects terminal graphics support (Sixel, iTerm2, Kitty).
 
+## Gallery Browser
+
+Browse your indexed collection with a thumbnail grid and filter panel:
+
+```bash
+# Open gallery browser
+schenesort gallery
+
+# Pre-filter results
+schenesort gallery --mood peaceful
+schenesort gallery --tag nature --style photography
+```
+
+The gallery requires an indexed collection (`schenesort index`) and cached thumbnails for fast loading.
+
+### Generate Thumbnails
+
+```bash
+# Generate thumbnails for a directory
+schenesort thumbnail ~/wallpapers
+
+# Recursive with progress bar
+schenesort thumbnail ~/wallpapers -r
+
+# Force regenerate all thumbnails
+schenesort thumbnail ~/wallpapers --force
+
+# Clear thumbnail cache
+schenesort thumbnail ~/wallpapers --clear
+```
+
+Thumbnails are cached at `~/.cache/schenesort/thumbnails/` (320x200 JPEG).
+
+**Gallery keyboard shortcuts:**
+
+| Key              | Action                |
+|------------------|-----------------------|
+| `j` / `Down`     | Move down             |
+| `k` / `Up`       | Move up               |
+| `h` / `Left`     | Move left             |
+| `l` / `Right`    | Move right            |
+| `g` / `Home`     | First image           |
+| `G` / `End`      | Last image            |
+| `Enter`          | Open detail view      |
+| `Tab`            | Switch panel          |
+| `Escape`         | Clear filters         |
+| `r`              | Refresh               |
+| `q` / `Ctrl+C`   | Quit                  |
+
+**Detail view shortcuts:**
+
+| Key              | Action                |
+|------------------|-----------------------|
+| `j` / `Down`     | Next image            |
+| `k` / `Up`       | Previous image        |
+| `Escape` / `q`   | Back to grid          |
+
 ## Collection Indexing and Querying
 
 Build a SQLite index for fast querying across your entire collection:
@@ -153,7 +221,9 @@ schenesort collage collage.png --tile-width 640 --tile-height 360
 schenesort collage night_cities.png --time night --subject urban --cols 3 --rows 2
 ```
 
-![Collage example](docs/collage.png)
+`schenesort collage landscape.png --cols 4 --rows 4 --tile-width 640 --tile-height 360 --tag landscape`
+
+![Collage example](docs/landscape.png)
 
 | Option          | Description                          | Default |
 |-----------------|--------------------------------------|---------|
@@ -263,6 +333,7 @@ schenesort cleanup ~/wallpapers -r
 ## Configuration
 
 Schenesort follows XDG Base Directory spec:
+
 - Config: `$XDG_CONFIG_HOME/schenesort/config.toml` (default: `~/.config/schenesort/config.toml`)
 - Data: `$XDG_DATA_HOME/schenesort/index.db` (default: `~/.local/share/schenesort/index.db`)
 
@@ -340,7 +411,7 @@ See [schenesort.yazi/README.md](schenesort.yazi/README.md) for details.
 
 ## XMP Sidecar Format
 
-```
+```text
 ~/wallpapers/
 ├── mountain_sunset.jpg
 ├── mountain_sunset.jpg.xmp   ← metadata stored here

{schenesort-2.3.0 → schenesort-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "schenesort"
-version = "2.3.0"
+version = "2.4.0"
 description = "Wallpaper collection management CLI tool"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -56,7 +56,7 @@ testpaths = ["tests"]
 pythonpath = ["src"]
 
 [tool.bumpversion]
-current_version = "2.3.0"
+current_version = "2.4.0"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{schenesort-2.3.0 → schenesort-2.4.0}/src/schenesort/cli.py

@@ -412,6 +412,85 @@ def index(
         typer.echo(f"With metadata: {stats.get('with_metadata', 0)}")
 
 
+@app.command()
+def thumbnail(
+    path: Annotated[Path, typer.Argument(help="Directory to generate thumbnails for")],
+    recursive: Annotated[
+        bool, typer.Option("--recursive", "-r", help="Process directories recursively")
+    ] = True,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Regenerate all thumbnails")] = False,
+    clear: Annotated[
+        bool, typer.Option("--clear", help="Clear thumbnail cache before generating")
+    ] = False,
+) -> None:
+    """Generate thumbnails for gallery view."""
+    from rich.progress import BarColumn, Progress, TaskProgressColumn, TextColumn
+
+    from schenesort.thumbnails import (
+        clear_cache,
+        generate_thumbnail,
+        get_cache_stats,
+        thumbnail_exists,
+    )
+
+    path = path.resolve()
+
+    if not path.exists():
+        typer.echo(f"Error: Path '{path}' does not exist.", err=True)
+        raise typer.Exit(1)
+
+    if not path.is_dir():
+        typer.echo(f"Error: Path '{path}' is not a directory.", err=True)
+        raise typer.Exit(1)
+
+    if clear:
+        cleared = clear_cache()
+        typer.echo(f"Cleared {cleared} cached thumbnail(s).")
+
+    pattern = "**/*" if recursive else "*"
+    image_files = [
+        f for f in path.glob(pattern) if f.is_file() and f.suffix.lower() in VALID_IMAGE_EXTENSIONS
+    ]
+
+    if not image_files:
+        typer.echo("No image files found.")
+        raise typer.Exit(0)
+
+    generated = 0
+    skipped = 0
+    failed = 0
+
+    with Progress(
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        TextColumn("{task.completed}/{task.total}"),
+    ) as progress:
+        task = progress.add_task("Generating thumbnails", total=len(image_files))
+
+        for filepath in image_files:
+            if not force and thumbnail_exists(filepath):
+                skipped += 1
+                progress.advance(task)
+                continue
+
+            result = generate_thumbnail(filepath, force=force)
+            if result:
+                generated += 1
+            else:
+                failed += 1
+
+            progress.advance(task)
+
+    typer.echo(f"\nGenerated: {generated}, Skipped: {skipped}, Failed: {failed}")
+
+    # Show cache stats
+    stats = get_cache_stats()
+    typer.echo(f"\nCache: {stats['path']}")
+    typer.echo(f"Total thumbnails: {stats['count']}")
+    typer.echo(f"Cache size: {stats['size_mb']:.1f} MB")
+
+
 @app.command()
 def get(
     tag: Annotated[str | None, typer.Option("--tag", "-t", help="Filter by tag")] = None,
@@ -581,6 +660,48 @@ def browse(
     app_instance.run()
 
 
+@app.command()
+def gallery(
+    tag: Annotated[str | None, typer.Option("--tag", "-t", help="Filter by tag")] = None,
+    mood: Annotated[str | None, typer.Option("--mood", "-m", help="Filter by mood")] = None,
+    color: Annotated[str | None, typer.Option("--color", "-c", help="Filter by color")] = None,
+    style: Annotated[str | None, typer.Option("--style", "-s", help="Filter by style")] = None,
+    subject: Annotated[str | None, typer.Option("--subject", help="Filter by subject")] = None,
+    time: Annotated[str | None, typer.Option("--time", help="Filter by time of day")] = None,
+    screen: Annotated[
+        str | None, typer.Option("--screen", help="Filter by recommended screen (4K, 1440p, etc)")
+    ] = None,
+    min_width: Annotated[
+        int | None, typer.Option("--min-width", help="Minimum width in pixels")
+    ] = None,
+    min_height: Annotated[
+        int | None, typer.Option("--min-height", help="Minimum height in pixels")
+    ] = None,
+    search: Annotated[
+        str | None, typer.Option("--search", "-q", help="Search description, scene, style, subject")
+    ] = None,
+) -> None:
+    """Browse wallpapers in a thumbnail grid with filter sidebar."""
+    from schenesort.tui.grid_app import GridBrowser
+    from schenesort.tui.widgets.filter_panel import FilterValues
+
+    initial_filters = FilterValues(
+        search=search or "",
+        tag=tag or "",
+        mood=mood or "",
+        color=color or "",
+        style=style or "",
+        subject=subject or "",
+        time=time or "",
+        screen=screen or "",
+        min_width=min_width,
+        min_height=min_height,
+    )
+
+    app_instance = GridBrowser(initial_filters=initial_filters)
+    app_instance.run()
+
+
 @app.command()
 def config(
     create: Annotated[

schenesort-2.4.0/src/schenesort/thumbnails.py

@@ -0,0 +1,127 @@
+"""Thumbnail cache management for gallery view."""
+
+import hashlib
+import os
+from pathlib import Path
+
+from PIL import Image
+
+APP_NAME = "schenesort"
+
+# Thumbnail dimensions - larger for better quality when rendered in terminal
+# Terminal cells are ~32x14 chars, but textual-image benefits from more source pixels
+THUMBNAIL_WIDTH = 320
+THUMBNAIL_HEIGHT = 200
+
+
+def get_cache_dir() -> Path:
+    """Get the XDG cache directory for schenesort thumbnails."""
+    xdg_cache = os.environ.get("XDG_CACHE_HOME", "")
+    if xdg_cache:
+        cache_dir = Path(xdg_cache) / APP_NAME / "thumbnails"
+    else:
+        cache_dir = Path.home() / ".cache" / APP_NAME / "thumbnails"
+    return cache_dir
+
+
+def get_thumbnail_path(image_path: Path) -> Path:
+    """Get the thumbnail path for an image.
+
+    Uses MD5 hash of the absolute path to create a unique filename.
+    """
+    # Use absolute path for consistent hashing
+    abs_path = str(image_path.resolve())
+    path_hash = hashlib.md5(abs_path.encode()).hexdigest()
+    return get_cache_dir() / f"{path_hash}.jpg"
+
+
+def thumbnail_exists(image_path: Path) -> bool:
+    """Check if a thumbnail exists for the given image."""
+    thumb_path = get_thumbnail_path(image_path)
+    if not thumb_path.exists():
+        return False
+
+    # Check if thumbnail is newer than original
+    try:
+        orig_mtime = image_path.stat().st_mtime
+        thumb_mtime = thumb_path.stat().st_mtime
+        return thumb_mtime >= orig_mtime
+    except OSError:
+        return False
+
+
+def generate_thumbnail(image_path: Path, force: bool = False) -> Path | None:
+    """Generate a thumbnail for the given image.
+
+    Args:
+        image_path: Path to the original image
+        force: If True, regenerate even if thumbnail exists
+
+    Returns:
+        Path to the thumbnail, or None if generation failed
+    """
+    if not force and thumbnail_exists(image_path):
+        return get_thumbnail_path(image_path)
+
+    thumb_path = get_thumbnail_path(image_path)
+
+    try:
+        # Ensure cache directory exists
+        thumb_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with Image.open(image_path) as img:
+            # Convert to RGB if necessary (handles RGBA, palette, etc.)
+            if img.mode not in ("RGB", "L"):
+                img = img.convert("RGB")
+
+            # Calculate size preserving aspect ratio
+            img.thumbnail((THUMBNAIL_WIDTH, THUMBNAIL_HEIGHT), Image.Resampling.LANCZOS)
+
+            # Save as JPEG with high quality for better terminal rendering
+            img.save(thumb_path, "JPEG", quality=95, optimize=True)
+
+        return thumb_path
+
+    except Exception:
+        # Clean up partial file if it exists
+        if thumb_path.exists():
+            thumb_path.unlink()
+        return None
+
+
+def clear_cache() -> int:
+    """Clear all cached thumbnails.
+
+    Returns:
+        Number of thumbnails deleted
+    """
+    cache_dir = get_cache_dir()
+    if not cache_dir.exists():
+        return 0
+
+    count = 0
+    for thumb in cache_dir.glob("*.jpg"):
+        try:
+            thumb.unlink()
+            count += 1
+        except OSError:
+            pass
+
+    return count
+
+
+def get_cache_stats() -> dict:
+    """Get statistics about the thumbnail cache."""
+    cache_dir = get_cache_dir()
+    if not cache_dir.exists():
+        return {"count": 0, "size_bytes": 0, "path": str(cache_dir)}
+
+    thumbnails = list(cache_dir.glob("*.jpg"))
+    total_size = sum(t.stat().st_size for t in thumbnails)
+
+    return {
+        "count": len(thumbnails),
+        "size_bytes": total_size,
+        "size_mb": total_size / (1024 * 1024),
+        "path": str(cache_dir),
+    }

schenesort-2.4.0/src/schenesort/tui/__init__.py

@@ -0,0 +1,15 @@
+"""Schenesort TUI - Terminal UI for browsing wallpapers."""
+
+from schenesort.tui.app import WallpaperBrowser
+from schenesort.tui.grid_app import GridBrowser
+from schenesort.tui.widgets.filter_panel import FilterPanel, FilterValues
+from schenesort.tui.widgets.thumbnail_grid import ThumbnailGrid, ThumbnailText
+
+__all__ = [
+    "FilterPanel",
+    "FilterValues",
+    "GridBrowser",
+    "ThumbnailGrid",
+    "ThumbnailText",
+    "WallpaperBrowser",
+]