pivtools 0.1.3__cp311-cp311-win_amd64.whl

pivtools_core/image_handling/readers/lavision_reader.py

@@ -0,0 +1,190 @@
+import os
+from typing import Optional
+from loguru import logger
+import numpy as np
+
+from . import register_reader
+
+
+def read_lavision_im7(
+    file_path: str, camera_no: int = 1, frames: int = 2
+) -> np.ndarray:
+    """Read LaVision .im7 files.
+    
+    LaVision .im7 files store all cameras in a single file per time instance.
+    Each file contains frame pairs (A and B) for all cameras.
+    
+    Structure: For N cameras, the file contains 2*N frames in sequence:
+    - Frames 0,1: Camera 1, frames A and B
+    - Frames 2,3: Camera 2, frames A and B
+    - etc.
+    
+    Args:
+        file_path: Path to the .im7 file
+        camera_no: Camera number (1-based indexing)
+        frames: Number of frames to read (typically 2 for PIV)
+        
+    Returns:
+        np.ndarray: Array of shape (frames, H, W) containing the image data
+    """
+    import sys
+    if sys.platform == "darwin":
+        raise ImportError(
+            "lvpyio is not shipped or supported on macOS (darwin). Please use a supported platform for LaVision .im7 reading."
+        )
+    try:
+        import lvpyio as lv
+    except ImportError:
+        raise ImportError(
+            "LaVision library not available. Please install."
+        )
+
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"Image file not found: {file_path}")
+    
+    # Read the buffer as a generator
+    buffer = lv.read_buffer(file_path)
+    
+    # Calculate which frames we need for this camera
+    start_frame = (camera_no - 1) * 2
+    end_frame = start_frame + frames
+    
+    # Iterate through the generator, only processing the frames we need
+    data = None
+    for idx, img in enumerate(buffer):
+        if idx < start_frame:
+            # Skip frames before our camera
+            continue
+        elif idx < end_frame:
+            # This is one of our frames
+            if data is None:
+                # Initialize array on first needed frame
+                height, width = img.components["PIXEL"].planes[0].shape
+                data = np.zeros((frames, height, width), dtype=np.float64)
+            
+            i_scale = img.scales.i.slope
+            i_offset = img.scales.i.offset
+            u_arr = img.components["PIXEL"].planes[0] * i_scale + i_offset
+            data[idx - start_frame, :, :] = u_arr
+        else:
+            # We've got all our frames, stop iterating
+            break
+    
+    if data is None:
+        raise ValueError(f"Camera {camera_no} not found in file {file_path}")
+    
+    return data.astype(np.float32)
+
+
+def read_lavision_pair(file_path: str, camera_no: int = 1) -> np.ndarray:
+    """Read LaVision .im7 file and return as frame pair.
+    
+    Args:
+        file_path: Path to the .im7 file (contains all cameras for one time instance)
+        camera_no: Camera number (1-based) to extract from the file
+        
+    Returns:
+        np.ndarray: Array of shape (2, H, W) containing frame A and B for the specified camera
+    """
+    return read_lavision_im7(file_path, camera_no, frames=2)
+
+
+def read_lavision_ims(file_path: str, camera_no: Optional[int] = None, im_no: Optional[int] = None) -> np.ndarray:
+    """Read LaVision images from a .set file.
+    
+    LaVision .set files contain all cameras and frames in a single container.
+    This function reads the set file and extracts the appropriate frames for the
+    specified camera and image number.
+    
+    Args:
+        file_path: Path to the .set file
+        camera_no: Camera number (1-based). If None, extracted from file_path (legacy)
+        im_no: Image number (1-based). If None, extracted from file_path (legacy)
+        
+    Returns:
+        np.ndarray: Array of shape (2, H, W) containing frame A and B
+    """
+    import sys
+    from pathlib import Path
+    
+    if sys.platform == "darwin":
+        raise ImportError(
+            "LaVision libraries are not supported on macOS (darwin). Please use a supported platform."
+        )
+    
+    try:
+        import lvpyio as lv
+    except ImportError:
+        raise ImportError(
+            "LaVision library not available. Please install lvpyio."
+        )
+    
+    path = Path(file_path)
+    
+    # For .set files, camera_no and im_no must be provided
+    if path.suffix.lower() == '.set' or (camera_no is not None and im_no is not None):
+        # Modern format: file_path is the .set file
+        set_file_path = file_path
+        if camera_no is None or im_no is None:
+            raise ValueError("camera_no and im_no must be provided for .set files")
+    else:
+        # Legacy path parsing for backward compatibility
+        # Extract camera number from path (e.g., "Cam1" -> 1)
+        if camera_no is None:
+            camera_match = None
+            for part in path.parts:
+                if part.startswith("Cam") and part[3:].isdigit():
+                    camera_match = int(part[3:])
+                    break
+            if camera_match is None:
+                raise ValueError(f"Could not extract camera number from path: {file_path}")
+            camera_no = camera_match
+        
+        # Extract image number from filename
+        if im_no is None:
+            stem = path.stem
+            if stem.isdigit():
+                im_no = int(stem)
+            else:
+                raise ValueError(f"Could not extract image number from filename: {path.name}")
+        
+        # Source directory is typically the parent of the CamX directory
+        source_dir = path.parent.parent
+        set_file_path = str(source_dir)
+    
+    if not Path(set_file_path).exists():
+        raise FileNotFoundError(f"Set file path not found: {set_file_path}")
+    
+    # Read the set file
+    try:
+        set_file = lv.read_set(set_file_path)
+        im = set_file[im_no - 1]  # 0-based indexing in Python
+    except Exception as e:
+        raise RuntimeError(f"Failed to read set file from {set_file_path}: {e}")
+    
+    # Extract frames for this camera
+    data = np.zeros((2, *im.frames[0].components["PIXEL"].planes[0].shape), dtype=np.float64)
+    
+    for j in range(2):
+        # Frame indexing: 2*cameraNo-(2-j)
+        frame_idx = 2 * camera_no - (2 - j)
+        frame = im.frames[frame_idx]
+        
+        # Apply scaling
+        i_scale = frame.scales.i.slope
+        i_offset = frame.scales.i.offset
+        u_arr = frame.components["PIXEL"].planes[0] * i_scale + i_offset
+        
+        data[j, :, :] = u_arr
+    
+    set_file.close()
+    return data.astype(np.float32)
+
+
+def read_lavision_ims_pair(file_path: str, **kwargs) -> np.ndarray:
+    """Read LaVision .set file and return as frame pair."""
+    return read_lavision_ims(file_path, **kwargs)
+
+
+register_reader([".im7"], read_lavision_pair)
+register_reader([".set"], read_lavision_ims_pair)

pivtools_core/image_handling/readers/registry.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+from typing import Callable, Dict, List
+
+# Registry for image readers
+_reader_registry: Dict[str, Callable] = {}
+
+
+def register_reader(extensions: List[str], reader_func: Callable):
+    """Register an image reader for specific file extensions."""
+    for ext in extensions:
+        _reader_registry[ext.lower()] = reader_func
+
+
+def get_reader(file_path: str) -> Callable:
+    """Get appropriate reader for a file based on its extension."""
+    ext = Path(file_path).suffix.lower()
+    if ext not in _reader_registry:
+        raise ValueError(f"No reader registered for file type: {ext}")
+    return _reader_registry[ext]
+
+
+def list_supported_formats() -> List[str]:
+    """List all supported file formats."""
+    return list(_reader_registry.keys())

pivtools_core/paths.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+
+def get_data_paths(
+    base_dir,
+    num_images,
+    cam,
+    type_name,
+    endpoint="",
+    use_merged=False,
+    use_uncalibrated=False,
+    calibration=False,  # New argument
+):
+    """
+    Construct directories for data, statistics, and videos.
+    endpoint: optional subfolder ('' ignored).
+    use_uncalibrated: if True, return paths for uncalibrated data
+    calibration: if True, return calibration directory
+    """
+    base_dir = Path(base_dir)
+    cam = f"Cam{cam}"
+    # Calibration data
+    if calibration:
+        calib_dir = base_dir / "calibration" / cam
+        if endpoint:
+            calib_dir = calib_dir / endpoint
+        return dict(calib_dir=calib_dir)
+    # Uncalibrated data
+    if use_uncalibrated:
+        data_dir = base_dir / "uncalibrated_piv" / str(num_images) / cam / type_name
+        stats_dir = (
+            base_dir / "statistics" / "uncalibrated" / str(num_images) / cam / type_name
+        )
+        video_dir = base_dir / "videos" / "uncalibrated" / str(num_images) / cam
+    # Merged data
+    elif use_merged:
+        data_dir = base_dir / "merged" / str(num_images) / cam / type_name
+        stats_dir = base_dir / "statistics" / "merged" / cam / type_name
+        video_dir = base_dir / "videos" / "merged" / cam / type_name
+    # Regular calibrated data
+    else:
+        data_dir = base_dir / "calibrated_piv" / str(num_images) / cam / type_name
+        stats_dir = base_dir / "statistics" / str(num_images) / cam / type_name
+        video_dir = base_dir / "videos" / str(num_images) / cam
+    if endpoint:
+        data_dir = data_dir / endpoint
+        stats_dir = stats_dir / endpoint
+        video_dir = video_dir / endpoint
+    return dict(data_dir=data_dir, stats_dir=stats_dir, video_dir=video_dir)

pivtools_core/vector_loading.py

@@ -0,0 +1,248 @@
+import warnings
+from pathlib import Path
+from typing import Optional, Sequence, Tuple
+
+import dask
+import dask.array as da
+import numpy as np
+import scipy.io
+
+from .config import Config
+
+
+def read_mat_contents(
+    file_path: str, run_index: Optional[int] = None, return_all_runs: bool = False
+) -> np.ndarray:
+    """
+    Reads piv_result from a .mat file.
+    If multiple runs are present, selects the specified run_index (0-based).
+    If run_index is None, selects the first run with valid (non-empty) data.
+    If return_all_runs is True, returns all runs in shape (R, 3, H, W).
+    Otherwise returns shape (1, 3, H, W) for the selected run.
+    """
+    mat = scipy.io.loadmat(file_path, struct_as_record=False, squeeze_me=True)
+    piv_result = mat["piv_result"]
+
+    # Multiple runs case: numpy array of structs
+    if isinstance(piv_result, np.ndarray) and piv_result.dtype == object:
+        total_runs = piv_result.size
+
+        if return_all_runs:
+            # Return all runs
+            all_runs = []
+            for idx in range(total_runs):
+                pr = piv_result[idx]
+                ux = np.asarray(pr.ux)
+                uy = np.asarray(pr.uy)
+                b_mask = (
+                    np.asarray(pr.b_mask).astype(ux.dtype, copy=False)
+                    if ux.size > 0
+                    else np.array([])
+                )
+                if ux.size > 0 and uy.size > 0:
+                    stacked = np.stack([ux, uy, b_mask], axis=0)  # (3, H, W)
+                else:
+                    # Empty run - create placeholder with consistent shape if possible
+                    stacked = np.array([[], [], []])  # Will be reshaped later
+                all_runs.append(stacked)
+            return np.array(all_runs)  # (R, 3, H, W)
+
+        # Single run selection (existing logic)
+        if run_index is None:
+            # Find first valid run (non-empty ux, uy)
+            for idx in range(total_runs):
+                pr = piv_result[idx]
+                ux = np.asarray(pr.ux)
+                uy = np.asarray(pr.uy)
+                if ux.size > 0 and uy.size > 0:
+                    run_index = idx
+                    break
+            else:
+                raise ValueError(f"No valid runs found in {file_path}")
+        if run_index < 0 or run_index >= total_runs:
+            raise ValueError(
+                f"Invalid run_index {run_index} for {file_path} (total_runs={total_runs})"
+            )
+        pr = piv_result[run_index]
+        ux = np.asarray(pr.ux)
+        uy = np.asarray(pr.uy)
+        b_mask = np.asarray(pr.b_mask).astype(ux.dtype, copy=False)
+        stacked = np.stack([ux, uy, b_mask], axis=0)[None, ...]  # (1, 3, H, W)
+        return stacked
+
+    # Single run struct
+    if run_index is not None and run_index != 0:
+        raise ValueError(
+            f"Invalid run_index {run_index} for single-run file {file_path}"
+        )
+    pr = piv_result
+    ux = np.asarray(pr.ux)
+    uy = np.asarray(pr.uy)
+    b_mask = np.asarray(pr.b_mask).astype(ux.dtype, copy=False)
+
+    if return_all_runs:
+        stacked = np.stack([ux, uy, b_mask], axis=0)[None, ...]  # (1, 3, H, W)
+        return stacked
+    else:
+        stacked = np.stack([ux, uy, b_mask], axis=0)[None, ...]  # (1, 3, H, W)
+        return stacked
+
+
+def load_vectors_from_directory(
+    data_dir: Path, config: Config, runs: Optional[Sequence[int]] = None
+) -> da.Array:
+    """
+    Load .mat vector files for requested runs.
+    - runs: list of 1-based run numbers to include; if None or empty, include all runs in the files.
+    Returns Dask array with shape (N_existing, R, 3, H, W).
+    """
+    data_dir = Path(data_dir)
+    fmt = config.vector_format  # e.g. "B%05d.mat"
+    expected_paths = [data_dir / (fmt % i) for i in range(1, config.num_images + 1)]
+    existing_paths = [p for p in expected_paths if p.exists()]
+
+    missing_count = len(expected_paths) - len(existing_paths)
+    if missing_count == len(expected_paths):
+        raise FileNotFoundError(
+            f"No vector files found using pattern {fmt} in {data_dir}"
+        )
+    if missing_count:
+        warnings.warn(
+            f"{missing_count} vector files missing in {data_dir} (loaded {len(existing_paths)})"
+        )
+
+    # Convert runs (1-based) to zero-based indices for reading
+    zero_based_runs: Optional[Sequence[int]] = None
+    if runs:
+        zero_based_runs = [r - 1 for r in runs]
+
+    # Detect shape/dtype from first readable file
+    first_arr = None
+    for p in existing_paths:
+        try:
+            first_arr = read_mat_contents(
+                str(p), run_index=zero_based_runs[0] if zero_based_runs else None
+            )
+            # Debugging: print shape, dtype, and file info
+            if first_arr.ndim != 4:
+                warnings.warn(
+                    f"[DEBUG] Unexpected array ndim={first_arr.ndim} in {p.name}"
+                )
+            break
+        except Exception as e:
+            warnings.warn(f"Failed to read {p.name} during probing: {e}")
+            raise
+    if first_arr is None:
+        raise FileNotFoundError(f"Could not read any valid vector files in {data_dir}")
+
+    shape, dtype = first_arr.shape, first_arr.dtype  # (R, 3, H, W), dtype
+
+    delayed_items = [
+        dask.delayed(read_mat_contents)(
+            str(p), run_index=zero_based_runs[0] if zero_based_runs else None
+        )
+        for p in existing_paths
+    ]
+    arrays = [da.from_delayed(di, shape=shape, dtype=dtype) for di in delayed_items]
+    stacked = da.stack(arrays, axis=0)  # (N, R, 3, H, W)
+    return stacked.rechunk({0: config.piv_chunk_size})
+
+
+def load_coords_from_directory(
+    data_dir: Path, runs: Optional[Sequence[int]] = None
+) -> Tuple[Sequence[np.ndarray], Sequence[np.ndarray]]:
+    """
+    Locate and read the coordinates.mat file in data_dir and return (x_list, y_list).
+    - runs: list of 1-based run numbers to include; if None or empty, include all runs present in the coords file.
+    - Returns:
+        x_list: list of x arrays in the same order as 'runs' (or all runs if None)
+        y_list: list of y arrays in the same order as 'runs' (or all runs if None)
+    """
+    data_dir = Path(data_dir)
+    coords_path = data_dir / "coordinates.mat"
+    if not coords_path.exists():
+        raise FileNotFoundError(f"No coordinates.mat file found in {data_dir}")
+
+    mat = scipy.io.loadmat(coords_path, struct_as_record=False, squeeze_me=True)
+    if "coordinates" not in mat:
+        raise KeyError(f"'coordinates' variable not found in {coords_path.name}")
+    coords = mat["coordinates"]
+
+    def _xy_from_struct(obj):
+        return np.asarray(obj.x), np.asarray(obj.y)
+
+    x_list, y_list = [], []
+
+    if isinstance(coords, np.ndarray) and coords.dtype == object:
+        if runs:
+            zero_based = [r - 1 for r in runs if 1 <= r <= coords.size]
+            if len(zero_based) != len(runs):
+                missing = sorted(set(runs) - set([z + 1 for z in zero_based]))
+                warnings.warn(
+                    f"Skipping out-of-range run indices {missing} for coordinates"
+                )
+        else:
+            zero_based = list(range(coords.size))
+
+        for idx in zero_based:
+            x, y = _xy_from_struct(coords[idx])
+            x_list.append(x)
+            y_list.append(y)
+    else:
+        if runs and 1 not in runs:
+            warnings.warn(
+                "Requested runs do not include run 1 present in coordinates; returning empty coords"
+            )
+            return [], []
+        x, y = _xy_from_struct(coords)
+        x_list.append(x)
+        y_list.append(y)
+
+    return x_list, y_list
+
+
+def save_mask_to_mat(file_path: str, mask: np.ndarray, polygons):
+    """
+    Save the given mask array to a .mat file.
+    """
+    scipy.io.savemat(file_path, {"mask": mask, "polygons": polygons}, do_compression=True)
+
+
+def read_mask_from_mat(file_path: str):
+    """
+    Read the mask and polygons from a .mat file.
+    Returns:
+        mask: np.ndarray
+        polygons: list of dicts with fields 'index', 'name', 'points'
+    """
+    # Load without squeeze_me to avoid 0-d array issues with single-element cells
+    # Use struct_as_record=True (default) so structs become record arrays with dict-like access
+    mat = scipy.io.loadmat(file_path, squeeze_me=False, struct_as_record=True)
+    mask = mat.get("mask", None)
+    polygons_raw = mat.get("polygons", None)
+    if mask is None or polygons_raw is None:
+        raise ValueError(f"Missing 'mask' or 'polygons' in {file_path}")
+
+    # Squeeze the mask manually if needed
+    mask = np.squeeze(mask)
+    
+    # polygons_raw is a numpy object array (MATLAB cell array)
+    # Flatten it to iterate (it might be [[obj1], [obj2]] or [[obj]])
+    polygons_flat = polygons_raw.flatten()
+    
+    polygons = []
+    for poly in polygons_flat:
+        # poly is a structured array (record) with named fields accessible via indexing
+        # Extract scalar values from 0-d arrays
+        idx_raw = poly['index'] if isinstance(poly, np.void) else poly['index'][0, 0]
+        name_raw = poly['name'] if isinstance(poly, np.void) else poly['name'][0, 0]
+        pts_raw = poly['points'] if isinstance(poly, np.void) else poly['points'][0, 0]
+        
+        idx = int(idx_raw.item() if hasattr(idx_raw, 'item') else idx_raw)
+        name = str(name_raw.item() if hasattr(name_raw, 'item') else name_raw)
+        
+        # pts might be a 2D array, convert to list of lists
+        points = pts_raw.tolist() if isinstance(pts_raw, np.ndarray) else list(pts_raw)
+        polygons.append({"index": idx, "name": name, "points": points})
+
+    return mask, polygons

pivtools_gui/__init__.py

@@ -0,0 +1,3 @@
+"""PIVTOOLs GUI - Web interface for Particle Image Velocimetry Tools"""
+
+__version__ = "0.1.1"