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**
```bash
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:**
```bash
du -sh assets_BACKUP_*
```

---

## 🔍 Step 2: DRY RUN (Test Safe!)

**Run script in safe mode:**
```bash
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:**
```bash
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):**
```bash
# 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:**
```bash
# 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:**
```bash
# 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**
```bash
# 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!** 🎨✨