📷 PhotoS
CLI for AI agents, GUI for humans. PhotoS is a cross-platform batch photo toolbox: a full Tkinter GUI (visual preview, review & rate lightbox, dedup viewer, gallery export) for photographers — and a CLI / REST / MCP surface with one versioned JSON contract for AI agents.
🖥 GUI for humans · ⌨️ CLI for AI agents ·
pip install photo-s-tools
English · 中文
🤖 Built for AI agents
PhotoS is an AI-agent-ready image pipeline: four integration paths, one versioned
JSON contract (schema_version, additive-only — upgrades never break a consumer).
| Path | Entry point |
|---|---|
| MCP server — 25 tools (process / select / hdr / blurfaces / dedup / …) | claude mcp add photo-s -- photo-s mcp |
| Packaged SKILL.md — skill-capable agents, zero extras | cp -r skills/photo-s ~/.claude/skills/ |
| REST API — async tasks + SSE progress | photo-s serve --port 0 --token auto --ready-file x.json |
| Python library — no IPC overhead | from photo_s.engine import batch_process |
Every output carries schema_version; JSON keys are always English; per-file
errors never abort the batch; destructive actions require an explicit flag.
Full contract: docs/AGENT_API.md.
✨ Features
| Feature | GUI | CLI | Description |
|---|---|---|---|
| Batch compress | ✅ | ✅ | JPEG/WebP/HEIC/AVIF quality tuning |
| Target size mode | ✅ | ✅ | Auto-tune quality to fit under a target file size |
| Format convert | ✅ | ✅ | JPEG / PNG / WebP / TIFF / BMP / HEIC / AVIF |
| RAW decode | ✅ | ✅ | 22+ camera RAW formats, built-in (rawpy/libraw) |
| Resize / Scale | ✅ | ✅ | Max dimensions, percentage, or longest-side cap |
| Visual preview | ✅ | — | Live original↔processed preview rendered through the real pipeline |
| Tone & color | ✅ | ✅ | Brightness/contrast/saturation/gamma/sharpen, B&W, sepia |
| White balance | ✅ | ✅ | Kelvin temperature or gray-card sampling |
| WB tint axis | ✅ | ✅ | Green(-)/magenta(+) G-M axis |
| Point curves / levels | ✅ | ✅ | PCHIP point curves, manual black/white/gamma |
| 3-way color grading | ✅ | ✅ | Shadows/midtones/highlights hue + sat zones |
| HSL split | ✅ | ✅ | 8 color domains, hue/sat/lum shifts |
| Point color | ✅ | ✅ | Targeted hue/sat/lum around a sampled color + range |
| Local masks | ✅ | ✅ | Named linear/radial/color-range masks + v1.8 AI segmentation (subject/person/object:class), brush strokes (subtract mode), combos (A&B / A-B); 11 scalar + 5 string local adjustments under each |
| Lens correction | ✅ | ✅ | Manual distortion k1, vignette fix, CA fix (pure numpy) |
| Perceptual analysis | ✅ | ✅ | Histograms / channel stats / WB lean / exposure / blur (analyze) |
| Vibrance / clarity / texture | ✅ | ✅ | Natural saturation, local contrast |
| Dehaze / vignette / grain | ✅ | ✅ | Dark-channel dehaze, radial vignette, film grain |
| Exposure | ✅ | ✅ | Stops adjustment or normalize-to-target auto exposure |
| Auto levels | ✅ | ✅ | 2% clip histogram stretch |
| LOG recovery | ✅ | ✅ | SLOG3/CLOG3/LOGC3/DLOG/VLOG/HLG (1D LUT, no deps) |
| LUT grading | ✅ | ✅ | .cube trilinear (plugin adds tetrahedral + 5 film presets) |
| Denoise | ✅ | ✅¹ | NLM ([enhance] extra) |
| Auto-straighten | ✅ | ✅¹ | Level the horizon, confidence-gated ([enhance] extra) |
| HDR merge | ✅ | ✅¹ | Exposure fusion, handheld alignment ([enhance] extra) |
| Face blur | ✅ | ✅¹ | Blur or pixelate faces, Haar cascade ([enhance] extra) |
| Crop / Rotate / Flip / Pad | ✅ | ✅ | Unified aspect crop + arbitrary geometry |
| Print size | ✅ | ✅ | Center-crop + exact print pixels at a DPI |
| Smart rename | ✅ | ✅ | Date/camera/sequence templates |
| Auto folder organize | ✅ | ✅ | Date/camera subfolder creation |
| Watermark | ✅ | ✅ | Text + image overlay, 7 positions |
| Multi-size output | ✅ | ✅ | One input set, N labeled outputs |
| Metadata tagging | ✅ | ✅ | Rating/keywords/caption batch tag (UserComment) |
| Metadata filter | ✅ | ✅ | Find photos by rating/keywords |
| Metadata import | — | ✅ | Batch write from spreadsheet |
| Culling | ✅ | ✅ | Exposure/sharpness filter (GUI keeps only matches, undoable) |
| Select (keeper) | ✅ | ✅ | Sort by rating — keep/reject thresholds (≥4 keep, ≤2 reject) |
| Burst keep-sharpest | ✅ | ✅ | Keep the sharpest of a burst |
| Checksum manifest | ✅ | ✅ | SHA-256 archive integrity + verify |
| HTML gallery | ✅ | ✅ | Self-contained index.html + thumbnails |
| Presets | ✅ | ✅ | Save/load named configs |
| Multi-profile batch | — | ✅ | One input set, N output profiles |
| Parallel processing | ✅ | ✅ | Multi-threaded |
| JSON output | — | ✅ | Machine-readable output for AI agents |
| Config file | — | ✅ | TOML defaults |
| EXIF edit | — | ✅ | Batch copyright/author/GPS |
| Preset apply | — | ✅ | One-click apply a saved style |
| EXIF date shift | — | ✅ | Timezone/camera clock fixes |
| Privacy scrub | — | ✅ | Strip EXIF + ICC + GPS |
| Sync date | — | ✅ | Output mtime ← EXIF datetime |
| Folder watch | ✅ | ✅ | Auto-process new files ([watch] extra) |
| Auto-rotate | ✅ | ✅ | EXIF Orientation-based |
| Image dedup | ✅ | ✅ | Perceptual hash duplicate detection |
| Quality metrics | ✅ | ✅ | SSIM / blur score |
| CSV report | — | ✅ | Per-file stats |
| Integrity check | — | ✅ | Corrupt file scan |
| Contact sheet | ✅ | ✅ | Grid montage |
| Color management | — | ✅ | sRGB / CMYK flatten |
| REST API | — | ✅ | HTTP server for agents (async tasks + SSE progress) |
| Plugin system | — | ✅ | Third-party plugin support |
| Official plugin manager | — | ✅ | list/install/info/fetch + pip install |
| MCP server | — | ✅ | 25 tools to MCP clients (Claude Desktop / Claude Code / any MCP client) |
| Batch benchmark | — | ✅ | Worker-scaling measurement |
¹ Denoise / auto-straighten / HDR / face blur need an optional dependency:
pip install photo-s-tools[enhance](opencv-python-headless). When missing, these features give a clear install hint and the rest keeps working.
📦 Install
pip install photo-s-tools # core — RAW decode (rawpy) built in
pip install "photo-s-tools[enhance]" # + opencv: face blur / HDR / denoise / straighten
pip install "photo-s-tools[mcp]" # + MCP server (Python 3.10+)
Zero-install (uvx): uvx --from photo-s-tools photo-s --help ·
uvx --from "photo-s-tools[mcp]" photo-s mcp
🚀 Quick start
photo-s batch 'RAW/*.ARW' --format jpeg -o out/ -q 90 # batch RAW → JPEG
photo-s compress *.jpg --target-size 5MB -j 8 # auto-tune to ≤5MB
photo-s select ~/shoot/ -r --selects-dir picks --rejects-dir bin --dry-run
photo-s hash ~/deliver/ -o manifest.csv --verify manifest.csv
photo-s --help lists all 33 commands. Language: --language en|zh|auto.
🧭 Documentation
| Doc | Contents |
|---|---|
docs/FEATURES.md |
Full inventory — 33 CLI commands, engine pipeline |
docs/AGENT_API.md |
Agent contract: JSON shapes, exit codes, REST, MCP |
docs/PLUGINS.md |
Plugin system: SCUNet denoise, LUT, write your own |
docs/GUI_CHANGES.md |
GUI behavior & interface contract |
docs/ROADMAP.md |
Version roadmap (v1.6.0: Lightroom-direction grading) |
Names: PyPI distribution
photo-s-tools(the obviousphoto-sis taken) · CLI commandphoto-s· Python packagephoto_s· brand PhotoS.
⚠️ Limitations
PhotoS is a batch / delivery pipeline, not an interactive editor — no RAW-domain editing. Local editing is spec-driven: named masks (linear/radial/color/AI segmentation/brush strokes/combos) + local adjustments under masks, all as compact strings that serialize through CLI/REST/MCP/presets.
- On-device inference, no cloud. Denoise model weights (SCUNet) download to your machine on first use; nothing is uploaded.
- Licensing. Official code and official model weights (incl. the SCUNet checkpoint) are MIT — free for commercial use. Third-party plugins and models carry their own licenses; verify before commercial redistribution.
📄 License
MIT
1 maintainer
Release files for photo-s-tools 1.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| photo_s_tools-1.8.0.tar.gz | 421.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| photo_s_tools-1.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 733.5 kB
Release files / photo_s_tools-1.8.0.tar.gz
| Download URL | photo_s_tools-1.8.0.tar.gz |
|---|---|
| Size | 421.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6d3609467eff2c4b13151360ab0bbf3093d3ee30dc5d7195caa8308177b21f63
|
|
BLAKE2b-256 checksum How to use checksums |
b41504dd98694d0daabe3fb29f7d876a17fee1cb0f5adf799f4acddf5bd1ad9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logRelease files / photo_s_tools-1.8.0-py3-none-any.whl
| Download URL | photo_s_tools-1.8.0-py3-none-any.whl |
|---|---|
| Size | 311.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a607088807fd003e78d5de3b888b69bfe43a1f13f26d51c2811ffacab7657ed
|
|
BLAKE2b-256 checksum How to use checksums |
1799471250e9c7a3d898b710c77d5977784db949a92f5bd2f66f5cd923549343
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency log
