*** BEST VIEWED WITH CURIOSITY ENABLED ***
Build plan
Implementation specifics
Concrete engineering requirements for turning card photos into measured centering ratios, overlays, grader eligibility, and product-ready reports.
Worker stack
Python + CV
OpenCV first; segmentation model when needed.
Artifact store
images + JSON
Original, normalized crop, overlay, measurements.
Operator path
manual handles
Needed for low-confidence boundaries.
API contract
/analyze
Async job with status/result endpoints.
Concrete implementation components
What has to be built, beyond the user-facing page.
Image intake endpointAccept front and optional back image, enforce size/type limits, strip metadata, assign analysis id, and enqueue processing.
Quality preflightCompute blur, glare, crop, resolution, corner visibility, background contrast, and sleeve/slab indicators.
Card boundary detectorFind outer quadrilateral, refine corners, reject cropped/uncertain images, and calculate a transform matrix.
Perspective normalizerRectify to canonical card aspect ratio. Store normalized image for repeatable measurement and debugging.
Layout classifierPick measurement strategy for vintage, modern bordered, full art, trainer, Japanese, reverse, and card back layouts.
Inner-boundary detectorDetect artwork/print window or relevant border landmarks. Provide manual override coordinates when confidence is low.
Rules comparison engineCompare ratios to versioned grader profiles with uncertainty-aware pass/borderline/fail states.
Report rendererGenerate JSON result, concise PulseLine text, detailed TCGMarketPulse panel, and annotated overlay.
Minimum repository additions
Suggested folder structure.
tcg-centering/
worker/
analyze.py
quality.py
detect_card.py
rectify.py
classify_layout.py
measure.py
render_overlay.py
rules/
psa.json
cgc.json
bgs.json
sjc-placeholder.json
api/
routes.ts or routes.py
migrations/
centering_analysis.sql
eval/
golden_set_manifest.json
run_eval.pyDatabase tables to add
Enough structure for auditability and later model improvement.
| Table | Purpose | Key fields |
|---|---|---|
| centering_analysis | One user-facing analysis job | id, user_id, card_id, status, created_at, completed_at, model_version, rules_version |
| centering_image | Front/back image artifacts | analysis_id, side, original_uri, normalized_uri, overlay_uri, width, height, sha256 |
| centering_quality | Photo preflight results | blur_score, glare_score, crop_status, corner_visibility, warnings_json |
| centering_measurement | Measured ratios and boundaries | side, left_px, right_px, top_px, bottom_px, lr_ratio, tb_ratio, uncertainty_pct, confidence |
| grader_rule_profile | Versioned centering thresholds | grader, grade_label, front_rule_json, back_rule_json, source_note, effective_date |
| centering_feedback | Human correction and returned-grade loop | analysis_id, corrected_boundaries_json, returned_grader, returned_grade, notes |