schenesort 2.2.0__tar.gz → 2.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: schenesort
-Version: 2.2.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.2.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
@@ -26,7 +28,7 @@ Once you have a collection of wallpapers re-named with metadata sidecars, run th
 that can be queried to retrieve suggestions based on tags, colours, names and the like. Then use `get` to get a
 wallpaper path `feh $(schenesort get -1 -p)` or `hyprctl hyprpaper wallpaper "eDP-1,$(schenesort get -1 -p)"`
 
-schenesort also provides a bunch of utility commands to satisfy a gooner collection.
+![Browse example - Autumn](docs/browse-destruction.png)
 
 ## Installation
 
@@ -44,16 +46,25 @@ uv sync
 
 ## Quick Start
 
+To generate metadata you need a olama server serving llava nearby, it takes a minute to set one up see [ollama
+setup](./ollama-setup.md).
+
 ```bash
 # 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
@@ -64,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               |
@@ -74,6 +87,7 @@ schenesort get -1 -p | xargs feh  # random wallpaper
 | `info`                       | Show collection file statistics                     |
 | `describe`                   | AI-rename images based on content (Ollama)          |
 | `models`                     | List available Ollama models                        |
+| `collage`                    | Create a collage grid from matching wallpapers      |
 | `metadata show`              | Display XMP sidecar metadata                        |
 | `metadata set`               | Manually set metadata fields                        |
 | `metadata generate`          | Generate metadata with AI (Ollama)                  |
@@ -91,13 +105,12 @@ schenesort browse                  # uses paths.wallpaper from config
 schenesort get --mood peaceful -b  # browse query results
 ```
 
-![Browse example - Greek](docs/browse-greek.png)
-
 ![Browse example - Autumn](docs/browse-autumn.png)
 
 ![Browse example - Stallman](docs/browse-stallman.png)
 
 **Keyboard shortcuts:**
+
 | Key          | Action         |
 |--------------|----------------|
 | `j` / `Down` | Next image     |
@@ -109,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:
@@ -147,6 +217,38 @@ schenesort stats
 
 The database is stored at `$XDG_DATA_HOME/schenesort/index.db` (default: `~/.local/share/schenesort/index.db`).
 
+## Collage Generation
+
+Create a collage grid (up to 4x4) from wallpapers matching query criteria:
+
+```bash
+# Create a 2x2 collage (default)
+schenesort collage output.png --mood peaceful
+
+# Create a 4x4 collage of landscape images
+schenesort collage wall.png --subject landscape --cols 4 --rows 4
+
+# Custom tile size (default: 480x270)
+schenesort collage collage.png --tile-width 640 --tile-height 360
+
+# Combine filters
+schenesort collage night_cities.png --time night --subject urban --cols 3 --rows 2
+```
+
+`schenesort collage landscape.png --cols 4 --rows 4 --tile-width 640 --tile-height 360 --tag landscape`
+
+![Collage example](docs/landscape.png)
+
+| Option          | Description                          | Default |
+|-----------------|--------------------------------------|---------|
+| `--cols`        | Number of columns (1-4)              | 2       |
+| `--rows`        | Number of rows (1-4)                 | 2       |
+| `--tile-width`  | Width of each tile in pixels         | 480     |
+| `--tile-height` | Height of each tile in pixels        | 270     |
+| `--random`      | Select images randomly               | True    |
+
+All `get` query filters are supported: `--tag`, `--mood`, `--color`, `--style`, `--subject`, `--time`, `--screen`, `--min-width`, `--min-height`, `--search`.
+
 ## Metadata Management
 
 Store metadata in XMP sidecar files (`.xmp`) alongside images without modifying the original files.
@@ -168,7 +270,7 @@ Store metadata in XMP sidecar files (`.xmp`) alongside images without modifying
 | `source`             | Source URL or info                                       |
 | `ai_model`           | Model used for metadata generation                       |
 
-### Generate Metadata with AI
+### Generate Metadata using ollama
 
 ```bash
 # Preview what would be generated
@@ -245,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`)
 
@@ -322,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.2.0 → schenesort-2.4.0}/README.md

@@ -1,9 +1,11 @@
-# Schenesort v2.2.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
@@ -12,7 +14,7 @@ Once you have a collection of wallpapers re-named with metadata sidecars, run th
 that can be queried to retrieve suggestions based on tags, colours, names and the like. Then use `get` to get a
 wallpaper path `feh $(schenesort get -1 -p)` or `hyprctl hyprpaper wallpaper "eDP-1,$(schenesort get -1 -p)"`
 
-schenesort also provides a bunch of utility commands to satisfy a gooner collection.
+![Browse example - Autumn](docs/browse-destruction.png)
 
 ## Installation
 
@@ -30,16 +32,25 @@ uv sync
 
 ## Quick Start
 
+To generate metadata you need a olama server serving llava nearby, it takes a minute to set one up see [ollama
+setup](./ollama-setup.md).
+
 ```bash
 # 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
@@ -50,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               |
@@ -60,6 +73,7 @@ schenesort get -1 -p | xargs feh  # random wallpaper
 | `info`                       | Show collection file statistics                     |
 | `describe`                   | AI-rename images based on content (Ollama)          |
 | `models`                     | List available Ollama models                        |
+| `collage`                    | Create a collage grid from matching wallpapers      |
 | `metadata show`              | Display XMP sidecar metadata                        |
 | `metadata set`               | Manually set metadata fields                        |
 | `metadata generate`          | Generate metadata with AI (Ollama)                  |
@@ -77,13 +91,12 @@ schenesort browse                  # uses paths.wallpaper from config
 schenesort get --mood peaceful -b  # browse query results
 ```
 
-![Browse example - Greek](docs/browse-greek.png)
-
 ![Browse example - Autumn](docs/browse-autumn.png)
 
 ![Browse example - Stallman](docs/browse-stallman.png)
 
 **Keyboard shortcuts:**
+
 | Key          | Action         |
 |--------------|----------------|
 | `j` / `Down` | Next image     |
@@ -95,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:
@@ -133,6 +203,38 @@ schenesort stats
 
 The database is stored at `$XDG_DATA_HOME/schenesort/index.db` (default: `~/.local/share/schenesort/index.db`).
 
+## Collage Generation
+
+Create a collage grid (up to 4x4) from wallpapers matching query criteria:
+
+```bash
+# Create a 2x2 collage (default)
+schenesort collage output.png --mood peaceful
+
+# Create a 4x4 collage of landscape images
+schenesort collage wall.png --subject landscape --cols 4 --rows 4
+
+# Custom tile size (default: 480x270)
+schenesort collage collage.png --tile-width 640 --tile-height 360
+
+# Combine filters
+schenesort collage night_cities.png --time night --subject urban --cols 3 --rows 2
+```
+
+`schenesort collage landscape.png --cols 4 --rows 4 --tile-width 640 --tile-height 360 --tag landscape`
+
+![Collage example](docs/landscape.png)
+
+| Option          | Description                          | Default |
+|-----------------|--------------------------------------|---------|
+| `--cols`        | Number of columns (1-4)              | 2       |
+| `--rows`        | Number of rows (1-4)                 | 2       |
+| `--tile-width`  | Width of each tile in pixels         | 480     |
+| `--tile-height` | Height of each tile in pixels        | 270     |
+| `--random`      | Select images randomly               | True    |
+
+All `get` query filters are supported: `--tag`, `--mood`, `--color`, `--style`, `--subject`, `--time`, `--screen`, `--min-width`, `--min-height`, `--search`.
+
 ## Metadata Management
 
 Store metadata in XMP sidecar files (`.xmp`) alongside images without modifying the original files.
@@ -154,7 +256,7 @@ Store metadata in XMP sidecar files (`.xmp`) alongside images without modifying
 | `source`             | Source URL or info                                       |
 | `ai_model`           | Model used for metadata generation                       |
 
-### Generate Metadata with AI
+### Generate Metadata using ollama
 
 ```bash
 # Preview what would be generated
@@ -231,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`)
 
@@ -308,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.2.0 → schenesort-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "schenesort"
-version = "2.2.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.2.0"
+current_version = "2.4.0"
 commit = true
 tag = true
 tag_name = "v{new_version}"