Human aes expert

Portrait Retouch Skill

Intelligent portrait retouching that analyzes before editing — only fixes what's broken, preserves everything else.

When to Activate

• User wants to retouch or enhance a portrait photo
• User mentions "skin", "lighting", "wrinkles", "blemishes", "clothing fit"
• User asks for "aesthetic analysis" or "portrait improvement"
• User wants style transfer between portrait images

Architecture

Input Portrait ──► Gemini Analysis (12-Dim Scoring) ──► Aesthetic Score Report
                                                                │
                                                                ▼
Enhanced Portrait ◄── Gemini Image Edit ◄── Targeted Prompt (only low dimensions)

Core Principles

1. Non-destructive: Never remove/add/relocate background objects unless explicitly requested
2. Precision targeting: Only dimensions scoring below threshold get improvement prompts
3. Identity preservation: Subject must remain recognizable as the same person
4. Professional specificity: Name exact techniques ("fill light on face") not vague goals ("make it better")

The 12 Aesthetic Dimensions

Dimension	What It Measures	Priority
Facial Skin Tone	Skin color naturalness, uniformity, color cast	1.5x
Facial Brightness	Face illumination, shadow/highlight balance	1.3x
Outfit	Clothing fit, wrinkle-free, visual coherence	1.2x
Environment	Background lighting consistency	1.1x
Facial Feature Clarity	Sharpness of eyes, nose, lips, eyebrows	1.0x
Facial Aesthetic	Overall facial harmony and proportion	0.95x
Facial Contour Clarity	Edge sharpness of face outline	0.9x
Overall Aesthetic	Holistic image quality	0.85x
Looks	Expression engagement, eye contact	0.8x
Facial Structure	Bone structure visibility, symmetry	0.7x
General Appearance	Grooming, tidiness	0.6x
Composition	Subject placement, headroom	0.5x
Body Shape	Posture quality, proportion in frame	0.4x

Scoring Criteria

Scoring is STRICT — most casual photos score 5-7, only professional-grade gets 8+.

Score	Rating	Action
8-10	Excellent	Minor refinements only
7	Good	Enhancement recommended
5-6	Acceptable	Targeted improvement needed
0-4	Poor	Priority correction required

Prompt Construction Logic

1. Score all 12 dimensions via Gemini vision analysis
2. Filter dimensions below threshold (default: 7.0)
3. Rank by priority weight (facial > body > environment)
4. Map each low dimension to a specific improvement instruction
5. Wrap in preservation rules that lock identity, pose, and background

Preservation Rules (Always Enforced)

• Background objects: Never removed, added, or relocated
• Identity: Face and recognizable features preserved exactly
• Pose & body: Same body position, hand gestures, head/body angle
• Clothing & accessories: Unchanged unless explicitly requested
• Expression: Facial expression, eye gaze, smile must remain pixel-identical
• No new dots: NEVER add any new black/dark dots, specks, points, acne, or marks on the face

Intensity Levels

Level	Skin	Face Shape	Eyes/Lips	Body Skin
Subtle	Remove obvious blemishes/acne (keep pores/texture)	NO slimming	NO eye changes	Light evening
Moderate	Smooth wrinkles, even tone, remove temporary blemishes/acne (preserve natural skin texture)	NO slimming	Reduce eye bags, NO eye changes	MUST match face
Aggressive	Strongly smooth, clean skin, remove temporary blemishes/acne (still preserve some pore texture)	NO slimming	Remove eye bags, NO eye changes	IDENTICAL to face

All levels FORBID: Any face reshaping/slimming, over-brightening, expression changes, adding new black dots/moles/acne, making person unrecognizable, altering eyes/pupils/gaze.

Usage Modes

1. Auto-Enhance Mode

Analyzes all 12 dimensions, applies non-destructive enhancements to low-scoring areas.

2. Analysis-Only Mode

Returns aesthetic scores without applying changes. Useful for preview.

3. User-Guided Mode

User instructions integrated alongside auto improvements while respecting preservation rules.

Running the Server

cd /path/to/PortraitRetouch
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
python server.py

Server runs at http://127.0.0.1:8000

API Reference

See references/API.md for complete endpoint documentation.

Key Files

File	Purpose
src/agents/aesthetic_analyzer.py	12-dimension scoring engine
src/agents/retouch_planner.py	Prompt construction with constraints
src/agents/interaction_memory.py	Multi-turn session memory
src/processors/face_local_retouch.py	High-resolution face region processing
src/prompts/system_prompts.py	All system prompts and improvement maps

Example: Low Environment Score

If environment scores 5/10, the constructed prompt will say:

"Improve environmental lighting and color consistency: correct any color cast in the background, balance ambient lighting with facial lighting. Do NOT remove, add, or relocate any background objects."

It will NOT say "clean up background" — vague instructions cause destructive edits.