📘 ELSAC User Guide

Organize, score, and curate your character images for consistent LoRA training.

Run python app.py and open http://127.0.0.1:7860. Projects live in characters/ next to the app.

📁 Step 1 · Project Setup

Create a New Project — enter your character's name in Create New Character.
Upload Raw Images — drag images into Upload Raw Images, then click Create Project. ELSAC builds characters/<name>/raw_images.
Resume later — pick a project under Resume Existing Project and click Load Project. Progress is restored automatically.

🔍 Step 2 · Clustering

Click Run Clustering — CLIP + HDBSCAN group similar images into cluster_0, cluster_1, … and outliers.
Browse groups anytime in the Image Viewer. Typically cluster_0 holds the main identity.
Re-running replaces the previous result — no stale folders.

⭐ Step 3 · Single-Reference Scoring

Pick a cluster folder → Load Cluster Images → click your best, most representative image.
Click Run Single-Reference Scoring — every image is compared to that reference.
Results are copied into buckets under scored/general_likeness/: 95_plus_godtier90_95_excellent85_90_good80_85_okbelow_80_review

👤 Step 4 · Face Likeness Scoring

A specialized pass for facial consistency — ELSAC detects, crops, and aligns faces before comparing.

Pick a General Likeness bucket and load its images.
Choose a reference with a clear, front-facing face.
Click Run Face Likeness Scoring → output goes to scored/face_likeness/.

👥 Step 5 · Multi-Reference Scoring (Recommended)

The strongest pass: 4–8 references are combined into one averaged identity.

Load images from Face Likeness buckets (or other scored folders).
Click to preview, then Add to Selection 4–8 images with varied angles, lighting, and expressions.
Click Run Multi-Reference Scoring → results in scored/multi_likeness/ with reference_set/ and scoring_results.csv.

🔬 Step 6 · Technical Analysis

Pick the target folder (multi_likeness, general_likeness, or face_likeness).
Click Run Technical Analysis — metrics: Blur (Laplacian), Face Ratio, Head Yaw.
CSVs land in analyzed/: quality_analysis_*.csv + quality_summary_*.csv. Preview & download them in the Step 6 tabs.

💡

Final tips

For your best set, draw from 95_plus_godtier and 90_95_excellent in scored/multi_likeness/.
Prefer images labeled excellent or good in Step 6 reports.
Face-based scores (Steps 4–5) are more identity-specific than whole-image scores.
Wide / full-body shots are often flagged "face too small" — use it as a framing filter, not a blanket reject.

🖼️ Use the Image Viewer anytime to browse every project folder · 📊 The Progress panel tracks completed steps and survives reloads.

📚 Dataset Recommendations

What to shoot (and collect) so your LoRA learns the character — not just one scene.

🎯

Core principle

Your dataset must teach three things:

Identity (face consistency) — most important
Body & proportions — prevents a “floating-head” LoRA
Context robustness — prevents overfitting to one scene

📊 The 40-image plan: aim for at least 40 images for a basic character. (My own characters use ~240 — but this plan walks through 40.)

🧠 Tier 1 — Face & Identity 18 images

📷

Close Portraits

Framing: head to upper chest · Purpose: lock facial identity

Include:

neutral expressionslight smileconfident lookoff-camerastudio lightwindow lighteditorial lightnight/neon

face sharp
eyes clearly visible
no heavy shadows hiding features

🧍

Waist-Up Shots

Framing: waist to head · Purpose: connect face to upper body

Mix:

casual standingrelaxed posestyle/attitudecandidslight motionclothing variety

Lighting variety is important here.

🧍 Tier 2 — Body Understanding 16 images

🚶

Three-Quarter Shots

Framing: mid-thigh to head · Purpose: body proportions + posture

Variety:

standing relaxedhand on hipwalkingseatedspecial pose

keep anatomy natural
avoid extreme foreshortening early on

🕴️

Full Body

Framing: full body · Purpose: global body coherence

Include:

neutral standingcasual walkspecial place poseindoors fulloutdoor casuallifestyle candid

face still reasonably visible
avoid tiny distant shots

🎭 Tier 3 — Lifestyle Personality 6 images

Inject character flavor with images special to your character. Example — a rockstar who loves art and sports:

rock starsportyartistic

🧹

Final reminders

Quality over quantity — a sharp, consistent 40 beats a messy 200.
Run Step 6 (Technical Analysis) to catch blur and tiny faces before training.
Your final set = overlap of high likeness (Steps 3–5) and high quality (Step 6).

📚 More resources

More tools 🐙 GitHub