From b848a7b169fceff2755b222e73c831ef543677b1 Mon Sep 17 00:00:00 2001 From: Mike Wichers Date: Thu, 5 Mar 2026 13:04:31 -0500 Subject: [PATCH] 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 --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 77 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7d29d7e..de611cf 100644 --- a/README.md +++ b/README.md @@ -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 -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 1–3) +- 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. 1–3 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 5–10px 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 | 30–50 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) 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`. 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) Acquire one of each (~$50 total) to train the Foil Classifier. This ensures the app can distinguish complex modern foil types.