brkraw 0.3.11__py3-none-any.whl → 0.5.0__py3-none-any.whl

brkraw/resolver/datatype.py

@@ -0,0 +1,69 @@
+"""
+Utilities to resolve NumPy dtype and scaling parameters for Paravision scans/recos.
+
+Given a `Scan` or `Reco` object, `resolve()` inspects the relevant parameter
+objects (`acqp` for Scan, `visu_pars` for Reco) and returns a dict containing:
+    - dtype: NumPy dtype built from byte order and word type
+    - slope: VisuCoreDataSlope
+    - offset: VisuCoreDataOffs
+"""
+from __future__ import annotations
+from typing import Union, Optional, TypedDict, cast
+import numpy as np
+from .helpers import get_file
+from ..dataclasses import Scan, Reco
+
+
+WORDTYPE = {
+    "_32BIT_SGN_INT": "i",
+    "_16BIT_SGN_INT": "h",
+    "_8BIT_UNSGN_INT": "B",
+    "_32BIT_FLOAT": "f",
+}
+
+BYTEORDER = {
+    "littleEndian": "<",
+    "bigEndian": ">",
+}
+
+
+class ResolvedDatatype(TypedDict):
+    dtype: np.dtype
+    slope: Optional[float]
+    offset: Optional[float]
+
+
+
+def _get_dtype(byte_order: str, word_type: str) -> np.dtype:
+    if byte_order not in BYTEORDER:
+        raise ValueError(f"Unsupported byte order: {byte_order!r}")
+    if word_type not in WORDTYPE:
+        raise ValueError(f"Unsupported word type: {word_type!r}")
+    return np.dtype(f"{BYTEORDER[byte_order]}{WORDTYPE[word_type]}")
+
+
+def resolve(obj: Union["Scan", "Reco"]) -> Optional[ResolvedDatatype]:
+    """Return dtype/slope/offset metadata for a Scan or Reco."""
+    if isinstance(obj, Scan):
+        try:
+            p = get_file(obj, 'acqp')
+        except FileNotFoundError:
+            return None
+        byte_order = f'{p.get("BYTORDA")}Endian'
+        word_type = f'_{"".join(p["ACQ_word_size"].split("_"))}_SGN_INT'
+    elif isinstance(obj, Reco):
+        try:
+            p = get_file(obj, 'visu_pars')
+        except FileNotFoundError:
+            return None
+        byte_order = p.get('VisuCoreByteOrder')
+        word_type = p.get('VisuCoreWordType')
+    else:
+        raise TypeError(f"resolve() expects Scan or Reco, got {type(obj)!r}")
+    result: ResolvedDatatype = {
+        "dtype": _get_dtype(byte_order, word_type),
+        "slope": cast(Optional[float], p.get('VisuCoreDataSlope')),
+        "offset": cast(Optional[float], p.get('VisuCoreDataOffs')),
+    }
+
+    return result

brkraw/resolver/fid.py

@@ -0,0 +1,90 @@
+"""
+Locate and load Bruker Paravision FID/rawdata for custom reconstruction.
+
+This helper finds the FID (or rawdata) file in a Scan node, resolves the
+expected NumPy dtype from metadata, and returns a flat NumPy array. Optional
+byte offsets/sizes allow partial reads for debugging or incremental loading.
+Returns None when required files or dtype metadata are missing.
+"""
+from __future__ import annotations
+
+
+from warnings import warn
+from .datatype import resolve as datatype_resolver
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..dataclasses import Scan
+
+import numpy as np
+
+def get_fid(scan: "Scan"):
+    """Return the first FID/rawdata candidate in a scan, warning on multiples."""
+    fid_candidates = []
+    for fileobj in scan.iterdir():
+        if 'fid' in fileobj.name or 'rawdata' in fileobj.name:
+            fid_candidates.append(fileobj)
+    if len(fid_candidates) == 0:
+        return None
+    elif len(fid_candidates) > 1:
+        warn('Multiple FID file candidates found. Take first one.')
+    return fid_candidates[0]
+
+
+def resolve(
+    scan: "Scan",
+    buffer_start: Optional[int] = None,
+    buffer_size: Optional[int] = None,
+    *,
+    as_complex: bool = True,
+) -> Optional[np.ndarray]:
+    """Load FID as a NumPy array for reconstruction workflows.
+
+    Args:
+        scan: Scan node containing the FID/rawdata file.
+        buffer_start: Optional byte offset to start reading (default: 0).
+        buffer_size: Optional number of bytes to read (default: entire file).
+        as_complex: When True (default), interpret interleaved real/imag pairs
+            as complex samples. When False, return the raw 1D array.
+    
+    Returns:
+        1D NumPy array of complex samples (or raw when as_complex=False), or
+        None when file/dtype is missing.
+
+    Raises:
+        ValueError: If buffer_start or buffer_size is negative.
+    """
+    fid_entry = get_fid(scan)
+    if fid_entry is None:
+        return None
+
+    dtype_info = datatype_resolver(scan)
+    if not dtype_info or 'dtype' not in dtype_info:
+        return None
+
+    dtype = np.dtype(dtype_info['dtype'])
+    start = 0 if buffer_start is None else int(buffer_start)
+    size = None if buffer_size is None else int(buffer_size)
+
+    if start < 0 or (size is not None and size < 0):
+        raise ValueError("buffer_start and buffer_size must be non-negative")
+
+    with fid_entry.open() as f:
+        f.seek(start)
+        raw = f.read() if size is None else f.read(size)
+    data = np.frombuffer(raw, dtype)
+
+    if not as_complex:
+        return data
+
+    if data.size % 2 != 0:
+        raise ValueError("FID data length is not even; cannot form complex pairs.")
+
+    real = data[0::2]
+    imag = data[1::2]
+    return real.astype(np.float32, copy=False) + 1j * imag.astype(np.float32, copy=False)
+
+
+__all__ = [
+    'resolve'
+]

brkraw/resolver/helpers.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import numpy as np
+from typing import TYPE_CHECKING, Union, Tuple, List, Any
+if TYPE_CHECKING:
+    from ..dataclasses import Study, Scan, Reco
+
+
+def get_reco(obj: "Scan", reco_id):
+    if reco_id not in obj.avail.keys():
+        raise KeyError('reco_id')
+    return obj.avail[reco_id]
+
+
+def get_file(obj: Union["Study", "Scan", "Reco"], basename: str):
+    if not hasattr(obj, basename):
+        raise FileNotFoundError(basename)
+    else:
+        key = obj._full_path(basename)
+        if key in obj._cache.keys():
+            obj._cache.pop(key, None)
+    return getattr(obj, f'file_{basename}')
+
+def return_alt_val_if_none(val: object, alt_val: object) -> object:
+    if val is None:
+        return alt_val
+    return val
+
+def strip_comment(raw_comment: str):
+    return raw_comment.strip('<>').strip()
+
+
+def swap_element(obj: List[Any], index1: int, index2: int) -> List[Any]:
+    new_obj = obj[:]
+    new_obj[index1], new_obj[index2] = new_obj[index2], new_obj[index1]
+    return new_obj

brkraw/resolver/image.py

@@ -0,0 +1,188 @@
+"""
+Load Paravision `2dseq` data into a NumPy array with geometry metadata.
+
+This resolver reads dtype/slope/offset and shape info for a given `Scan`/`Reco`,
+then reshapes the `2dseq` buffer (Fortran order) and normalizes axis labels so
+the spatial z-axis sits at index 2. Returns None when required metadata or
+files are missing.
+"""
+from __future__ import annotations
+
+
+from typing import TYPE_CHECKING, Optional, Sequence, TypedDict, List, Tuple
+from .datatype import resolve as datatype_resolver
+from .shape import resolve as shape_resolver
+from .helpers import get_reco, get_file, swap_element
+import numpy as np
+
+if TYPE_CHECKING:
+    from ..dataclasses import Scan, Reco
+    from .shape import ResolvedShape
+    from .shape import ResolvedCycle
+
+
+class ResolvedImage(TypedDict):
+    dataobj: np.ndarray
+    slope: float
+    offset: float
+    shape_desc: List[str]
+    sliceorder_scheme: Optional[str]
+    num_cycles: int
+    time_per_cycle: Optional[float]
+
+
+Z_AXIS_DESCRIPTORS = {'spatial', 'slice', 'without_slice'}
+
+
+def _find_z_axis_candidate(shape_desc: Sequence[str]) -> Optional[int]:
+    """Return the first spatial z-axis descriptor index found at/after position 2."""
+    for idx, desc in enumerate(shape_desc):
+        if idx < 2:
+            continue
+        if desc in Z_AXIS_DESCRIPTORS:
+            return idx
+    return None
+
+
+def _normalize_zaxis_descriptor(shape_desc: List[str]) -> List[str]:
+    """Ensure the z-axis descriptor uses 'slice' to represent spatial depth."""
+    normalized = shape_desc[:]
+    if normalized[2] == 'without_slice':
+        normalized[2] = 'slice'
+    return normalized
+
+
+def _validate_swapped_axes(
+    dataobj: np.ndarray,
+    expected_shape: Sequence[int],
+    shape_desc: List[str],
+    original_zaxis_desc: str,
+    swapped_idx: int,
+):
+    """Validate shape/descriptor invariants after moving spatial z-axis into position 2."""
+    if dataobj.shape != tuple(expected_shape):
+        raise ValueError(f"data shape {dataobj.shape} does not match expected {tuple(expected_shape)} after z-axis swap")
+    if len(expected_shape) != len(shape_desc):
+        raise ValueError("shape and shape_desc length mismatch after z-axis normalization")
+    if shape_desc[swapped_idx] != original_zaxis_desc:
+        raise ValueError(f"axis {swapped_idx} descriptor mismatch after swap; expected '{original_zaxis_desc}'")
+    if shape_desc[2] not in Z_AXIS_DESCRIPTORS:
+        raise ValueError(f"z-axis descriptor '{shape_desc[2]}' is invalid; expected one of {sorted(Z_AXIS_DESCRIPTORS)}")
+
+
+def ensure_3d_spatial_data(dataobj: np.ndarray, shape_info: "ResolvedShape") -> Tuple[np.ndarray, List[str]]:
+    """
+    Normalize data and descriptors so the spatial z-axis sits at index 2.
+
+    Swaps axes when needed to place the first spatial z-axis descriptor at
+    position 2 and rewrites 'without_slice' to 'slice' for clarity.
+
+    Raises:
+        ValueError: When data dimensionality and shape_desc disagree or z-axis
+            descriptor is missing.
+    """
+    shape = shape_info['shape']
+    shape_desc = list(shape_info['shape_desc'])
+
+    if dataobj.ndim != len(shape_desc):
+        raise ValueError(f"dataobj.ndim ({dataobj.ndim}) and shape_desc length ({len(shape_desc)}) do not match")
+
+    if dataobj.ndim < 3 or len(shape_desc) < 3:
+        return dataobj, shape_desc
+
+    if shape_desc[2] in Z_AXIS_DESCRIPTORS:
+        return dataobj, _normalize_zaxis_descriptor(shape_desc)
+
+    zaxis_candi_idx = _find_z_axis_candidate(shape_desc)
+    if zaxis_candi_idx is None:
+        raise ValueError(f"z-axis descriptor not found in shape_desc starting at index 2: {shape_desc}")
+
+    pre_zaxis_desc = shape_desc[2]
+    new_dataobj = np.swapaxes(dataobj, 2, zaxis_candi_idx)
+    new_shape = swap_element(shape, 2, zaxis_candi_idx)
+    new_shape_desc = swap_element(shape_desc, 2, zaxis_candi_idx)
+
+    _validate_swapped_axes(new_dataobj, new_shape, new_shape_desc, pre_zaxis_desc, zaxis_candi_idx)
+
+    normalized_shape_desc = _normalize_zaxis_descriptor(new_shape_desc)
+    return new_dataobj, normalized_shape_desc
+
+
+def _read_2dseq_data(reco: "Reco", dtype: np.dtype, shape: Sequence[int]) -> np.ndarray:
+    """Read 2dseq file into a Fortran-ordered NumPy array with shape validation."""
+    expected_size = int(np.prod(shape)) * np.dtype(dtype).itemsize
+    with get_file(reco, "2dseq") as f:
+        f.seek(0)
+        raw = f.read()
+    if len(raw) != expected_size:
+        raise ValueError(f"2dseq size mismatch: expected {expected_size} bytes for shape {shape}, got {len(raw)}")
+    try:
+        return np.frombuffer(raw, dtype).reshape(shape, order="F")
+    except ValueError as exc:
+        raise ValueError(f"failed to reshape 2dseq buffer to shape {shape}") from exc
+
+
+def _normalize_cycle_info(cycle_info: Optional["ResolvedCycle"]) -> Tuple[int, Optional[float]]:
+    """Normalize cycle info and provide safe defaults when metadata is absent."""
+    if not cycle_info:
+        return 1, None
+    return int(cycle_info['num_cycles']), cycle_info.get('time_step')
+
+
+def resolve(scan: "Scan", reco_id: int = 1) -> Optional[ResolvedImage]:
+    """Load 2dseq as a NumPy array with associated metadata.
+
+    Args:
+        scan: Scan node containing the target reco.
+        reco_id: Reco identifier to read (default: 1).
+
+    Returns:
+        ImageResolveResult with:
+            - dataobj: NumPy array reshaped using Fortran order.
+            - slope/offset: intensity scaling.
+            - shape_desc: normalized descriptors with spatial z-axis at index 2.
+            - slice/cycle metadata.
+        None if required metadata or files are missing; raises ValueError on
+        inconsistent metadata.
+    """
+    reco: "Reco" = get_reco(scan, reco_id)
+
+    dtype_info = datatype_resolver(reco)
+    shape_info = shape_resolver(scan, reco_id=reco_id)
+    if not dtype_info or not shape_info:
+        return None
+
+    dtype = np.dtype(dtype_info["dtype"])
+    slope = dtype_info["slope"]
+    if slope is None:
+        slope = 1.0
+    offset = dtype_info["offset"]
+    if offset is None:
+        offset = 0.0
+    shape = shape_info["shape"]
+
+    try:
+        dataobj = _read_2dseq_data(reco, dtype, shape)
+    except FileNotFoundError:
+        return None
+
+    dataobj, shape_desc = ensure_3d_spatial_data(dataobj, shape_info)
+    num_cycles, time_per_cycle = _normalize_cycle_info(shape_info['objs'].cycle)
+
+    result: ResolvedImage = {
+        # image
+        'dataobj': dataobj,
+        'slope': slope,
+        'offset': offset,
+        'shape_desc': shape_desc,
+        'sliceorder_scheme': shape_info['sliceorder_scheme'],
+
+        # cycle
+        'num_cycles': num_cycles,
+        'time_per_cycle': time_per_cycle,
+    }
+    return result
+
+__all__ = [
+    'resolve'
+]