First commit

design doc.md

@@ -0,0 +1,69 @@
+# Spinda Coordinate Regression & Global Registry (SCRGR)
+
+**Date Created:** 2026-05-07 10:49:15
+
+**Tags:** #MachineLearning #ComputerVision #Python #Pokemon #Spinda #Regression
+
+## The Problem
+
+There are $2^{32}$ (over 4.2 billion) Spinda variations, but identifying a specific pattern from a user-submitted photo or screenshot is currently a manual, error-prone process. Because a 32-bit PID determines the exact coordinates of four facial spots on a discrete $16 \times 16$ grid, a system is needed to automatically extract these coordinates and map them to their corresponding game data without requiring a massive, unsearchable database of raw images.
+
+## Context
+
+Spinda's visual appearance is deterministic. The PID is split into four bytes, each providing the $(x, y)$ coordinates for one of the four spots.
+
+- **Current State:** Existing tools can generate a pattern from a PID, but the inverse (Pattern → PID) is difficult due to "visual collisions" (multiple PIDs resulting in identical spot placements) and the noise inherent in real-world photography (glare, blur, and distortion).
+    
+- **Technical Shift:** While initial discussions considered abstract image fingerprinting, the realization that the "identity" of a Spinda is mathematically defined by 8 discrete integers ($4 \text{ spots} \times 2 \text{ coordinates}$) allows for a more precise Regression-based approach.
+    
+
+## Design
+
+### Summary
+
+The proposed solution uses a **Coordinate Regression Model** to translate pixels into a 8-dimension vector of spatial coordinates. This vector is rounded to the nearest integers to match the game's internal $16 \times 16$ grid, providing a "Visual Fingerprint" that can be instantly looked up in a $O(1)$ hash map to identify associated PIDs.
+
+### Detailed Design
+
+#### 1. Synthetic Data Generation & Augmentation
+
+To facilitate a "smooth" training experience in Python, we will build a generator using libraries like `OpenCV` or `PIL`:
+
+- **Perfect Sprites:** Generate 2D Spinda faces with known ground-truth coordinates.
+    
+- **Augmentation Pipeline:** Apply "Domain Randomization" to simulate real-world conditions:
+    
+    - **Spatial Transforms:** Slight rotations and tilts to mimic handheld photography.
+        
+    - **Sensor Noise:** Add Gaussian noise and Moiré patterns to simulate digital camera sensors.
+        
+    - **Grid Jitter:** Ensure the model learns the center-of-mass for a spot even if it is partially obscured.
+        
+
+#### 2. ML Architecture: Coordinate Regression
+
+Instead of a classification model, we will implement a **Regression CNN** (e.g., a modified ResNet or MobileNet backbone):
+
+- **Input:** A standardized $128 \times 128$ crop of the Spinda face.
+    
+- **Output Layer:** A dense layer with 8 neurons using a linear activation function, representing $[\hat{x}_1, \hat{y}_1, \hat{x}_2, \hat{y}_2, \hat{x}_3, \hat{y}_3, \hat{x}_4, \hat{y}_4]$.
+    
+- **Loss Function:** Mean Squared Error (MSE) to minimize the distance between predicted and actual grid coordinates.
+    
+
+#### 3. Deterministic "Snap-to-Grid" Matching
+
+Post-inference, the model's float outputs are processed to ensure mathematical accuracy:
+
+- **Rounding:** Outputs are rounded to the nearest integer within the $[0, 15]$ range.
+    
+- **Hashing:** The 8 integers are concatenated into a unique string key (e.g., `"12-04-08-09-02-01-15-14"`).
+    
+- **Collision Handling:** The database maps this key to a list of all PIDs that produce that visual output, accounting for the BDSP "Endian flip" and other internal overlaps.
+    
+
+#### 4. The Global Registry & Audit Trail
+
+- **Automated Documentation:** Successfully matched Spindas are added to a community database.
+    
+- **Manual Review System:** For entries with low model confidence (e.g., if the floats were far from an integer before rounding), the system logs the original image for administrator "Approve/Reject" review to maintain data integrity.