Improve prefetch caching

Author: kenwer

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## [Unreleased]
 ### Changed
-- Detectorist now prefetches adjacent images in both directions, so stepping forward or backward feels faster.
+- Detectorist prefetches and processes the next 3 images in the current direction. Cached images & detections are displayed almost instantly so the app feels snappier.
 - The "Loading image..." placeholder only appears when loading actually takes noticeable time.
 - Batch runs load the next image in the background while the current one is processed, cutting batch time (up to 2x for HIF files).
 - A batch run no longer aborts when one image fails to load. The image is skipped and recorded as "load-error" in detections.csv.

src/detectorist/detectorist_app.py

@@ -51,6 +51,7 @@ def __init__(self):
         super().__init__()
 
         self.current_image_path = None
+        self._previous_row: int | None = None
         self._all_detection_results: list = []
         self._last_detection_time_ms: float = 0.0
 
@@ -269,6 +270,7 @@ def _load_images_from_paths(self, file_paths: list[str]):
         # Clear existing list and main image
         self.model.clear()
         self.current_image_path = None
+        self._previous_row = None
         self.ui.image_label.clear()
         # Files on disk may have changed, so cached decodes are not trustworthy.
         # The queued invocation runs clear_cache on the worker thread, which is
@@ -423,6 +425,11 @@ def on_image_selected(self, index):
         if new_image_path == self.current_image_path:
             return  # No need to reload the same image
 
+        try:
+            self._previous_row = self.model.imagePaths().index(self.current_image_path)
+        except ValueError:
+            self._previous_row = None
+
         self.current_image_path = new_image_path
         self._all_detection_results = []
 
@@ -466,21 +473,32 @@ def trigger_processing(self):
 
     def _prefetch_hints(self) -> list[str]:
         """
-        Returns the paths worth decoding ahead of time: one step forward and
-        one step backward. During forward browsing the previous image is
-        already cached (no-op), so the cost is one extra decode. During
-        backward browsing the backward hint populates the slot that would
-        otherwise miss two steps back.
+        Returns paths to decode ahead of time. In both directions: protect the
+        from-image (so it survives the upcoming evictions) then prefetch 3 in the
+        direction of travel, giving 3 instant steps ahead and 1 instant step back.
+        Falls back to 2 ahead and 2 behind (n+1, n-1, n+2, n-2) for the first
+        selection or a jump.
         """
         paths = self.model.imagePaths()
         try:
             row = paths.index(self.current_image_path)
         except ValueError:
             return []
-        hints = paths[row + 1:row + 2]
-        if row > 0:
-            hints = hints + [paths[row - 1]]
-        return hints
+
+        prev_row = self._previous_row
+        if prev_row is not None and abs(row - prev_row) == 1:
+            if row > prev_row:
+                # Promote the from-image first so it survives the forward loads.
+                return [paths[prev_row]] + paths[row + 1:row + 4]
+            else:
+                # Same pattern as forward: protect the from-image first, then
+                # prefetch 3 in the direction of travel.
+                return [paths[prev_row]] + list(reversed(paths[max(0, row - 3):row]))
+
+        # No clear direction: nearest 2 in each direction, alternating so the
+        # closest neighbors are always decoded first.
+        return [paths[i] for i in [row + 1, row - 1, row + 2, row - 2]
+                if 0 <= i < len(paths)]
 
     def handle_model_loaded(self, success: bool, message: str, class_names: list):
         """Handles the result of loading a model in the worker."""

src/detectorist/image_cache.py

@@ -25,13 +25,13 @@ class ImageCache:
     the image file and the loaded model, so entries stay valid until the
     model changes or the files on disk may have (callers clear it then).
 
-    The default capacity of 3 keeps two previously viewed images plus the
-    prefetched next image resident, so both a forward and a backward step
-    land in the cache. Each decoded 33 MP 16-bit image occupies roughly
-    200 MB, which is why the capacity is this small.
+    The default capacity of 5 keeps 3 images ahead in the travel direction and
+    1 image behind alongside the current image, so three consecutive steps in
+    the browsing direction are served without decoding. Each decoded 33 MP
+    16-bit image occupies roughly 200 MB, so the capacity is kept small.
     """
 
-    def __init__(self, max_entries: int = 3):
+    def __init__(self, max_entries: int = 5):
         self._max_entries = max_entries
         # dicts preserve insertion order; the first key is the least recently used
         self._entries: dict[str, CacheEntry] = {}