CardGrader

CardGrader is a native SwiftUI iOS app for measuring trading card centering from a photo. It is built around a simple collector workflow: import or capture a card image, adjust interactive border guides, review front/back centering ratios, and save snapshots for later comparison.

The project includes:

• A native SwiftUI iOS app.
• Camera and photo-library import for card images.
• A camera alignment guide that helps users frame the card square-on.
• OpenCV-backed automatic detection of the outer card edge and inner border.
• One-tap straighten that perspective-corrects a tilted card before measuring.
• Interactive outer and inner border guides for centering measurement.
• Local saved snapshots with front/back images, overlays, metrics, and history.

Features

• Import card photos from the camera or photo library.
• See a trading-card-shaped alignment frame and roll-level indicator while shooting, encouraging straight, square-on photos.
• Auto-detect the outer card edge and inner border with an OpenCV contour/edge pipeline, falling back to a Vision heuristic when no confident card rectangle is found.
• Straighten tilted or angled photos with a one-tap perspective correction ("Fit & Straighten") that preserves true card proportions, then re-runs guide detection.
• Measure left/right and top/bottom centering with draggable guide overlays.
• Review collector-friendly centering ratios such as 55/45 or 69/31.
• See verdict-style summaries for gem candidate, good, and off-center results.
• Save front-only or front/back card snapshots locally.
• Browse saved snapshots with sorting for newest, best centered, or needs review.
• View saved card details with the original image and centering report.
• Share an exported snapshot report image from saved card details.
• Delete saved snapshots with confirmation.
• Use light and dark mode with a shared visual design system.
• Run core centering, overlay, and detector logic through Swift unit tests.

App

iOS

The iOS app is built with SwiftUI and uses UIKit bridges where needed for camera capture and image rendering.

Core areas:

• cardv1/Models contains card side, overlay, centering, and saved snapshot models.
• cardv1/Views contains the editor, inspection canvas, centering report, snapshot list/detail views, camera bridge with alignment overlay, and design tokens.
• cardv1/CardVision contains the OpenCV detection bridge (CardDetectorBridge) for card-edge detection and perspective straightening, exposed to Swift through an Objective-C++ layer and bridging header.
• cardv1/Stores contains local file-based snapshot persistence.
• cardv1/Ads contains a disabled no-op ad wrapper until production privacy and consent setup is complete.
• cardv1Tests contains model, centering, snapshot persistence, and detector tests.

Card Detection

CardGrader uses OpenCV (via the opencv-spm Swift package) for image analysis:

• Auto-detect borders finds the outer card edge and the inside edge of the colored border. It handles both full-bleed scans (card fills the frame) and cards photographed on a background, and falls back to an Apple Vision heuristic when OpenCV can't find a confident card rectangle.
• Fit & Straighten detects the card's quadrilateral and applies a perspective warp so a tilted or angled card becomes upright and cropped to its edges. Card proportions are preserved so the centering measurement stays accurate. Full-bleed images that are already square-on are left untouched.

The OpenCV dependency is pinned in cardv1.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved.

Measurement Model

CardGrader measures centering from user-adjusted guides. The outer guide marks the card edge and the inner guide marks the artwork or border boundary. From those guides, the app computes border percentages, centering ratios, and a plain-language explanation.

This app is intended as a collector aid, not an official grading result. Final grades can depend on many factors beyond centering, including corners, edges, surface, print quality, and grader standards.

Requirements

• Xcode 26 or newer.
• iOS 17 or newer.
• iOS simulator or device target supported by the project.

Development

Open the project in Xcode:

open cardv1.xcodeproj

Run tests from the command line:

xcodebuild -project cardv1.xcodeproj -scheme cardv1 -destination 'platform=iOS Simulator,name=iPhone 17' test

Notes

• Saved snapshots are stored locally on device using JSON metadata and compressed JPEG images.
• The back side of a card is optional, so users can save front-only cards.
• Imported photos keep their original framing; the app normalizes orientation but does not silently crop to a card ratio.
• Ads are disabled in the current build until production ad IDs, App Store privacy details, and consent requirements are configured.
• Generated screenshots and local build artifacts are intentionally ignored by Git.