# PhotoS

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Dongwu259/photo_s  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/photos

## Description
Batch photo processing: compress, convert, EXIF, rename, dedup, cull, galleries

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "photos": {
    "command": "npx",
    "args": ["-y","photos"]
  }
}
```

## Documentation & README

# 📷 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 — v2.0 workspace with Library / Develop (live
pipeline preview + histogram + edit tools beside it) / Export (photo queue +
output settings) / Tools modules — 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** · [中文](https://github.com/Dongwu259/photo_s/blob/HEAD/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** — 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`](https://github.com/Dongwu259/photo_s/blob/HEAD/docs/AGENT_API.md).

---

## ✨ Features

| Feature | GUI | CLI | Description |
|---|---|---|---|
| Batch compress | ✅ | ✅ | JPEG/WebP/HEIC/AVIF quality tuning, chroma subsampling (444/422/420) |
| 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); demosaic algorithm choice, color space (sRGB/AdobeRGB/ProPhotoRGB), 16-bit TIFF output, auto sRGB ICC tagging |
| 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 |
| Export sharpen | ✅ | ✅ | LR-style output-stage USM, radius scales with output resolution |
| 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); named user-maintained lens profiles |
| 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 |
| Highlight recovery | ✅ | ✅ | LR-style: compress flat clipped highlights back to visible gradient |
| LOG recovery | ✅ | ✅ | SLOG3/CLOG3/LOGC3/DLOG/VLOG/HLG (1D LUT, no deps) |
| LUT grading | ✅ | ✅ | .cube trilinear (plugin adds tetrahedral + 5 film presets) |
| AI auto-tone | — | ✅¹ | Plugin: CLIP+MLP predicts 9-field LR params + confidence, RAG boost, optional Qwen3-VL aesthetic score & advisor (`photo-s-plugin-auto-tone[model]`) |
| 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) |
| Cutout | ✅ | ✅ | Background removal → alpha: AI segmentation (`subject`/`person`/`object:class`) or color key (`color:R,G,B[tol,feather,invert]` — white-bg text/logo); PNG/WebP/TIFF/AVIF/HEIC (JPEG errors per file) |
| 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 + built-in `lr-look` (LR-style grade: S-curve, vibrance, export sharpen) |
| 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

```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[tiff16]"  # + tifffile: 16-bit RAW → TIFF output
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 batch 'RAW/*.ARW' -o out/ -q 95 --jpeg-subsampling 444 \
  --raw-demosaic amaze                                # max quality RAW → JPEG
photo-s batch 'RAW/*.ARW' -o out/ --preset lr-look     # LR-style grade out of the box
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 34 commands. Language: `--language en|zh|auto`.

---

## 🧭 Documentation

| Doc | Contents |
|---|---|
| [`docs/FEATURES.md`](https://github.com/Dongwu259/photo_s/blob/HEAD/docs/FEATURES.md) | Full inventory — 34 CLI commands, engine pipeline |
| [`docs/AGENT_API.md`](https://github.com/Dongwu259/photo_s/blob/HEAD/docs/AGENT_API.md) | Agent contract: JSON shapes, exit codes, REST, MCP |
| [`docs/PLUGINS.md`](https://github.com/Dongwu259/photo_s/blob/HEAD/docs/PLUGINS.md) | Plugin system: SCUNet denoise, LUT, write your own |
| [`docs/GUI_CHANGES.md`](https://github.com/Dongwu259/photo_s/blob/HEAD/docs/GUI_CHANGES.md) | GUI behavior & interface contract |
| [`docs/ROADMAP.md`](https://github.com/Dongwu259/photo_s/blob/HEAD/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 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 most official model weights (incl. the SCUNet
  checkpoint) are **MIT** — free for commercial use. Exception: the auto-tone
  plugin's weights are **CC-BY-NC 4.0** (non-commercial, trained on personal
  Lightroom edits; see `plugins/auto-tone/LICENSE-WEIGHTS.txt`). Third-party
  plugins and models carry their own licenses; verify before redistribution.

## 📄 License

MIT