chore(docs): document ScoreExtractor tiling and refactor debug scripts (#563)

scripts/debug/debug_overlap.py

@@ -0,0 +1,98 @@
+import cv2
+import numpy as np
+import sys
+import glob
+
+# Test matching between two chunks to see what the score was!
+# Wait, the chunks are the output of the slicing!
+# The tracker works on the original FRAMES!
+# Let's test the tracker on the original frames!
+# I will supply the exact logic used in the tracker.
+
+def test_tracker():
+    video_file = r"C:\Users\Certes\Desktop\guitar_score\output\サカナクション／新宝島(エレキギターTAB) 難易度★★★ sakanaction shintakarajima.mp4"
+    cap = cv2.VideoCapture(video_file)
+    
+    panorama = None
+    last_clean_frame = None
+    in_transition = False
+    last_conf = 1.0
+    
+    count = 0
+    saved_matches = []
+    
+    while True:
+        ret, frame = cap.read()
+        if not ret: break
+        
+        count += 1
+        if count % 15 != 0: # fps=2
+            continue
+            
+        frame = cv2.resize(frame, (1280, 720))
+        
+        if panorama is None:
+            panorama = frame.copy()
+            last_clean_frame = frame.copy()
+            continue
+            
+        # calculate shift
+        prev_chan = last_clean_frame[:, :, 0]
+        curr_chan = frame[:, :, 0]
+        w = 1280
+        template_w = int(w * 0.3)
+        start_x = int(w * 0.6)
+        template = prev_chan[:, start_x:start_x + template_w]
+        
+        res = cv2.matchTemplate(curr_chan, template, cv2.TM_CCOEFF_NORMED)
+        _, conf, _, max_loc = cv2.minMaxLoc(res)
+        dx = start_x - max_loc[0]
+        if conf < 0.15 or dx <= 0:
+            dx = 0
+        if dx > w * 0.15:
+            dx = 0
+            
+        if (conf < 0.45) or (last_conf - conf > 0.3):
+            in_transition = True
+        elif in_transition and conf > 0.85 and dx == 0:
+            in_transition = False
+            
+            # overlap logic
+            h = panorama.shape[0]
+            new_page = frame.copy()
+            search_w = min(1500, panorama.shape[1])
+            search_region = panorama[:, -search_w:, 0]
+            
+            head_w = min(400, new_page.shape[1])
+            head = new_page[:, 50:50+head_w, 0]
+            
+            res2 = cv2.matchTemplate(search_region, head, cv2.TM_CCOEFF_NORMED)
+            _, max_val, _, matched_loc = cv2.minMaxLoc(res2)
+            
+            saved_matches.append(max_val)
+            print(f"Page turn detected! Overlap match score: {max_val:.4f} at {matched_loc}")
+            
+            if max_val > 0.65:
+                overlap_px = search_w - matched_loc[0] + 50
+                if overlap_px < new_page.shape[1] - 50:
+                    panorama = np.hstack([panorama, new_page[:, overlap_px:]])
+                else:
+                    pass
+            else:
+                panorama = np.hstack([panorama, new_page])
+                
+        elif dx > 0 and dx < w and not in_transition:
+            new_strip = frame[:, w - dx:, :]
+            panorama = np.hstack([panorama, new_strip])
+
+        last_conf = conf
+        last_clean_frame = frame.copy()
+        
+        if len(saved_matches) >= 3:
+            break
+            
+    cap.release()
+    print("Test complete.")
+
+if __name__ == "__main__":
+    test_tracker()