Metadata-Version: 2.4
Name: photo-s-tools
Version: 1.7.1
Summary: 批量图片压缩与格式转换工具 — Batch Image Compression & Format Conversion (CLI + GUI)
Author: PhotoS Contributors
License-Expression: MIT
Keywords: image,compression,photo,batch,RAW,JPEG,WebP
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.4.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: rawpy>=0.18.0
Provides-Extra: raw
Provides-Extra: exif
Requires-Dist: piexif>=1.1.3; extra == "exif"
Provides-Extra: watch
Requires-Dist: watchdog>=3.0.0; extra == "watch"
Provides-Extra: gui
Requires-Dist: tkinterdnd2>=0.3.0; extra == "gui"
Provides-Extra: heic
Requires-Dist: pillow-heif>=0.5.0; extra == "heic"
Provides-Extra: avif
Requires-Dist: pillow-avif-plugin>=1.0; extra == "avif"
Provides-Extra: enhance
Requires-Dist: opencv-python-headless>=4.6.0; extra == "enhance"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.20; python_version >= "3.10" and extra == "mcp"
Provides-Extra: all
Requires-Dist: piexif>=1.1.3; extra == "all"
Requires-Dist: watchdog>=3.0.0; extra == "all"
Requires-Dist: pillow-heif>=0.5.0; extra == "all"
Requires-Dist: pillow-avif-plugin>=1.0; extra == "all"
Requires-Dist: tkinterdnd2>=0.3.0; extra == "all"
Requires-Dist: opencv-python-headless>=4.6.0; extra == "all"
Requires-Dist: mcp<2,>=1.20; python_version >= "3.10" and extra == "all"
Dynamic: license-file

# 📷 PhotoS

<!-- mcp-name: io.github.Dongwu259/photo-s -->

[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-photo--s--tools-orange)](https://pypi.org/project/photo-s-tools/)

**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** · [中文](docs/README.zh-CN.md)

---

## 🤖 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** — 19 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`](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, 11 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 | — | ✅ | 19 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

```bash
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

```bash
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 22 commands. Language: `--language en|zh|auto`.

---

## 🧭 Documentation

| Doc | Contents |
|---|---|
| [`docs/FEATURES.md`](docs/FEATURES.md) | Full inventory — 22 CLI commands, engine pipeline |
| [`docs/AGENT_API.md`](docs/AGENT_API.md) | Agent contract: JSON shapes, exit codes, REST, MCP |
| [`docs/PLUGINS.md`](docs/PLUGINS.md) | Plugin system: SCUNet denoise, LUT, write your own |
| [`docs/GUI_CHANGES.md`](docs/GUI_CHANGES.md) | GUI behavior & interface contract |
| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Version roadmap (v1.6.0: Lightroom-direction grading) |

> Names: PyPI distribution **`photo-s-tools`** (the obvious `photo-s` is taken) ·
> CLI command `photo-s` · Python package `photo_s` · brand **PhotoS**.

---

## ⚠️ Limitations

PhotoS is a **batch / delivery pipeline**, not an interactive editor — no brush masks yet (v1.8), no RAW-domain editing.

- **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
