Add asset naming and device folder utilities to ScanPaths

Introduces minimal primitives for asset filename construction, device folder listing, and extension inference in the ScanPaths class. These additions support canonical asset naming, device subfolder discovery, and automatic selection of file extensions based on existing files.

Author: skbarber

GEECS-Data-Utils/geecs_data_utils/scan_paths.py

@@ -26,6 +26,9 @@
 from geecs_data_utils.type_defs import ScanTag
 from geecs_data_utils.geecs_paths_config import GeecsPathsConfig
 
+# Acceptable extensions (lowercase, no dot)
+_ACCEPTABLE_EXTS = {"png", "tif", "tiff", "h5", "dat", "tdms", "jpg", "jpeg", "bmp"}
+
 # from geecs_data_utils.types import ScanConfig, ScanMode
 
 # module‐level logger
@@ -709,6 +712,69 @@ def get_common_shot_dataframe(
 
         return pd.DataFrame(rows)
 
+    # ---- Minimal naming + discovery primitives (no shot loops) -------------------
+
+    @staticmethod
+    def _shot_str(shot: int) -> str:
+        """Zero-pad to at least 3 digits; expand naturally beyond 999."""
+        return f"{shot:03d}" if shot < 1000 else str(shot)
+
+    def list_device_folders(self) -> list[str]:
+        """Return device subfolder names from this scan folder."""
+        try:
+            return self.get_folders_and_files().get("devices", [])
+        except Exception:
+            root = self.get_folder()
+            return (
+                [p.name for p in root.iterdir() if p.is_dir()]
+                if root and root.exists()
+                else []
+            )
+
+    def device_folder(self, device: str) -> Path:
+        """Resolve '<scan>/<device>'."""
+        return self.get_folder() / device
+
+    @staticmethod
+    def build_asset_filename(
+        *, scan: int, shot: int, device: str, ext: str, variant: Optional[str] = None
+    ) -> str:
+        """Build canonical expected file naming."""
+        ext = ext.lstrip(".").lower()
+        shot_str = ScanPaths._shot_str(shot)
+        variant_seg = "" if not variant else f"{variant}"
+        return f"Scan{scan:03d}_{device}_{shot_str}{variant_seg}.{ext}"
+
+    def build_asset_path(
+        self, *, shot: int, device: str, ext: str, variant: Optional[str] = None
+    ) -> Path:
+        """Full expected path for one asset."""
+        tag = self.get_tag()
+        fname = self.build_asset_filename(
+            scan=tag.number, shot=shot, device=device, ext=ext, variant=variant
+        )
+        return self.device_folder(device) / fname
+
+    def infer_device_ext(self, device: str, *, max_files: int = 5) -> str:
+        """Peek at up to `max_files` files to find proper file extension."""
+        from collections import Counter
+
+        dpath = self.device_folder(device)
+        if not dpath.exists():
+            return "png"
+
+        counts = Counter()
+        seen = 0
+        for f in dpath.iterdir():
+            if f.is_file():
+                ext = f.suffix.lower().lstrip(".")
+                if ext in _ACCEPTABLE_EXTS:
+                    counts[ext] += 1
+                    seen += 1
+                    if seen >= max_files:
+                        break
+        return counts.most_common(1)[0][0] if counts else "png"
+
 
 ScanPaths.reload_paths_config()