.

.justfile

@@ -1,19 +1,62 @@
-# Scry build recipes
+# Scry development commands
+# Android SDK paths
 
-# Default recipe - show available commands
+android_sdk := env_var('LOCALAPPDATA') / "Android/Sdk"
-default:
+adb := android_sdk / "platform-tools/adb.exe"
-    @just --list
+emulator := android_sdk / "emulator/emulator.exe"
+camera_virtual := "-camera-back virtualscene -virtualscene-poster wall=\"" + (justfile_directory() / "TestImages/reference_alpha/serra_angel.jpg") + "\""
+camera_webcam := "-camera-back webcam0 -camera-front webcam0"
 
-# Build both standard and embedded versions for all platforms
+emu camera="virtual":
-build apk="delver.apk":
+    {{ emulator }} -avd Pixel_6 {{ if camera == "virtual" { camera_virtual } else { camera_webcam } }} -gpu host &
-    rm -rf dist
-    dotnet publish -c Release -r win-x64 -o dist/win-x64/standard
-    dotnet publish -c Release -r win-x64 -p:EmbeddedApk={{apk}} -o dist/win-x64/embedded
-    dotnet publish -c Release -r linux-x64 -o dist/linux-x64/standard
-    dotnet publish -c Release -r linux-x64 -p:EmbeddedApk={{apk}} -o dist/linux-x64/embedded
-    dotnet publish -c Release -r osx-x64 -o dist/osx-x64/standard
-    dotnet publish -c Release -r osx-x64 -p:EmbeddedApk={{apk}} -o dist/osx-x64/embedded
 
-# Clean build artifacts
+# Kill the running emulator
-clean:
+emu-kill:
-    rm -rf bin obj dist
+    {{ adb }} emu kill
+
+# Wait for emulator to fully boot
+emu-wait:
+    @echo "Waiting for emulator to boot..."
+    @while [ "$({{ adb }} shell getprop sys.boot_completed 2>/dev/null)" != "1" ]; do sleep 1; done
+    @echo "Emulator ready"
+
+# Build a project
+build project="src/Scry.App" target="net10.0-android":
+    @echo "Building {{ project }}..."
+    dotnet build {{ project }} -f {{ target }} -c Debug
+    @echo "Build complete"
+
+# Publish a project (creates distributable)
+publish project="src/Scry.App" target="net10.0-android":
+    @echo "Publishing {{ project }} (this takes a while)..."
+    dotnet publish {{ project }} -f {{ target }} -c Release
+    @echo "Publish complete"
+
+# Install APK to emulator/device
+install:
+    {{ adb }} install -r src/Scry.App/bin/Release/net10.0-android/publish/land.charm.scry-Signed.apk
+
+# Launch the app on emulator/device
+launch:
+    {{ adb }} shell am start -n land.charm.scry/crc64fb23cc0d511b0157.MainActivity
+
+# Publish, install, and launch
+run: (publish "src/Scry.App") install launch
+
+# View app crash logs
+logs:
+    {{ adb }} logcat -d | grep -iE "land.charm.scry|scry|mono|dotnet" | tail -80
+
+# Run tests
+test:
+    dotnet test test/Scry.Tests
+
+# Generate the card hash database from Scryfall
+gen-db *args: (build "tools/DbGenerator" "net10.0")
+    @echo "Running Database generator (this takes a while)..."
+    dotnet run --project tools/DbGenerator --no-build -- src/Scry.App/Resources/Raw/card_hashes.db {{ args }}
+    @echo "Completed generating the database"
+
+# Full workflow: start emulator, wait, run with hot reload
+dev: emu emu-wait
+    dotnet watch --project src/Scry.App -f net10.0-android

AGENTS.md

@@ -0,0 +1,30 @@
+# Agent Instructions
+
+## Build and Task Commands
+
+Prefer using `just` commands over raw dotnet/build commands:
+
+| Task | Command |
+|------|---------|
+| Build project | `just build` |
+| Run tests | `just test` |
+| Generate card database | `just gen-db` |
+| Publish app | `just publish` |
+| Run full dev workflow | `just dev` |
+
+## Project Structure
+
+- `src/Scry.App` - MAUI mobile app
+- `src/Scry.Core` - Core library (recognition, hashing, database)
+- `test/Scry.Tests` - Unit tests
+- `tools/DbGenerator` - Card hash database generator
+
+## Database Generator
+
+The `just gen-db` command:
+- Builds the DbGenerator tool
+- Runs it against `src/Scry.App/Resources/Raw/card_hashes.db`
+- Supports incremental updates (only downloads missing cards)
+- Prefers LEA/LEB (Alpha/Beta) sets for reference_alpha test cards
+
+Use `--force` flag to rebuild from scratch if needed.

Directory.Build.props

@@ -0,0 +1,10 @@
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <AnalysisLevel>latest</AnalysisLevel>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+</Project>

Directory.Packages.props

@@ -0,0 +1,26 @@
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageVersion Include="CommunityToolkit.Maui" Version="14.0.0" />
+    <PackageVersion Include="CommunityToolkit.Maui.Camera" Version="6.0.0" />
+    <PackageVersion Include="CommunityToolkit.Mvvm" Version="8.4.0" />
+    <PackageVersion Include="Microsoft.Maui.Controls" Version="10.0.30" />
+    <PackageVersion
+            Include="Microsoft.Maui.Controls.Compatibility"
+            Version="10.0.30"
+        />
+    <PackageVersion
+            Include="Microsoft.Extensions.Logging.Debug"
+            Version="10.0.0"
+        />
+    <PackageVersion Include="SkiaSharp" Version="3.119.0" />
+    <PackageVersion Include="Microsoft.Data.Sqlite" Version="9.0.1" />
+
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageVersion Include="xunit" Version="2.9.2" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.2" />
+  </ItemGroup>
+</Project>

Program.cs

@@ -1,369 +0,0 @@
-using System.CommandLine;
-using System.Reflection;
-using System.Text;
-using ICSharpCode.SharpZipLib.Zip;
-using Microsoft.Data.Sqlite;
-using Spectre.Console;
-
-// Ensure UTF-8 output for Unicode characters
-Console.OutputEncoding = Encoding.UTF8;
-
-var dlensArgument = new Argument<FileInfo>("dlens");
-dlensArgument.Description = "Path to the .dlens database file";
-
-var outputOption = new Option<FileInfo?>("--output", "-o");
-outputOption.Description = "Output CSV file path (defaults to collection.csv)";
-
-var showTableOption = new Option<bool>("--show-table", "-t");
-showTableOption.Description = "Display the card collection as a table";
-showTableOption.DefaultValueFactory = _ => false;
-
-#if EMBEDDED_APK
-var rootCommand = new RootCommand("Extract and display card data from Delver Lens")
-{
-    dlensArgument,
-    outputOption,
-    showTableOption
-};
-
-rootCommand.SetAction(async (parseResult, cancellationToken) =>
-{
-    var dlensFile = parseResult.GetValue(dlensArgument)!;
-    var outputFile = parseResult.GetValue(outputOption) ?? new FileInfo("collection.csv");
-    var showTable = parseResult.GetValue(showTableOption);
-    await ProcessFiles(null, dlensFile, outputFile, showTable);
-});
-#else
-var apkArgument = new Argument<FileInfo>("apk");
-apkArgument.Description = "Path to the Delver Lens APK file";
-
-var rootCommand = new RootCommand("Extract and display card data from Delver Lens")
-{
-    apkArgument,
-    dlensArgument,
-    outputOption,
-    showTableOption
-};
-
-rootCommand.SetAction(async (parseResult, cancellationToken) =>
-{
-    var apkFile = parseResult.GetValue(apkArgument)!;
-    var dlensFile = parseResult.GetValue(dlensArgument)!;
-    var outputFile = parseResult.GetValue(outputOption) ?? new FileInfo("collection.csv");
-    var showTable = parseResult.GetValue(showTableOption);
-    await ProcessFiles(apkFile, dlensFile, outputFile, showTable);
-});
-#endif
-
-return await rootCommand.Parse(args).InvokeAsync();
-
-async Task ProcessFiles(FileInfo? apkFile, FileInfo dlensFile, FileInfo outputFile, bool showTable)
-{
-#if !EMBEDDED_APK
-    if (apkFile == null || !apkFile.Exists)
-    {
-        AnsiConsole.MarkupLine($"[red]APK file not found:[/] {apkFile?.FullName}");
-        return;
-    }
-#endif
-
-    if (!dlensFile.Exists)
-    {
-        AnsiConsole.MarkupLine($"[red]dlens file not found:[/] {dlensFile.FullName}");
-        return;
-    }
-
-    List<ScannedCard>? scannedCards = null;
-    List<CollectionCard>? collection = null;
-    var steps = new[] { false, false, false };
-
-    Panel BuildPanel()
-    {
-        var content = $"""
-        [bold yellow]Progress[/]
-
-        {Step(0, "Read scanned cards from dlens")}
-        {Step(1, "Resolve card data from APK")}
-        {Step(2, "Export collection to CSV")}
-        """;
-
-        if (steps[2])
-        {
-            content += $"""
-
-
-            [bold yellow]Summary[/]
-
-            [blue]Your collection:[/] {collection!.Count} unique cards, {collection.Sum(c => c.Quantity)} total
-            [green]Exported to:[/] {outputFile.FullName}
-
-            [bold yellow]How to import into Archidekt[/]
-
-            1. Go to [link]https://archidekt.com/collection[/]
-            2. Click [yellow]Import[/]
-            3. Click [yellow]Add manual column[/] [blue]6 times[/]
-            4. Set the columns in order:
-               • Quantity → [blue]Quantity[/]
-               • Scryfall ID → [blue]Scryfall ID[/]
-               • Foil → [blue]Foil[/]
-               • Card Name → [blue]Ignore[/]
-               • Set Code → [blue]Ignore[/]
-               • Collector Number → [blue]Ignore[/]
-            5. Set [yellow]Skip first row[/] to [blue]true[/] [grey](the CSV has a header)[/]
-            6. Set the csv file by either dragging and dropping it, or clicking the upload box
-            7. Click [yellow]Upload[/]
-            """;
-        }
-
-        return new Panel(content)
-        {
-            Header = new PanelHeader(" Delver Lens → Archidekt "),
-            Border = BoxBorder.Rounded,
-            Padding = new Padding(2, 1)
-        };
-    }
-
-    var spinnerFrames = new[] { "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" };
-    var spinnerIndex = 0;
-    var currentStep = 0;
-
-    string Step(int index, string text)
-    {
-        if (steps[index])
-            return $"[green][[✓]][/] {text}";
-        if (index == currentStep)
-            return $"[blue][[{spinnerFrames[spinnerIndex]}]][/] {text}";
-        return $"[grey][[○]][/] [grey]{text}[/]";
-    }
-
-    // When piped, output CSV to stdout for composability
-    if (Console.IsOutputRedirected)
-    {
-        scannedCards = await GetScannedCards(dlensFile);
-        collection = await ResolveCollection(apkFile, scannedCards);
-        WriteCsvToStdout(collection);
-        return;
-    }
-
-    // Interactive: use live display with progress panel
-    using var cts = new CancellationTokenSource();
-
-    await AnsiConsole.Live(BuildPanel())
-        .StartAsync(async ctx =>
-        {
-            // Spinner animation task
-            var spinnerTask = Task.Run(async () =>
-            {
-                while (!cts.Token.IsCancellationRequested)
-                {
-                    await Task.Delay(80, cts.Token).ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
-                    spinnerIndex = (spinnerIndex + 1) % spinnerFrames.Length;
-                    ctx.UpdateTarget(BuildPanel());
-                }
-            });
-
-            scannedCards = await GetScannedCards(dlensFile);
-            steps[0] = true;
-            currentStep = 1;
-            ctx.UpdateTarget(BuildPanel());
-
-            collection = await ResolveCollection(apkFile, scannedCards);
-            steps[1] = true;
-            currentStep = 2;
-            ctx.UpdateTarget(BuildPanel());
-
-            await ExportCsv(collection, outputFile);
-            steps[2] = true;
-            ctx.UpdateTarget(BuildPanel());
-
-            cts.Cancel();
-            await spinnerTask;
-        });
-
-    // Display table if requested (after live panel completes)
-    if (showTable)
-    {
-        DisplayCollection(collection!);
-    }
-}
-
-async Task<List<CollectionCard>> ResolveCollection(FileInfo? apkFile, List<ScannedCard> scannedCards)
-{
-    var tempDbPath = Path.GetTempFileName();
-    var cardIds = scannedCards.Select(c => c.CardId).ToHashSet();
-
-    try
-    {
-        // Get APK stream from embedded resource or file
-#if EMBEDDED_APK
-        var assembly = Assembly.GetExecutingAssembly();
-        await using var apkStream = assembly.GetManifestResourceStream("delver.apk")
-            ?? throw new Exception("Embedded APK resource not found");
-#else
-        await using var apkStream = apkFile!.OpenRead();
-#endif
-
-        using (var zipFile = new ZipFile(apkStream))
-        {
-            var entry = zipFile.GetEntry("res/raw/data.db");
-            if (entry == null)
-            {
-                throw new Exception("Could not find res/raw/data.db in APK");
-            }
-
-            await using var zipStream = zipFile.GetInputStream(entry);
-            await using var outputStream = File.Create(tempDbPath);
-            await zipStream.CopyToAsync(outputStream);
-        }
-
-        var cardData = new Dictionary<int, (string Name, string SetCode, string CollectorNumber, string ScryfallId)>();
-
-        await using (var connection = new SqliteConnection($"Data Source={tempDbPath};Mode=ReadOnly"))
-        {
-            await connection.OpenAsync();
-
-            await using var cmd = connection.CreateCommand();
-            cmd.CommandText = @"
-                SELECT
-                    c._id,
-                    n.name,
-                    e.tl_abb,
-                    c.number,
-                    c.scryfall_id
-                FROM cards c
-                JOIN names n ON c.name = n._id
-                JOIN editions e ON c.edition = e._id;";
-
-            await using var reader = await cmd.ExecuteReaderAsync();
-            while (await reader.ReadAsync())
-            {
-                var id = reader.GetInt32(0);
-                if (cardIds.Contains(id))
-                {
-                    cardData[id] = (
-                        reader.GetString(1),
-                        reader.GetString(2),
-                        reader.IsDBNull(3) ? "" : reader.GetString(3),
-                        reader.IsDBNull(4) ? "" : reader.GetString(4)
-                    );
-                }
-            }
-        }
-
-        var collection = new List<CollectionCard>();
-        foreach (var scanned in scannedCards)
-        {
-            if (cardData.TryGetValue(scanned.CardId, out var data))
-            {
-                collection.Add(new CollectionCard(
-                    scanned.Quantity,
-                    data.Name,
-                    data.SetCode,
-                    data.CollectorNumber,
-                    data.ScryfallId,
-                    scanned.Foil
-                ));
-            }
-            else
-            {
-                collection.Add(new CollectionCard(
-                    scanned.Quantity,
-                    $"Unknown (ID: {scanned.CardId})",
-                    "",
-                    "",
-                    "",
-                    scanned.Foil
-                ));
-            }
-        }
-
-        return collection;
-    }
-    finally
-    {
-        SqliteConnection.ClearAllPools();
-        if (File.Exists(tempDbPath))
-        {
-            File.Delete(tempDbPath);
-        }
-    }
-}
-
-void DisplayCollection(List<CollectionCard> collection)
-{
-    var table = new Table();
-    table.Border = TableBorder.Rounded;
-    table.AddColumn("Qty");
-    table.AddColumn("Name");
-    table.AddColumn("Set");
-    table.AddColumn("#");
-    table.AddColumn("Foil");
-    table.AddColumn("Scryfall ID");
-
-    foreach (var card in collection.OrderBy(c => c.Name).ThenBy(c => c.SetCode))
-    {
-        table.AddRow(
-            card.Quantity.ToString(),
-            card.Name.Length > 30 ? card.Name[..27] + "..." : card.Name,
-            card.SetCode,
-            card.CollectorNumber,
-            card.Foil ? "[yellow]Yes[/]" : "",
-            card.ScryfallId.Length > 8 ? card.ScryfallId[..8] + "..." : card.ScryfallId
-        );
-    }
-
-    AnsiConsole.Write(table);
-}
-
-async Task ExportCsv(List<CollectionCard> collection, FileInfo outputFile)
-{
-    var sb = new StringBuilder();
-    sb.AppendLine("Quantity,Scryfall ID,Foil,Card Name,Set Code,Collector Number");
-
-    foreach (var card in collection.OrderBy(c => c.Name).ThenBy(c => c.SetCode))
-    {
-        var foilStr = card.Foil ? "Foil" : "Normal";
-        var name = card.Name.Contains(',') ? $"\"{card.Name}\"" : card.Name;
-        sb.AppendLine($"{card.Quantity},{card.ScryfallId},{foilStr},{name},{card.SetCode},{card.CollectorNumber}");
-    }
-
-    await File.WriteAllTextAsync(outputFile.FullName, sb.ToString());
-}
-
-void WriteCsvToStdout(List<CollectionCard> collection)
-{
-    Console.WriteLine("Quantity,Scryfall ID,Foil,Card Name,Set Code,Collector Number");
-
-    foreach (var card in collection.OrderBy(c => c.Name).ThenBy(c => c.SetCode))
-    {
-        var foilStr = card.Foil ? "Foil" : "Normal";
-        var name = card.Name.Contains(',') ? $"\"{card.Name}\"" : card.Name;
-        Console.WriteLine($"{card.Quantity},{card.ScryfallId},{foilStr},{name},{card.SetCode},{card.CollectorNumber}");
-    }
-}
-
-async Task<List<ScannedCard>> GetScannedCards(FileInfo dlensFile)
-{
-    var cards = new List<ScannedCard>();
-
-    await using var connection = new SqliteConnection($"Data Source={dlensFile.FullName};Mode=ReadOnly");
-    await connection.OpenAsync();
-
-    await using var command = connection.CreateCommand();
-    command.CommandText = "SELECT * FROM cards";
-
-    await using var reader = await command.ExecuteReaderAsync();
-    while (await reader.ReadAsync())
-    {
-        var cardId = reader.GetInt32(reader.GetOrdinal("card"));
-        var quantity = reader.GetInt32(reader.GetOrdinal("quantity"));
-        var foil = reader.GetInt32(reader.GetOrdinal("foil")) == 1;
-
-        cards.Add(new ScannedCard(cardId, quantity, foil));
-    }
-
-    return cards;
-}
-
-record ScannedCard(int CardId, int Quantity, bool Foil);
-record CollectionCard(int Quantity, string Name, string SetCode, string CollectorNumber, string ScryfallId, bool Foil);

Scry.csproj

@@ -1,33 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFramework>net10.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <PublishReadyToRun>true</PublishReadyToRun>
-    <PublishSingleFile>true</PublishSingleFile>
-    <SelfContained>true</SelfContained>
-    <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
-    <DebugType>none</DebugType>
-    <DebugSymbols>false</DebugSymbols>
-  </PropertyGroup>
-
-  <PropertyGroup Condition="'$(EmbeddedApk)' != ''">
-    <DefineConstants>$(DefineConstants);EMBEDDED_APK</DefineConstants>
-  </PropertyGroup>
-
-  <ItemGroup Condition="'$(EmbeddedApk)' != ''">
-    <EmbeddedResource Include="$(EmbeddedApk)">
-      <LogicalName>delver.apk</LogicalName>
-    </EmbeddedResource>
-  </ItemGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Data.Sqlite" Version="10.0.2" />
-    <PackageReference Include="SharpZipLib" Version="1.4.2" />
-    <PackageReference Include="Spectre.Console" Version="0.54.0" />
-    <PackageReference Include="System.CommandLine" Version="2.0.2" />
-  </ItemGroup>
-
-</Project>

Scry.slnx

@@ -0,0 +1,9 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/Scry.App/Scry.App.csproj" />
+    <Project Path="src/Scry.Core/Scry.Core.csproj" />
+  </Folder>
+  <Folder Name="/test/">
+    <Project Path="test/Scry.Tests/Scry.Tests.csproj" />
+  </Folder>
+</Solution>

TestImages/README.md

@@ -0,0 +1,151 @@
+# Test Images
+
+This directory contains **225 reference images** for testing card recognition algorithms without requiring actual hardware.
+
+## Directory Structure
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| `reference_alpha/` | 47 | Alpha edition reference cards (old frame) |
+| `varying_quality/` | 38 | Different lighting, blur, exposure, angles |
+| `single_cards/` | 19 | Individual card photos |
+| `real_photos/` | 18 | Phone camera photos from Visions project |
+| `foreign/` | 16 | Non-English cards (Japanese, German, French, etc.) |
+| `worn/` | 15 | Heavily played, damaged, worn cards |
+| `foil/` | 14 | Foil cards with holographic glare/reflections |
+| `low_light/` | 14 | Poor lighting, glare, shadows, amateur photos |
+| `tokens/` | 13 | Tokens and planeswalker emblems |
+| `hands/` | 11 | Cards held in hand (partial visibility) |
+| `ocr_test/` | 10 | Images optimized for OCR testing |
+| `reference/` | 9 | High-quality reference scans |
+| `multiple_cards/` | 6 | Multiple cards in frame |
+| `augmented/` | 4 | Augmented training examples |
+| `training_examples/` | 3 | ML training set samples |
+| `angled/` | 2 | Perspective distortion |
+
+## Image Sources
+
+Images from open-source MIT-licensed projects:
+
+- [hj3yoo/mtg_card_detector](https://github.com/hj3yoo/mtg_card_detector)
+- [tmikonen/magic_card_detector](https://github.com/tmikonen/magic_card_detector)
+- [fortierq/mtgscan](https://github.com/fortierq/mtgscan)
+- [LauriHursti/visions](https://github.com/LauriHursti/visions)
+- [KLuml/CardScanner](https://github.com/KLuml/CardScanner)
+- [dills122/MTG-Card-Analyzer](https://github.com/dills122/MTG-Card-Analyzer)
+- [ryanlin/Turtle](https://github.com/ryanlin/Turtle)
+
+Additional images from:
+- Reddit r/magicTCG (user-submitted photos)
+- Flickr (Creative Commons)
+- Card Kingdom / Face to Face Games grading guides
+- Scryfall (foreign language card scans)
+
+## Usage
+
+```csharp
+[Theory]
+[InlineData("varying_quality/test1.jpg")]
+[InlineData("angled/tilted_card_1.jpg")]
+[InlineData("hands/hand_of_card_1.png")]
+[InlineData("foil/rainbow_foil_secret_lair.jpg")]
+[InlineData("worn/hp_shuffle_crease.webp")]
+[InlineData("foreign/japanese_aang.jpg")]
+public async Task RecognizeCard_VaryingConditions(string imagePath)
+{
+    using var stream = File.OpenRead(Path.Combine("TestImages", imagePath));
+    var result = await _recognitionService.RecognizeCardAsync(stream);
+    
+    Assert.True(result.Success);
+    Assert.NotNull(result.Card);
+    Assert.True(result.Confidence >= 0.7f);
+}
+```
+
+## Category Details
+
+### foil/
+Foil cards showing holographic effects that challenge recognition:
+- Rainbow foils with color-shifting (`rainbow_foil_secret_lair.jpg`)
+- Surge foils with holo stickers (`surge_foils_holo.jpeg`)
+- Old-style foils (`old_foil_yawgmoth.jpg`)
+- Textured/dragonscale foils (`dragonscale_foil.jpg`)
+- Foil curling examples showing warping
+
+### worn/
+Heavily played and damaged cards:
+- Edge whitening (`edge_white.png`, `very_good_*.jpg`)
+- Scratches and scuffs (`scratch.png`, `hp_scratches.png`)
+- Creases and bends (`hp_shuffle_crease.webp`, `bent_creased.jpg`)
+- Binder damage (`hp_binder_bite_*.webp`)
+- Water damage (`hp_water_warping.png`)
+- Corner damage (`hp_compromised_corner.webp`)
+
+### low_light/
+Poor lighting and amateur photography conditions:
+- Glare from toploaders/sleeves (`glare_toploader.png`)
+- Direct light causing hotspots (`glare_straight_down.jpg`)
+- Depth of field blur (`dof_blur_amateur.jpg`)
+- Amateur condition photos with shadows
+- Flickr collection shots with mixed lighting
+
+### foreign/
+Non-English cards (8 languages):
+- Japanese (日本語)
+- German (Deutsch)
+- French (Français)
+- Italian (Italiano)
+- Spanish (Español)
+- Russian (Русский)
+- Simplified Chinese (简体中文)
+- Korean (한국어)
+
+### tokens/
+Tokens and planeswalker emblems:
+- Official WotC tokens
+- Custom/altered tokens
+- Planeswalker emblems (Elspeth, Gideon, Narset)
+- Token collections and gameplay shots
+
+### varying_quality/
+Images with various real-world challenges:
+- Different camera exposures
+- BGS graded cases (`counterspell_bgs.jpg`)
+- Cards in plastic sleeves (`card_in_plastic_case.jpg`)
+- Various lighting conditions
+- 28 numbered test images (`test1.jpg` - `test27.jpg`)
+
+### reference_alpha/
+47 Limited Edition Alpha cards for old-frame recognition:
+- Power Nine (Black Lotus, Ancestral Recall, Moxen, etc.)
+- Dual lands (Underground Sea, Volcanic Island, etc.)
+- Classic staples (Lightning Bolt, Counterspell, Sol Ring)
+
+### hands/
+Cards held in hand - partial visibility, stacked:
+- Various deck archetypes (Tron, Green, Red)
+- New and old frame cards
+- Different lighting conditions
+
+### real_photos/
+Phone camera photos from Visions project:
+- Real-world scanning conditions
+- Various resolutions and crops
+- Includes processed result images
+
+### ocr_test/
+From CardScanner project, graded by difficulty:
+- `card0-4.jpg`: Easier recognition
+- `card10-13.jpg`: Harder recognition (noted ~less accuracy)
+
+## TODO: Additional Categories Needed
+
+- [ ] **double_faced/** - Transform/MDFC cards (both sides)
+- [ ] **art_cards/** - Art series cards without text boxes
+- [ ] **promos/** - Extended art, borderless, showcase frames
+- [ ] **very_low_light/** - Near-dark conditions
+- [ ] **motion_blur/** - Cards in motion during scanning
+
+## License
+
+Card artwork is property of Wizards of the Coast. Images used for testing/research purposes only.