diff --git a/README.md b/README.md index de611cf..71f3d2d 100644 --- a/README.md +++ b/README.md @@ -388,23 +388,95 @@ Acquire pairs of cards to train the `StampDetector` (Promo/Date Stamped vs. Regu * **Action:** Place cropped images of promos in `Stamp_Data/Stamped` and regular versions in `Stamp_Data/Clean`. ### Step 3: The "Damage Simulation Lab" -Techniques to ethically create training data using "Draft Chaff" (worthless cards). -| Category | Damage Type | Simulation Technique | Capture Tip (Crucial for ML) | -| :--- | :--- | :--- | :--- | -| **Surface** | Light Scratches | Rub foil surface gently with 0000 Steel Wool. | Use flash or moving light source to catch glint. | -| **Surface** | Clouding | Rub white eraser vigorously over foil surface. | Compare side-by-side with a clean card. | -| **Surface** | Dirt | Smudge lightly with potting soil or cocoa powder. | Ensure contrast against card art. | -| **Surface** | Dents | Press a ballpoint pen cap firmly into the surface. | **Raking Light:** Light from side to cast shadows. | -| **Edges** | Whitening | Rub card edges rapidly against denim jeans. | Photograph against a **Black Background**. | -| **Edges** | Chipping | Flake off small bits of black border. | Photograph against a **White Background**. | -| **Edges** | Corner Wear | Rub corners against a rough mousepad. | Macro focus on the corner radius. | -| **Structure** | Creases | Fold a corner until a hard line forms. | Catch the light reflection off the crease ridge. | -| **Structure** | Shuffle Bend | Riffle shuffle aggressively to create an arch. | Profile view (side view) to show curvature. | -| **Structure** | Water Damage | Mist with spray bottle, wait 60s, dry. | Catch the rippled surface texture with side light. | -| **Critical** | Inking | Use a Black Sharpie to "fix" whitened edges. | Use UV/Blacklight if possible, or bright white light. | -| **Critical** | Rips | Tear the edge slightly (approx. 5mm). | High contrast background. | -| **Critical** | Binders Dents | Press a 3-ring binder ring into the card. | Raking light to show the circular crimp. | +#### Important: This Model Uses Object Detection, Not Image Classification + +The `Condition_Data` model is trained as an **Object Detection** model, not an Image Classification model. This is a critical difference: + +- **Image Classification** (used for Foil and Stamp): drop images in a folder, Create ML labels them by folder name. Simple. +- **Object Detection** (used for Condition): you must **draw bounding boxes** around each defect in Create ML. The model learns *where* damage is on the card, not just that damage exists. + +When training in Create ML, you will annotate each training image by drawing a rectangle around the damaged area and labeling it (e.g., "LightScratches", "Whitening"). Create ML has a built-in annotation tool — click an image, draw a box, type the label. + +**Folder naming maps directly to label names.** The labels must match the `Condition_Data` subfolder names exactly: +`LightScratches`, `Clouding`, `Dirt`, `Dents`, `Whitening`, `Chipping`, `CornerWear`, `Creases`, `ShuffleBend`, `WaterDamage`, `Inking`, `Rips`, `BindersDents` + +#### How the Grading Formula Works + +Understanding this helps you know what training data matters most. The app grades cards as follows (from `ConditionEngine.swift`): + +| Detected Damage | Grade Assigned | +| :--- | :--- | +| Any `Inking`, `Rips`, or `WaterDamage` detected | **Damaged** — immediately, regardless of anything else | +| 0 damage detections | **Near Mint (NM)** | +| 1–2 minor damage detections | **Excellent (EX)** | +| 3 or more minor damage detections | **Played (PL)** | + +**Critical damage types** (`Inking`, `Rips`, `WaterDamage`) are the highest training priority — a single false positive will incorrectly grade a NM card as Damaged. + +#### Materials List + +| Item | Used For | +| :--- | :--- | +| 0000 (ultra-fine) steel wool | Surface scratches on foil cards | +| White vinyl eraser | Clouding/surface haze | +| Potting soil or cocoa powder | Dirt simulation | +| Ballpoint pen cap (rounded end) | Dents | +| Black Sharpie marker | Inking simulation | +| Spray bottle with water | Water damage | +| 3-ring binder | Binder dents | +| Rough mousepad or sandpaper | Corner wear | +| 50–100 bulk "draft chaff" cards | Cards to damage | +| Black felt or black paper | Background for edge photos | +| White card stock | Background for chipping photos | +| Desk lamp | Raking light source | + +#### Sourcing Cards to Damage + +Buy bulk worthless cards — do not damage your own collection. +- **eBay:** Search "MTG bulk commons lot" — 1000 cards for ~$10 +- **TCGPlayer:** "Bulk commons" listings, often $0.01/card +- **Local game store:** Ask for "draft chaff" — often given away free + +Also buy **pre-damaged cards** — natural damage looks more authentic to the model than simulated: +- **eBay:** Search "MTG damaged cards lot" or "heavily played bulk" + +Aim for **50 cards per damage type** minimum. One card can be used for multiple damage types since each photo annotates only one damage area. + +#### Raking Light Setup (Required for Surface and Structure Damage) + +Most damage is invisible under flat overhead light. Raking light reveals it. + +1. Place the card flat on a dark surface. +2. Position your desk lamp so light hits the card at a near-horizontal angle (5–15° above the surface) from one side. +3. The damage will cast visible shadows or catch the light clearly. +4. For scratches: slowly rotate the card until the scratches "light up" — photograph at that angle. + +#### Damage Simulation Techniques + +| Category | Damage Type | Folder Name | Simulation Technique | Photography Tip | +| :--- | :--- | :--- | :--- | :--- | +| **Surface** | Light Scratches | `LightScratches` | Rub foil surface gently with 0000 Steel Wool in one direction. | Raking light from the scratched direction. Rotate until scratches catch light. | +| **Surface** | Clouding | `Clouding` | Rub white vinyl eraser vigorously over foil surface in circles. | Diffused light. Compare side-by-side with a clean card for reference. | +| **Surface** | Dirt | `Dirt` | Press a damp fingertip into potting soil, then onto card surface. | Even lighting. Ensure dirt contrasts against the card art. | +| **Surface** | Dents | `Dents` | Press rounded end of a ballpoint pen cap firmly straight down. | Raking light at 10° to cast shadow inside the dent. | +| **Edges** | Whitening | `Whitening` | Rub card edges rapidly back and forth against denim jeans. | Black background. Macro close-up of the edge. | +| **Edges** | Chipping | `Chipping` | Use fingernail to carefully flake small pieces off the black border. | White background. Macro close-up. | +| **Edges** | Corner Wear | `CornerWear` | Rub corners against a rough mousepad with a circular motion. | Macro focus on the corner. Black background. | +| **Structure** | Creases | `Creases` | Fold corner sharply until a hard crease forms, then unfold. | Raking light to catch reflection off the crease ridge. | +| **Structure** | Shuffle Bend | `ShuffleBend` | Riffle shuffle the card aggressively 10+ times to create an arch. | Profile/side view to show curvature clearly. | +| **Structure** | Water Damage | `WaterDamage` | Mist card lightly with spray bottle, wait 60 seconds, air dry flat. | Raking light to show rippled surface texture. | +| **Critical** | Inking | `Inking` | Draw along whitened edges with black Sharpie to simulate edge touch-up. | UV/blacklight if available; otherwise strong white light at angle. | +| **Critical** | Rips | `Rips` | Tear edge slightly (~5mm). | High contrast background opposite to card border color. | +| **Critical** | Binder Dents | `BindersDents` | Press a 3-ring binder ring firmly into the card surface. | Raking light to show the circular crimp. | + +#### What to Photograph per Damage Type + +For each damage type, capture: +1. **30–50 cards showing that damage clearly** — positive training examples +2. **10–20 completely clean (undamaged) cards** — include these in every subfolder so the model learns the baseline + +When annotating in Create ML, draw the bounding box **tightly around the damaged area only**. For shuffle bends, annotate the center of the arch. For edge damage, annotate the specific section of edge that is damaged, not the entire edge. ### Step 4: The "Edge Case" Validation List Acquire these specific cheap cards to verify the logic-based detectors. **Note:** These are for **Manual Verification** (testing the app), not for Create ML training folders.