AutoPics

Automated image preparation and compression tool.

AutoPics is a desktop application for preparing and compressing product or catalog images in batches. It provides a Qt-based GUI for selecting source/output folders, applying optional image cleanup/enhancement steps, and exporting optimized files in modern formats.

What AutoPics does

• Batch-processes images from a source folder into a target comp folder.
• Supports output to JPEG, AVIF, JPEG XL, and PNG.
• Lets you choose quality presets (High / Medium / Low) or enforce a target size standard. PNG High / Medium / Low reduce the image to a colour palette with libimagequant (alpha kept); the size target works for these too. The PNG Dither slider (0-100%, default from standardPngDither in defaults.txt) trades a little file size for less banding.
• Lossless option for PNG (Pillow optimised), JPEG XL (true lossless) and AVIF (near-lossless: max quality, 4:4:4). Lossless files can't be sized to the target.
• Includes optional image operations:
  • automatic trimming of flat-color borders,
  • color enhancement,
  • sharpness enhancement,
  • standard or custom max-dimension resize,
  • keep transparent backgrounds (PNG / AVIF / JPEG XL output) instead of flattening onto white.
• Uses parallel processing to speed up large batches.
• Displays run results in-app and previews output images while processing.

Tech stack

• Python
• PySide6 for the desktop GUI
• Pillow for image manipulation
• pillow-avif-plugin and pillow-jxl-plugin for AVIF/JXL support
• imagequant (libimagequant) for lossy PNG palettes and dithering

Requirements

• Python 3.14+ (as defined in pyproject.toml)
• A platform supported by PySide6 and your selected image codec plugins

Installation

This project uses uv in its lockfile workflow.

uv sync

If you do not use uv, install dependencies manually from pyproject.toml:

pip install pyside6 pillow-avif-plugin pillow-jxl-plugin imagequant

Running the app

From the project root:

uv run AutoPics.py

Usage overview

1. Click Browse and select your source image folder.
2. Confirm or adjust the output comp folder path.
3. (Optional) Enter a rename prefix for generated files.
4. Configure settings:
   • quality mode,
   • resize behavior,
   • output format,
   • enhancement options.
5. Click Process.
6. Review the output summary and generated files in the comp folder.

Project structure

• AutoPics.py — main GUI application.
• picComp.py — batch orchestration, encoding logic, and multiprocessing pipeline.
• imageEditing.py — reusable image editing utilities.
• standards.py — loads defaults.txt; shared by the GUI and the MCP server.
• mcp_server.py — MCP server exposing the pipeline to an AI agent.
• third_party_licenses/ — bundled third-party license texts.

MCP server

mcp_server.py exposes the same pipeline over the Model Context Protocol, so an AI agent can inspect a folder of images and compress it without the GUI. It runs headless — it imports picComp and imageEditing directly and never starts Qt.

Setup

uv sync --group mcp

Copy .env.example to .env and set AUTOPICS_ALLOWED_ROOTS to the folders the server is allowed to touch. Then register it in Claude Desktop's claude_desktop_config.json:

"autopics": {
  "command": "C:\\Users\\jp\\Desktop\\CodeProjects\\AutoPics\\.venv\\Scripts\\python.exe",
  "args": ["C:\\Users\\jp\\Desktop\\CodeProjects\\AutoPics\\mcp_server.py"]
}

Tools

Tool	What it does
autopics_inspect_images	Read-only. Dimensions, size, format, mode and alpha for files or a folder.
autopics_get_defaults	Read-only. The standards from defaults.txt and what each one controls.
autopics_compress_batch	The Process button. Compresses a folder or file list; supports dry_run.
autopics_process_image	Edits and encodes a single image to an explicit output path.

Configuration

Variable	Default	Meaning
AUTOPICS_ALLOWED_ROOTS	unset	Comma-separated directories the server may read and write. Unset means no restriction, which is not recommended when an agent is driving.
AUTOPICS_MAX_IMAGES	200	Batches larger than this are refused before anything is written.
AUTOPICS_TIMEOUT_SECONDS	600	Wall-clock limit for one tool call.
AUTOPICS_MAX_WORKERS	CPU default	Worker count for the batch pool.

Notes

• stdout is the JSON-RPC channel. Nothing in the pipeline may print to it, so picComp and imageEditing log through standards.log(), which writes to stderr, and mcp_server.py additionally redirects file descriptor 1 to stderr so worker processes cannot corrupt the protocol.
• The MCP path uses threads, the GUI uses processes. A spawned ProcessPoolExecutor does not survive running inside the stdio server process — the workers start, do the work, and their results never come back. PicComp(use_processes=False) switches to a ThreadPoolExecutor; Pillow releases the GIL during encode and decode, so this is no slower in practice.
• The server pins mcp<2. Version 2.x renames FastMCP to MCPServer and changes other APIs.

Licensing

• Project license: see LICENSE.
• Third-party notices: see files under [third_party_licenses/](thiAutomated image preparation and compression tool.
• Third-party notices: see files under third_party_licenses/.