docs: Add Step 0 - Training image creation without the app

- Clarifies no app/Mac/Xcode needed for training data collection
- Documents photography setup for foils (angles, black bg, raking light)
- Documents photography setup for damage and non-foil cards
- Explains the cropping rule and why it matters for model accuracy
- Lists free cropping tools for Windows and cross-platform
- Image quantity guide (min vs recommended per class)
- Explains Scryfall image downloads as a NonFoil supplement

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-05 13:04:31 -05:00
parent 15abf823be
commit b848a7b169

View File

@@ -271,7 +271,83 @@ Also add `PrivacyInfo.xcprivacy` to the app target to satisfy Apple's privacy ma
## Part 5: Machine Learning Training — Mac Required for Final Step ## Part 5: Machine Learning Training — Mac Required for Final Step
Training images can be collected on any device. Model training itself requires Create ML on a Mac. **You do not need the app, Xcode, or a Mac to collect training images.** All you need is physical cards and a phone camera. The only Mac-required step is the final model training in Create ML (Step 6).
> **The app ships and works without any trained models.** Foil detection defaults to "None" and condition defaults to "NM". You can release a working app first and add models later via OTA update. Do not let missing training data block your first build.
---
### Step 0: How to Create Training Images (No App Required)
This is the complete workflow for preparing training data on any computer.
#### What You Need
- Physical Magic cards (see shopping lists in Steps 13)
- A phone with a decent camera (iPhone, Android — anything works)
- A plain background: white card stock or black felt works best
- A free photo cropping tool:
- **Windows:** Photos app (built-in crop) or Paint
- **Any platform:** [Squoosh](https://squoosh.app) (browser-based, free, no install)
- **Bulk cropping:** [IrfanView](https://www.irfanview.com) (Windows, free) or [XnConvert](https://www.xnview.com/en/xnconvert/) (cross-platform, free)
#### Photography Setup
**For Foil Cards:**
1. Place the card on a **black background** (black felt or black paper).
2. Use a single directional light source — a desk lamp or window at 45°.
3. Take **5 photos of the same card** rotating it slightly between each shot so the light catches the foil at different angles. The AI must learn how the foil *moves*, not just how it looks flat.
4. Example angles: flat-on, 15° left tilt, 15° right tilt, 15° top tilt, 15° bottom tilt.
**For Non-Foil Cards:**
1. Place on **white or grey background**.
2. Even, diffused lighting (avoid strong reflections on the surface).
3. 13 photos per card is sufficient.
**For Condition/Damage:**
1. Use **raking light** (light source almost parallel to the card surface) — this casts shadows that highlight scratches, dents, and bends far more clearly than direct light.
2. For edge whitening: photograph against a **black background**.
3. For chipping: photograph against a **white background**.
4. Take a close-up — fill the frame with the card.
#### Cropping Rule — Critical
The app scans **cropped card images only** (no table, no background, no hand visible). Your training images must match this exactly or the model will learn the wrong thing.
After photographing:
1. Open the photo in your cropping tool.
2. Crop tightly to the card border — include the full card frame but nothing outside it.
3. It does not need to be pixel-perfect. Within 510px of the edge is fine.
4. Save as `.jpg` at any reasonable resolution (at least 400×560px).
#### Naming and Sorting
File names do not matter — only the **folder** they are in matters. Save cropped images directly into the appropriate `IYmtg_Training/` subfolder:
```
IYmtg_Training/Foil_Data/Etched/ ← drop etched foil photos here
IYmtg_Training/Foil_Data/Traditional/ ← drop traditional foil photos here
IYmtg_Training/Condition_Data/Edges/Whitening/ ← drop edge whitening photos here
```
#### How Many Images Do You Need?
| Goal | Minimum | Recommended |
| :--- | :--- | :--- |
| Test that training works | 10 per class | — |
| Functional model, limited accuracy | 20 per class | — |
| Solid production model | 3050 per class | 50+ per class |
| High-accuracy model | — | 100+ per class |
More is always better. Variety matters more than quantity — different cards, different lighting, different tilt angles.
#### Using Scryfall Images as a Supplement
For **NonFoil** training data you can download card images directly from Scryfall instead of photographing them. This is automated — run:
```bash
pip install requests pillow
python3 IYmtg_Automation/fetch_set_symbols.py
```
This downloads and crops set symbol images automatically. For general NonFoil card images, you can query the Scryfall API directly (`https://api.scryfall.com/cards/random`) and download the `normal` image URI. Downloaded Scryfall images are already cropped to the card frame and work well as NonFoil training data. Do not use Scryfall images for foil or damage training — they are flat renders with no foil or physical damage.
---
### General Data Collection Protocol (Critical) ### General Data Collection Protocol (Critical)
The app sends **cropped** images (just the card, no background) to the AI. Your training data must match this. The app sends **cropped** images (just the card, no background) to the AI. Your training data must match this.
@@ -283,8 +359,6 @@ The app sends **cropped** images (just the card, no background) to the AI. Your
3. **Sort:** Place the cropped image into the corresponding folder in `IYmtg_Training`. 3. **Sort:** Place the cropped image into the corresponding folder in `IYmtg_Training`.
4. **Quantity:** Aim for 30-50 images per category for robust results. 4. **Quantity:** Aim for 30-50 images per category for robust results.
> **Note:** The app works without trained models — foil detection defaults to "None" and condition defaults to "NM". You can ship a working app and add ML models later via OTA update.
### Step 1: The Master Foil Shopping List (Required for FoilEngine) ### Step 1: The Master Foil Shopping List (Required for FoilEngine)
Acquire one of each (~$50 total) to train the Foil Classifier. This ensures the app can distinguish complex modern foil types. Acquire one of each (~$50 total) to train the Foil Classifier. This ensures the app can distinguish complex modern foil types.