novafarma/docs/TRANSPARENCY_WIPE_WORKFLOW.md

🎨 TRANSPARENCY WIPE - SAFE WORKFLOW

Created: 12.01.2026 06:43 CET
Purpose: Remove solid backgrounds from all assets
Status: READY - BACKUP FIRST!

---

⚠️ CRITICAL: BACKUP FIRST!

Step 1: Create Backup

cd /Users/davidkotnik/repos/novafarma
cp -r assets/ assets_BACKUP_$(date +%Y%m%d_%H%M%S)

This will create: assets_BACKUP_20260112_064300/

Confirms backup:

du -sh assets_BACKUP_*

---

🔍 Step 2: DRY RUN (Test Safe!)

Run script in safe mode:

python3 tools/transparency_wipe.py assets/references/ --dry-run

This will:

• ✅ Scan all PNG files
• ✅ Report which would be processed
• ❌ NOT modify anything!

Example output:

✅ Would process: kai_master.png (white background detected)
✅ Would process: tree_oak.png (gray background detected)
⏭️  Skipped: ana_nobg.png (already transparent)

📊 RESULTS:
  ✅ Would process: 342
  ⏭️  Skipped: 828

---

🔥 Step 3: LIVE RUN (Only if dry-run looks good!)

AFTER reviewing dry-run results:

python3 tools/transparency_wipe.py assets/references/ --live

Confirmation required:

⚠️  WARNING: LIVE RUN MODE!
Are you sure? Type 'YES' to continue: YES

This will:

• ✅ Remove solid backgrounds (white, black, gray)
• ✅ Make images transparent
• ✅ Overwrite original files (BACKUP EXISTS!)
• ✅ Skip already transparent images

---

🎯 How It Works:

Detection:

1. Checks 4 corners of image
2. If all corners are similar color → likely background
3. If color is white/black/gray → process!

Processing:

1. Identifies background color (from corners)
2. Creates transparency mask
3. Makes matching pixels transparent
4. Saves as PNG with alpha channel

Edge Smoothing:

• Uses tolerance (30px color difference)
• Preserves anti-aliasing
• Gradual transparency at edges

---

📊 What Gets Processed:

YES (Will be processed):

• ✅ Images with white background
• ✅ Images with black background
• ✅ Images with gray background
• ✅ Images with solid color corners

NO (Will be skipped):

• ❌ Already transparent images
• ❌ Images with complex backgrounds
• ❌ Images in BACKUP folders

---

🛡️ Safety Features:

1. DRY RUN MODE - Test first!
2. Backup required - Manual step
3. Confirmation - Must type YES
4. Skip processed - Avoids re-processing
5. Error handling - Reports failures

---

📋 Recommended Workflow:

Morning (06:45):

# 1. BACKUP (5-10min)
cp -r assets/ assets_BACKUP_20260112

# 2. DRY RUN - Test references (1min)
python3 tools/transparency_wipe.py assets/references/ --dry-run

# 3. Review results
# - Check numbers make sense
# - Verify which files would change

If Dry Run Looks Good:

# 4. LIVE RUN - References first (10-20min)
python3 tools/transparency_wipe.py assets/references/ --live

# 5. Visual check (5min)
# - Open few processed images
# - Verify transparency looks good
# - Check edges are smooth

If References OK:

# 6. Process PHASE_PACKS (20-30min)
python3 tools/transparency_wipe.py assets/PHASE_PACKS/ --live

Total Time: ~1 hour (with checks)

---

⚠️ WHAT THIS WON'T DO:

Script CANNOT:

• ❌ "Color grade" images (Noir filter)
• ❌ Manually smooth dreadlocks
• ❌ Auto-sync with Tiled
• ❌ Match colors between images

For that, you need:

• Photoshop Batch Actions
• GIMP Color Correction
• Manual adjustments

---

🎨 Post-Processing (Manual):

If you want "Noir Color Grade":

Option A: GIMP Batch

1. Open GIMP
2. Filters → Batch Process
3. Apply Color Curve (noir filter)
4. Export all

Option B: Photoshop Action

1. Record Action (noir color grade)
2. File → Automate → Batch
3. Apply to folder

Option C: ImageMagick

# Apply noir color curve
for img in assets/references/**/*.png; do
  convert "$img" -modulate 100,80,100 -colorspace Gray "$img"
done

---

📊 Expected Results:

Before Transparency Wipe:

• 342 images with white/gray/black backgrounds
• Visible squares in Tiled
• Color mismatch

After Transparency Wipe:

• 342 images with transparency
• No white squares in Tiled
• Clean compositing

Still need manual:

• Color matching
• Edge smoothing (if script isn't perfect)
• Tiled tileset refresh

---

🚨 TROUBLESHOOTING:

Problem: Script removes too much

• Solution: Increase tolerance in script (line 18)
• Change tolerance=30 to tolerance=40

Problem: Edges look jagged

• Solution: Manual smoothing in GIMP
• Select → Grow → Feather → Delete

Problem: Wrong color removed

• Solution: Script detects corners
• Make sure subject NOT in corners!

---

✅ GO / NO-GO CHECKLIST:

Before running LIVE:

• Backup created (assets_BACKUP_* exists)
• Backup verified (same size as original)
• Dry-run completed
• Dry-run results reviewed
• Results look reasonable (~300-500 files)
• NOT running on entire assets/ (too risky!)
• Starting with assets/references/ only
• Coffee ready ☕

---

Status: ⏸️ WAITING FOR BACKUP COMMAND APPROVAL
Next: Backup → Dry Run → Review → Live Run
Time: ~1 hour total

Ready when you are, HIPO! 🎨✨