PortraitEdit AI Studio

Professional portrait editing, AI masks and automatic 8×10 alignment. Engineered & Powered by Centaq Production Team

What it does

A desktop photo editor for portrait and studio photographers. It works on photos where they already are (nothing is copied), saves every edit by itself, and exports at full quality.

• Import — an Import window: see every photo found, Check All / Uncheck All or pick by hand, Include subfolders. Photos already in the Library can't be added twice, and a dropped photo imports only that photo.
• Formats — JPG, PNG, TIFF, WebP, HEIC/HEIF (iPhone), AVIF, GIF, PSD and camera RAW (DNG, CR2, CR3, NEF, ARW, RAF, ORF, RW2, PEF and more).
• Library — Grid of every photo, Loupe for one, filmstrip, colour labels, sort, search. Remove (Delete) really takes photos out of the Library (with Undo); disk files are untouched.
• Fast editing — photos are prepared in the background when they enter the Library (like standard previews), so opening and editing don't wait. Only AI masks show a progress bar. Each open photo is also rendered at full resolution in the background (like 1:1 previews), so zooming in, out or to 100% is instant and sharp.
• Orientation — phone photos open upright automatically (EXIF). Rotate Left/Right with Ctrl+[ / Ctrl+] or Photo › Rotate. The turn is saved and used everywhere, including exports.
• Crop & Straighten — ratios, Angle slider, Auto level, 90° turns, X swaps portrait/landscape. Drag outside the crop box to turn the photo with the mouse; Ctrl/⌘-drag is the Straighten tool.
• Metadata — Keywording and Metadata panels: the camera's EXIF (camera, lens, exposure, date, GPS), plus your own Title, Caption, Keywords, Creator, Copyright and custom fields, all searchable and written into exports (EXIF + XMP).
• Histogram — clipping shown on the photo (J), drag a zone to change Blacks, Shadows, Exposure, Highlights or Whites; camera settings and RGB % underneath.
• More panels — Tone Curve, Color Grading, Detail (sharpening, noise reduction), Effects (vignette, grain) and Calibration.
• Auto — Auto tone and white balance (Ctrl+U, Ctrl+Shift+U). Sync can match light and colour across a series shot in changing light.
• Culling — 1–5 stars, Pick/Reject flags (P/X/U), rating and flag filters, Remove Rejected.
• Colour — Colour Mixer with Point Color (pick any colour, shift it), White Balance picker (W), with an eyedropper and magnifier.
• Develop — Basic panel (linear-light Exposure and White Balance, edge-aware Highlights/Shadows, Clarity, Texture, Dehaze, Vibrance), Colour Mixer, crop, and before/after views. Grid and filmstrip thumbnails show the edits.
• AI masks — Subject (any main subject, fine hair edges), Face, Skin, Hair, Clothes, Background, Objects, Brush, Color Range, Luminance, and Linear/Radial gradients. You can stack several masks per photo.
• Presets — 10 built-in develop presets plus your own. Import Lightroom presets (.xmp / .xml / .lrtemplate) and export yours as .xmp. Copy, paste or sync an edit to many photos.
• Export — JPEG, PSD, TIFF, PNG, WebP or the original file, with resize, sharpening, metadata, watermark and colour space. There are 5 built-in export presets, plus one-click File › Export with Preset.
• Pub_Casual — automatic head-safe 8:10 crop at 640 × 800 px, 300 dpi, JPEG 100.
• Catalog — folders, edits, labels and presets survive restarts. You can create a portable package with the photos.
• Menus — File, Edit, Library, Photo, Metadata, View, Window and Help, plus right-click menus on photos (grid, filmstrip, canvas) and folders. Every command shows its shortcut, and shortcuts can be reassigned.
• Themes — 7 themes plus an accent colour.
• LAN access — open the interface from a phone or tablet on the same Wi-Fi.

Supported platforms

Python 3.9 – 3.12 (64-bit), with 3.12 recommended. The AI libraries (MediaPipe, onnxruntime) have no wheels for 3.13+ in the tested versions.

Quick start

Windows

1. Install Python 3.12 (64-bit) — tick Add python.exe to PATH — and the Microsoft Visual C++ Redistributable (x64).
2. Double-click INSTALL.bat to install packages and create shortcuts, or run.bat to just start.
3. Full requirements, the offline model download and how to build the installer are in WINDOWS_SETUP.md.

After the first run, START_APP_no_console.vbs starts the app without a console window.

macOS

App: open PortraitEdit_AI_Studio_v6.1_macOS.dmg and drag the app to Applications. The first time, right-click it › Open (or System Settings › Privacy & Security › Open Anyway), because it is not notarised by Apple. To build the app yourself, double-click BUILD_MAC_APP.command.

From source: double-click run.command. The first run creates .venv-mac and installs everything, which takes a few minutes. Later runs start straight away.

./run.command --check   # set up and verify only
./run.command --reset   # rebuild the environment

If macOS blocks it, right-click → Open, or run chmod +x run.command.

User guide

The guide is short, with screenshots, in English and हिंदी:

1. In the app — Help › User Guide, or press F1.
2. In a browser — http://localhost:5000/guide.
3. As a file — GUIDE.md. Its screenshots are in static/guide/.

Requirements

requirements.txt installs:

Hardware. Everything runs on the processor (CPU); the graphics card is not used for processing, so a studio PC such as a Core i5 (10th gen) with a GT 1030 is fine. The app measures this computer's speed and tunes its background work to it. Help › Performance shows the result, and a faster or upgraded computer is picked up by itself.

AI models live in models/:

What the app reads

Only what you add, and never a copy: photos (even dragged and dropped ones) are used where they are. If they are moved or deleted they stay in the Library marked ! with their edits, and Locate… re-links them.

The app reads the folders and photos you import, its own program files and its data folder, and it writes only exports (where you choose) and that data folder. It never searches your Desktop, Documents, other drives or the rest of your computer. Background work (thumbnails, edit previews) covers only Library photos and stops when it is done.

Where things are stored

Original photos are never modified. Exports are written only where you choose.

Troubleshooting

Development

pip install -r requirements.txt
python app.py                    # starts on http://127.0.0.1:5000 (or the next free port)

python test_masks.py             # 68 mask checks
python test_develop.py           # 62 slider / mask / rotation / straighten / format / import checks
python check_health.py           # packages, models, files, ports

Code map:

The full technical reference is in DOCUMENTATION.md, and what changed in each release is in CHANGELOG.md.

Building

BUILD_APP.bat refuses to build without mediapipe and onnxruntime, and downloads the Subject model if it is missing. Both specs bundle models/, static/ (including the guide screenshots), templates/ and GUIDE.md.

Clean build: delete build/, dist/ and installer_output/.

Project structure

HeadAlign_v4.2/
├── app.py · engine.py · requirements.txt
├── templates/index.html
├── static/
│   ├── js/app.js · css/style.css · icon.ico · icon.png
│   └── guide/                      # screenshots used by GUIDE.md
├── models/                         # AI models (see Requirements)
├── haarcascade_frontalface_default.xml · sRGB_IEC61966-2-1.icc
│
├── GUIDE.md                        # user guide (English + हिंदी, shown in the app)
├── README.md · DOCUMENTATION.md · CHANGELOG.md · WINDOWS_SETUP.md · RELEASE_NOTES_v6.0.md
├── test_masks.py · test_develop.py · check_health.py
│
├── run.command                     # macOS launcher (from source)
├── BUILD_MAC_APP.command           # macOS .app + .dmg build
├── run.bat · START_APP_no_console.vbs · start_hidden.bat · Launch_App.vbs
├── INSTALL.bat · Install_App.ps1 · UNINSTALL.bat
├── BUILD_APP.bat · BUILD_INSTALLER.bat · PortraitEdit_Setup.iss
├── PortraitEdit_Distribute.spec · PortraitEdit_macOS.spec · static/icon.icns
└── DIAGNOSE.bat · CHECK_SYSTEM.bat · START_HERE.txt

Release history

Support

• Guide: Help › User Guide (F1)
• System check: Help › System Check, or python check_health.py
• Windows report: DIAGNOSE.bat → DIAGNOSE_REPORT.txt
• Crash log: PortraitEdit_log.txt