ShotSieve is a local-first photo culling app. It analyzes images on your machine, ranks them with optional learned image-quality models, and gives you the final keep/reject decision in a visual review workflow. The default server binds to loopback; your photo library is not uploaded by ShotSieve.
- Scans local photo folders and builds a reusable catalog.
- Scores supported images with learned quality models when the optional model runtime is available.
- Compares models on the same library.
- Provides Review filters, keep/reject decisions, and copy, move, and delete actions.
- Keeps the catalog, previews, model caches, and review UI local by default.
| Runtime | Best fit | Boundary |
|---|---|---|
| CPU | Any supported source install; packaged support is platform/architecture-specific | Broadest fallback; learned models still need enough RAM and disk. |
| NVIDIA CUDA | Supported NVIDIA GPUs | The current x64 path uses PyTorch 2.14.0 from the cu130 index and covers the architectures published by that wheel. Driver, VRAM, and model support still apply. |
| Intel XPU | Intel GPU/OS combinations in the pinned PyTorch XPU matrix | Available as Windows/Linux runtime packs and as a source-install track. |
| AMD ROCm | AMD's current OS/driver matrix | The Windows/Linux packs use the stable ROCm 10.0 PyTorch packages with gfx1103 kernels. Hardware support remains specific to AMD's live matrix. |
| Apple MPS | Apple Silicon Macs supported by the installed PyTorch build | Available as a macOS arm64 runtime pack. Intel Macs must use a source CPU installation; no packaged Intel macOS runtime is published. |
A runtime pack proves that the software stack can be built, not that every GPU
from that vendor is supported. Auto mode can fall back to CPU and reports the
reason; an explicit cuda, xpu, rocm, or mps request fails when that
runtime is unusable. ShotSieve checks Intel XPU architecture compatibility and
concrete ROCm GPU architecture mismatches before selecting those runtimes.
Fatal accelerator failures stop scoring instead of retrying each photo;
ordinary image or batch failures keep the individual-image fallback.
Windows ROCm TOPIQ/CLIPIQA use a scoped BatchNorm workaround that preserves
MIOpen convolutions and requires no external compiler installation.
See the build guide,
Intel XPU guide, and AMD ROCm guide
for the pinned boundaries and validation commands.
The release matrix contains ten runtime packs:
- Windows: CPU, NVIDIA CUDA, Intel XPU, AMD ROCm
- Linux: CPU, NVIDIA CUDA, Intel XPU, AMD ROCm
- macOS arm64: CPU and Apple MPS
Packaged macOS runtimes are Apple Silicon (arm64) only. The bootstrap launcher rejects Intel macOS rather than selecting an incompatible arm64 archive. Intel Macs can use the source installation with CPU scoring.
Current launcher names are:
| Platform | Runtime | Launcher |
|---|---|---|
| Windows | CPU | ShotSieve-CPU.exe |
| Windows | NVIDIA CUDA | ShotSieve-NVIDIA-CUDA.exe |
| Windows | Intel XPU | ShotSieve-Intel-XPU.exe |
| Windows | AMD ROCm | ShotSieve-AMD-ROCm.exe |
| Linux | CPU | ShotSieve-CPU |
| Linux | NVIDIA CUDA | ShotSieve-NVIDIA-CUDA |
| Linux | Intel XPU | ShotSieve-Intel-XPU |
| Linux | AMD ROCm | ShotSieve-AMD-ROCm |
| macOS arm64 | CPU | ShotSieve-CPU |
| macOS arm64 | Apple MPS | ShotSieve-Apple-MPS |
The current target and launcher names are required for fresh downloads. Retired vendor-only names and target aliases are not accepted by the current release tooling.
For a source or editable install:
python -m pip install -e .
python -m pip install -e ".[learned-iqa,format-loaders]"
shotsieve-desktopThe first command is enough for cataloging and Review. The optional extras add learned-IQA scoring and HEIF/RAW loaders. For a tested, pinned source setup for learned-IQA, follow docs/building.md.
For a downloaded runtime pack, launch the bundled ShotSieve-* executable
from the archive instead of shotsieve-desktop.
Useful options:
shotsieve-desktop --data-dir ./shot-data
shotsieve-desktop --model-cache-dir ./model-cache
shotsieve-desktop --host 127.0.0.1 --port 9001 --no-browser
shotsieve-desktop --check-runtimeSee configuration.md for CLI precedence, cache environment variables, offline mode, and UI analysis settings.
Source checkouts and frozen bundles default to a data/ directory next to the
checkout or launcher. Installed packages outside a checkout use the platform
app-data directory. --data-dir overrides either choice. The database is
data/shotsieve.db, previews are under data/previews/, and runtime sidecars
and install logs are under data/runtime/.
Portable runtime packs are torchless: PyTorch is installed into the selected
sidecar on first use after interactive consent or explicit
SHOTSIEVE_BOOTSTRAP_AUTO_INSTALL_TORCH=1. A declined, offline, or failed
install leaves Catalog and Review available, but learned-IQA scoring disabled.
Before installing or repairing Torch or learned-IQA dependencies, ShotSieve
checks the selected sidecar path and probes the filesystem for deep filenames.
If a portable folder is too deeply nested, move the entire ShotSieve folder
to a shorter location (for example C:\ShotSieve) and start it again. This
check runs before dependency downloads; the portable data/runtime/ layout
is unchanged.
Model weights are separate downloads and are never included in a release
archive. Use Settings > Prepare selected model after the runtime is ready.
- Open
Libraryand add one or more photo folders. - Run
Analyzeto scan and, when a model is ready, score supported images. - Use
Reviewto filter the catalog and make keep/reject decisions. - Use
Compareto evaluate models on the same library when needed. - Use
Settingsfor runtime information, model preparation, missing-entry cleanup, resource settings, and decision CSV export.
The supported model catalog is intentionally small:
topiq_nr- TOPIQ, the default all-rounder. Recommended for a first run.clipiqa- a complementary CLIP-based scorer.qrealign-mini- the compact Q-ReAlign Mini model
Model availability is discovered from the installed runtime. A model listed in the catalog is not a certification of every accelerator; the local runtime must initialize successfully. Model and checkpoint terms are separate from ShotSieve's license; see THIRD_PARTY_LICENSES.md.
An ordinary scan only updates files it discovers in that run. It does not remove cached rows, scores, or review decisions outside the selected roots, recursion, extension, or ignore-rule coverage. Enumeration errors are shown as errors rather than being treated as an empty folder.
Removing verified missing entries is a separate reviewed action in Settings. Unavailable or unmounted roots are treated as unknown and are not treated as a list of missing files.
Copy, move, and delete are explicit actions. Their operation results retain per-file status, error details, and retry safety. Completed mutations remain visible if a later file fails or a job is cancelled; uncertain mutations are left for manual inspection rather than silently retried.
Review uses one shared local catalog. The active library scope is shown separately from All libraries (global), and the queue is paged at 60 photos by default. Filters include score, format, dimensions, megapixels, file size, metadata completeness, path, and review state.
The default review server is 127.0.0.1:8765 and accepts requests only from
loopback clients with a loopback Host header. --host changes the address the
server binds to; it does not enable remote or LAN access.
- docs/building.md - source installs, testing, runtime packs, and release builds.
- docs/architecture.md - data flow, ownership, persistence, jobs, and compatibility boundaries.
- docs/configuration.md - CLI, environment, cache, model, and UI analysis configuration.
- docs/api.md - local CLI, HTTP route, job, and frontend interface reference.
- docs/troubleshooting.md - common setup, runtime, browser, cache, and operation failures.
- docs/contributing.md - safe changes and verification guidance.
- docs/intel-xpu.md - Intel XPU prerequisites and smoke evidence.
- docs/amd-rocm.md - AMD ROCm prerequisites and smoke evidence.
- docs/performance-measurement.md - opt-in catalog, scan, preview, and model-performance measurements.
- docs/frontend-workflows.md - frontend module ownership and public workflow facade.
- docs/accessibility-checklist.md - manual visual-usability checks; it is not a broad accessibility conformance claim.
- THIRD_PARTY_LICENSES.md - model, package, and runtime license boundaries.
- CHANGELOG.md - release history.
ShotSieve is licensed under the GNU Affero General Public License v3.0 or later. Optional learned-IQA packages, model weights, base models, vendor runtimes, and drivers have their own terms. Review those terms before redistribution or commercial use.