tofscope 0.1.0__py3-none-any.whl

tofscope/science/abundance.py

@@ -0,0 +1,42 @@
+"""Original-intensity isotope areas, with explicit coverage and ambiguity."""
+from dataclasses import dataclass,replace
+import numpy as np
+from contextlib import nullcontext
+from tofscope.science.signals import read_signal
+
+
+@dataclass(frozen=True)
+class IsotopeMeasurement:
+    recipe_id: str
+    requested_frames: tuple[int,int]
+    actual_frames: tuple[int,int] | None
+    summed_intensity: float | None
+    observed_fraction: float | None
+    ambiguous: bool
+    status: str
+
+
+def measure_isotopes(path,recipes,roi,frames,*,reader=None):
+    recipes=tuple(recipes)
+    if not recipes:raise ValueError('Choose at least one isotope window.')
+    if len(frames)!=2 or any(type(z) is not int for z in frames) or not 0<=frames[0]<=frames[1]:raise ValueError('Invalid measurement frame limits.')
+    if len(roi)!=4 or any(type(z) is not int for z in roi) or not (0<=roi[0]<=roi[1] and 0<=roi[2]<=roi[3]):raise ValueError('Invalid measurement ROI.')
+    first=max(frames[0],*(r.frames[0] for r in recipes));last=min(frames[1],*(r.frames[1] for r in recipes))
+    ambiguous=set()
+    for i,a in enumerate(recipes):
+        for j,b in enumerate(recipes[:i]):
+            if any(max(x0,y0)<=min(x1,y1) for x0,x1 in a.intervals for y0,y1 in b.intervals):ambiguous.update((i,j))
+    if first>last:
+        return [IsotopeMeasurement(r.id,tuple(frames),None,None,None,i in ambiguous,'No common frame coverage') for i,r in enumerate(recipes)]
+    rows=[];x0,x1,y0,y1=roi
+    for i,recipe in enumerate(recipes):
+        with reader(path,recipe) if reader else nullcontext(read_signal(path,recipe)) as source:
+            data = source.array if reader else source
+            if x1>=data.shape[2] or y1>=data.shape[1]:raise ValueError('Measurement ROI is outside the acquisition.')
+            area=float(data[first-recipe.frames[0]:last-recipe.frames[0]+1,y0:y1+1,x0:x1+1].sum(dtype=np.float64))
+        status='Overlapping mass windows' if i in ambiguous else 'Ambiguous selected set' if ambiguous else 'Common frame coverage' if (first,last)!=tuple(frames) else 'Measured'
+        rows.append(IsotopeMeasurement(recipe.id,tuple(frames),(first,last),area,None,i in ambiguous,status))
+    total=sum(r.summed_intensity for r in rows)
+    if not ambiguous and np.isfinite(total) and total>0:
+        rows=[replace(r,observed_fraction=r.summed_intensity/total) for r in rows]
+    return rows

tofscope/science/depth_calibration.py

@@ -0,0 +1,73 @@
+"""Physical profile coordinates; acquisition intensities and frames stay intact."""
+from dataclasses import dataclass
+import numpy as np
+
+
+@dataclass(frozen=True)
+class DepthAnchor:
+    frame: int
+    depth_nm: float
+
+
+def convert_depth(value,source_unit,target_unit):
+    scales={'nm':1.,'µm':1000.,'um':1000.,'mm':1e6}
+    if source_unit not in scales or target_unit not in scales:raise ValueError('Depth units must be nm, µm or mm.')
+    return np.asarray(value)*scales[source_unit]/scales[target_unit]
+
+
+def calibrated_window(frames,calibration=None):
+    """Intersect display coverage without extrapolating or changing selection."""
+    first,last=frames
+    if calibration:
+        first=max(first,calibration.anchors[0].frame);last=min(last,calibration.anchors[-1].frame)
+    return (first,last) if first<=last else None
+
+
+def display_depth(frames,calibration=None,unit='nm'):
+    return convert_depth(calibration.frame_to_depth(frames),'nm',unit) if calibration else np.asarray(frames)
+
+
+def validate_anchors(anchors,acquisition_frames):
+    if type(acquisition_frames) is not int or acquisition_frames<1:raise ValueError('Acquisition must contain frames.')
+    rows=[]
+    for a in anchors:
+        if type(a.frame) is not int or not 0<=a.frame<acquisition_frames:raise ValueError('Depth anchor frame must be an acquisition frame integer.')
+        if not np.isfinite(a.depth_nm):raise ValueError('Depths must be finite.')
+        if a.frame==0 and a.depth_nm!=0:raise ValueError('Frame 0 is fixed at depth 0.')
+        rows.append(DepthAnchor(a.frame,float(a.depth_nm)))
+    if not any(a.frame==0 for a in rows):rows.append(DepthAnchor(0,0.))
+    rows.sort(key=lambda a:a.frame)
+    for a,b in zip(rows,rows[1:]):
+        if a.frame==b.frame:raise ValueError('Depth anchor frames must be unique.')
+        if a.depth_nm>=b.depth_nm:raise ValueError('Depth must increase with acquisition frame.')
+    return tuple(rows)
+
+
+@dataclass(frozen=True)
+class DepthCalibration:
+    anchors: tuple[DepthAnchor,...]
+    acquisition_frames: int
+
+    def __post_init__(self):
+        rows=validate_anchors(self.anchors,self.acquisition_frames)
+        if len(rows)<2:raise ValueError('Add a positive-depth anchor to activate calibration.')
+        object.__setattr__(self,'anchors',rows)
+
+    def frame_to_depth(self,frames):
+        return np.interp(frames,[a.frame for a in self.anchors],[a.depth_nm for a in self.anchors],left=np.nan,right=np.nan)
+
+    def depth_to_frame(self,depth_nm):
+        return np.interp(depth_nm,[a.depth_nm for a in self.anchors],[a.frame for a in self.anchors],left=np.nan,right=np.nan)
+
+    def to_dict(self,unit='nm'):
+        convert_depth(1,'nm',unit)
+        return dict(anchors=[dict(frame=a.frame,depth_nm=a.depth_nm) for a in self.anchors],
+                    acquisition_frames=self.acquisition_frames,unit='µm' if unit=='um' else unit,
+                    interpolation='piecewise_linear',extrapolation=False)
+
+    @classmethod
+    def from_dict(cls,data):
+        if data.get('interpolation')!='piecewise_linear' or data.get('extrapolation') is not False:
+            raise ValueError('Unsupported depth interpolation policy.')
+        convert_depth(1,'nm',data['unit'])
+        return cls(tuple(DepthAnchor(**a) for a in data['anchors']),data['acquisition_frames'])

tofscope/science/integration.py

@@ -0,0 +1,149 @@
+"""Inclusive mass-window unions; display transforms never enter this module."""
+
+from dataclasses import dataclass
+import numpy as np
+from tofscope.storage.dataset_io import locked_read
+
+
+@dataclass(frozen=True)
+class EventBatch:
+    """Reader-independent event values and each spatial cell's slice into them."""
+
+    samples: np.ndarray
+    offsets: np.ndarray
+    lengths: np.ndarray
+    shape: tuple[int, ...]
+
+
+def canonical_intervals(intervals, axis_limits):
+    """Sort and merge touching/overlapping intervals, rejecting invalid limits."""
+    try:
+        limits = np.asarray(axis_limits, dtype=float)
+        pairs = np.asarray(tuple(intervals), dtype=float)
+    except (ValueError, TypeError) as exc:
+        raise ValueError("Mass windows must contain finite lower/upper pairs.") from exc
+    if limits.shape != (2,) or np.isnan(limits).any() or limits[0] >= limits[1]:
+        raise ValueError("Invalid calibrated mass-axis limits.")
+    if pairs.ndim != 2 or pairs.shape[1] != 2 or not len(pairs):
+        raise ValueError("Add at least one mass interval with lower and upper limits.")
+    if (
+        not np.isfinite(pairs).all()
+        or np.any(pairs[:, 0] >= pairs[:, 1])
+        or np.any(pairs[:, 0] < limits[0])
+        or np.any(pairs[:, 1] > limits[1])
+    ):
+        raise ValueError(
+            "Mass windows must be finite, lower < upper, and within the calibrated mass axis."
+        )
+    merged = []
+    for low, high in sorted(map(tuple, pairs)):
+        if merged and low <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(high, merged[-1][1]))
+        else:
+            merged.append((float(low), float(high)))
+    return tuple(merged)
+
+
+def integrate_event_windows(events, mass_axis, clock_ratio, normalization, intervals):
+    """Count each raw event once when its calibrated mass belongs to the union."""
+    # Compare exact stored bin values with user bounds without rounding those
+    # bounds down to the file's (often float32) dtype.
+    axis = np.asarray(mass_axis, dtype=np.float64)
+    if axis.ndim != 1 or not axis.size or not np.isfinite(axis).all():
+        raise ValueError("Mass axis must be a nonempty finite one-dimensional array.")
+    windows = canonical_intervals(intervals, (float(axis.min()), float(axis.max())))
+    if (
+        not np.isfinite([clock_ratio, normalization]).all()
+        or clock_ratio < 1
+        or int(clock_ratio) != clock_ratio
+        or normalization <= 0
+    ):
+        raise ValueError("Invalid timing ratio or normalization.")
+    included = np.zeros(len(axis), dtype=bool)
+    for low, high in windows:
+        included |= (axis >= low) & (axis <= high)
+    if isinstance(events, EventBatch):
+        lengths = events.lengths
+        offsets = events.offsets
+        raw_samples = events.samples
+    else:
+        cells = events.ravel()
+        lengths = np.fromiter(
+            (len(cell) for cell in cells), dtype=np.int64, count=cells.size
+        )
+        offsets = np.concatenate(([0], np.cumsum(lengths[:-1])))
+        raw_samples = np.concatenate(list(cells)) if lengths.sum() else np.empty(0)
+    if not lengths.sum():
+        return np.zeros(events.shape, dtype=np.float32)
+    samples = raw_samples.astype(np.int64) // int(clock_ratio)
+    valid = (samples >= 0) & (samples < len(axis))
+    selected = np.zeros(len(samples), dtype=np.int32)
+    selected[valid] = included[samples[valid]]
+    counts = np.concatenate(([0], np.cumsum(selected, dtype=np.int64)))
+    per_cell = counts[offsets + lengths] - counts[offsets]
+    return (per_cell.reshape(events.shape) / normalization).astype(np.float32)
+
+
+@locked_read
+def custom_peak_windows(
+    path, intervals, first, last, progress=None, cancel=None, reserve=None
+):
+    """Reconstruct a union in one read per supported acquisition depth slice."""
+    import h5py
+    from operator import index
+
+    try:
+        if isinstance(first, bool) or isinstance(last, bool):
+            raise TypeError
+        first, last = index(first), index(last)
+    except TypeError as exc:
+        raise ValueError("Integration frames must be integers.") from exc
+    with h5py.File(path, "r") as f:
+        if "FullSpectra/EventList" not in f:
+            raise ValueError("This file does not retain raw events.")
+        nz, ny, nx, _ = f["PeakData/PeakData"].shape
+        raw = f["FullSpectra/EventList"]
+        from contextlib import ExitStack
+
+        class Unmanaged:
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *args):
+                pass
+
+            def release(self):
+                pass
+
+        reserve = reserve or (lambda size: Unmanaged())
+        with ExitStack() as allocation:
+            allocation.enter_context(
+                reserve(int(f["FullSpectra/MassAxis"].size * 32 + 4096))
+            )
+            return _integrate_frames(
+                f, raw, nz, ny, nx, intervals, first, last, progress, cancel, reserve
+            )
+
+
+def _integrate_frames(
+    f, raw, nz, ny, nx, intervals, first, last, progress, cancel, reserve
+):
+    from tofscope.storage.bounded_events import admitted_events
+    from tofscope.storage.explorer import integration_parameters
+
+    axis = f["FullSpectra/MassAxis"][:]
+    windows = canonical_intervals(intervals, (float(axis.min()), float(axis.max())))
+    if not 0 <= first <= last < nz or last >= raw.shape[0] or raw.shape[1:] != (ny, nx):
+        raise ValueError("Requested frame range or raw spatial shape is invalid.")
+    ratio, normalization = integration_parameters(f)
+    volume = np.empty((last - first + 1, ny, nx), dtype=np.float32)
+    for i, z in enumerate(range(first, last + 1)):
+        if cancel is not None and cancel():
+            raise InterruptedError("Integration cancelled.")
+        with admitted_events(raw, z, reserve) as events:
+            volume[i] = integrate_event_windows(
+                events, axis, ratio, normalization, windows
+            )
+        if progress is not None:
+            progress(i + 1, len(volume))
+    return volume

tofscope/science/isotopes.py

@@ -0,0 +1,90 @@
+"""Offline atomic-isotope candidates with explicit charge and provenance."""
+from dataclasses import dataclass
+from pathlib import Path
+import hashlib
+import json
+import math
+import re
+
+ELECTRON_MASS_U=0.0005485799090441  # CODATA2022, NIST electron mass in u.
+from importlib.resources import files
+CATALOG_PATH=files('tofscope.resources').joinpath('reference/isotopes.json')
+
+
+@dataclass(frozen=True)
+class IsotopeRecord:
+    symbol: str
+    mass_number: int
+    neutral_mass_u: float
+    abundance_low: float | None
+    abundance_high: float | None
+    source_id: str
+    mass_uncertainty_u: float | None = None
+    mass_estimated: bool = False
+    abundance_uncertainty: float | None = None
+
+    def __post_init__(self):
+        if not re.fullmatch(r'[A-Z][a-z]{0,2}',self.symbol) or type(self.mass_number) is not int or self.mass_number<1:
+            raise ValueError('Invalid isotope identity.')
+        if not math.isfinite(self.neutral_mass_u) or self.neutral_mass_u<=0 or not self.source_id:
+            raise ValueError('Invalid isotope mass or source.')
+        lo,hi=self.abundance_low,self.abundance_high
+        if (lo is None)!=(hi is None) or (lo is not None and not (math.isfinite(lo) and math.isfinite(hi) and 0<=lo<=hi<=1)):
+            raise ValueError('Invalid reference abundance interval.')
+        for value in (self.mass_uncertainty_u,self.abundance_uncertainty):
+            if value is not None and (not math.isfinite(value) or value<0):raise ValueError('Invalid reference uncertainty.')
+
+
+@dataclass(frozen=True)
+class IonCandidate:
+    isotope: IsotopeRecord
+    charge: int
+    predicted_mz: float
+    error_Th: float
+    error_ppm: float
+
+    @property
+    def id(self):return f'{self.isotope.symbol}-{self.isotope.mass_number}:{self.charge:+d}'
+
+
+def ion_mz(record,charge: int):
+    if type(charge) is not int or charge not in (-3,-2,-1,1,2,3):raise ValueError('Atomic charge must be ±1, ±2 or ±3.')
+    return (record.neutral_mass_u-charge*ELECTRON_MASS_U)/abs(charge)
+
+
+class CandidateLimitExceeded(ValueError):
+    pass
+
+
+def find_candidates(mz,tolerance,tolerance_unit,charges,catalog,*,max_results=None):
+    if not math.isfinite(mz) or mz<=0:raise ValueError('Measured m/z must be positive and finite.')
+    if not math.isfinite(tolerance) or tolerance<0:raise ValueError('Tolerance must be finite and nonnegative.')
+    if tolerance_unit not in ('Th','ppm'):raise ValueError('Tolerance units must be Th or ppm.')
+    if not charges:raise ValueError('Select at least one charge state.')
+    for charge in charges:
+        if type(charge) is not int or charge not in (-3,-2,-1,1,2,3):raise ValueError('Atomic charge must be ±1, ±2 or ±3.')
+    candidates=[]
+    for isotope in catalog:
+        for charge in sorted(set(charges)):
+            predicted=ion_mz(isotope,charge);error=mz-predicted;ppm=error/predicted*1e6
+            if abs(error if tolerance_unit=='Th' else ppm)<=tolerance:
+                if max_results is not None and len(candidates) >= max_results:
+                    raise CandidateLimitExceeded('Too many atomic candidates; narrow the tolerance or charge states.')
+                candidates.append(IonCandidate(isotope,charge,predicted,error,ppm))
+    return sorted(candidates,key=lambda r:(abs(r.error_Th),r.isotope.symbol,r.isotope.mass_number,r.charge))
+
+
+def records_checksum(records):
+    return hashlib.sha256(json.dumps(records,sort_keys=True,separators=(',',':')).encode()).hexdigest()
+
+
+def load_catalog(path=None):
+    data=json.loads(Path(path or CATALOG_PATH).read_text())
+    meta=data['metadata'];records=data['isotopes']
+    if meta.get('schema_version')!=1 or not meta.get('sources') or not meta.get('retrieved') or not meta.get('redistribution_review'):
+        raise ValueError('Reference provenance is incomplete.')
+    if records_checksum(records)!=meta['records_sha256']:raise ValueError('Isotope reference checksum mismatch.')
+    result=tuple(IsotopeRecord(**row) for row in records)
+    keys=[(r.symbol,r.mass_number) for r in result]
+    if len(set(keys))!=len(keys):raise ValueError('Duplicate isotope reference identity.')
+    return result

tofscope/science/raw_peaks.py

@@ -0,0 +1,50 @@
+"""Frame-sized floating-point peak reconstruction, independent of HDF5 and UI."""
+import numpy as np
+from tofscope.science.integration import EventBatch
+
+
+def integrate_peak_table(events, mass_axis, clock_ratio, normalization, windows):
+    """Count every event in each inclusive window, preserving overlaps and order.
+
+    Disjoint windows are grouped so ordinary nominal tables take one or two
+    vectorized passes through the events, rather than one pass per channel.
+    """
+    axis = np.asarray(mass_axis, dtype=np.float64)
+    bounds = np.asarray(windows, dtype=np.float64)
+    if (axis.ndim != 1 or not len(axis) or not np.isfinite(axis).all()
+            or bounds.ndim != 2 or bounds.shape[1] != 2 or not len(bounds)
+            or not np.isfinite(bounds).all() or np.any(bounds[:, 0] >= bounds[:, 1])
+            or not np.isfinite([clock_ratio, normalization]).all()
+            or clock_ratio < 1 or int(clock_ratio) != clock_ratio or normalization <= 0):
+        raise ValueError('Invalid raw calibration or peak windows.')
+    if isinstance(events, EventBatch):
+        raw, lengths, offsets = events.samples, events.lengths, events.offsets
+    else:
+        cells = events.ravel()
+        lengths = np.fromiter((len(cell) for cell in cells), dtype=np.int64, count=len(cells))
+        offsets = np.concatenate(([0], np.cumsum(lengths[:-1])))
+        raw = np.concatenate(list(cells)) if lengths.sum() else np.empty(0, dtype='uint32')
+    result = np.zeros((len(lengths), len(bounds)), dtype=np.float32)
+    if not lengths.sum():
+        return result.reshape((*events.shape, len(bounds)))
+    # Bounded HDF5 arenas may contain padding; select only each cell's events.
+    positions = np.repeat(offsets - np.cumsum(lengths) + lengths, lengths) + np.arange(lengths.sum())
+    samples = raw[positions].astype(np.int64) // int(clock_ratio)
+    valid = (samples >= 0) & (samples < len(axis))
+    masses = axis[samples[valid]]
+    pixels = np.repeat(np.arange(len(lengths), dtype=np.int64), lengths)[valid]
+    groups = []
+    for index in np.argsort(bounds[:, 0], kind='stable'):
+        for group in groups:
+            if bounds[group[-1], 1] < bounds[index, 0]:
+                group.append(index)
+                break
+        else:
+            groups.append([index])
+    for group in groups:
+        subset = bounds[group]
+        bins = np.searchsorted(subset[:, 0], masses, side='right') - 1
+        selected = (bins >= 0) & (masses <= subset[np.maximum(0, bins), 1])
+        counts = np.bincount(pixels[selected] * len(group) + bins[selected], minlength=len(lengths) * len(group))
+        result[:, group] = (counts.reshape(len(lengths), len(group)) / normalization).astype(np.float32)
+    return result.reshape((*events.shape, len(bounds)))

tofscope/science/signals.py

@@ -0,0 +1,114 @@
+"""Immutable scientific signal definitions, independent of presentation state."""
+from dataclasses import dataclass,field
+from operator import index
+from uuid import UUID,uuid4
+
+from tofscope.science.integration import canonical_intervals
+from tofscope.storage.dataset_io import locked_read
+
+
+def _integer(value):
+    if isinstance(value,bool):
+        raise ValueError('Frame and channel indices must be integers.')
+    try:
+        return index(value)
+    except TypeError as exc:
+        raise ValueError('Frame and channel indices must be integers.') from exc
+
+
+def interval_label(intervals):
+    return ' ∪ '.join(f'{low:.4f}–{high:.4f}' for low,high in intervals)+' Th'
+
+
+@dataclass(frozen=True)
+class SignalRecipe:
+    id: str=field(default_factory=lambda:str(uuid4()))
+    label: str=''
+    source: str='custom'
+    stored_index: int|None=None
+    saved_id: str|None=None
+    intervals: tuple[tuple[float,float],...]=()
+    frames: tuple[int,int]=(0,0)
+
+    def __post_init__(self):
+        try:
+            identifier=str(UUID(self.id))
+        except (ValueError,AttributeError,TypeError) as exc:
+            raise ValueError('Signal ID must be a UUID.') from exc
+        if self.source not in ('stored','custom','saved'):
+            raise ValueError('Unknown signal source.')
+        if not isinstance(self.label,str):
+            raise ValueError('Signal label must be text.')
+        try:
+            first,last=map(_integer,self.frames)
+        except (TypeError,ValueError) as exc:
+            raise ValueError('Frames must contain two inclusive integer limits.') from exc
+        if not 0<=first<=last:
+            raise ValueError('Frames must be nonnegative and first <= last.')
+        stored=_integer(self.stored_index) if self.stored_index is not None else None
+        if ((self.source=='stored' and (stored is None or stored<0))
+                or (self.source!='stored' and stored is not None)):
+            raise ValueError('Only stored signals must reference a stored channel index.')
+        if self.source=='saved':
+            try:
+                saved=str(UUID(self.saved_id))
+            except (TypeError,AttributeError,ValueError) as exc:
+                raise ValueError('Saved signals must reference a saved UUID.') from exc
+        elif self.saved_id is not None:
+            raise ValueError('Only saved signals may reference saved data.')
+        else:
+            saved=None
+        windows=canonical_intervals(self.intervals,(float('-inf'),float('inf')))
+        object.__setattr__(self,'id',identifier)
+        object.__setattr__(self,'stored_index',stored)
+        object.__setattr__(self,'saved_id',saved)
+        object.__setattr__(self,'intervals',windows)
+        object.__setattr__(self,'frames',(first,last))
+
+    def to_dict(self):
+        return dict(schema_version=3,id=self.id,label=self.label,source=self.source,
+                    stored_index=self.stored_index,saved_id=self.saved_id,
+                    intervals=[list(w) for w in self.intervals],frames=list(self.frames))
+
+    @classmethod
+    def from_dict(cls,value):
+        version=value.get('schema_version')
+        if version==2:
+            source={'raw_reconstruction':'custom','stored':'stored'}.get(value.get('source'))
+            if source is None:
+                raise ValueError('Unknown legacy signal source.')
+            if source=='stored' and value.get('stored_index') is None:
+                raise ValueError('Legacy stored recipes need a stored channel index; choose that channel to restore it.')
+            return cls(label=value.get('signal',''),source=source,stored_index=value.get('stored_index'),
+                       intervals=((value['lower_Th'],value['upper_Th']),),frames=tuple(value['frames_inclusive']))
+        if version!=3:
+            raise ValueError('Unsupported signal recipe schema version.')
+        return cls(id=value['id'],label=value.get('label',''),source=value['source'],
+                   stored_index=value.get('stored_index'),saved_id=value.get('saved_id'),
+                   intervals=value['intervals'],frames=value['frames'])
+
+    def computation_key(self,path):
+        from tofscope.storage.explorer import file_key
+        return (file_key(path),self.source,self.stored_index,self.saved_id,self.intervals,self.frames)
+
+
+@locked_read
+def read_signal(path, recipe, progress=None):
+    """Return (depth,y,x), with array index zero at recipe.frames[0]."""
+    import h5py
+    from tofscope.storage.explorer import stored_peak
+    from tofscope.science.integration import custom_peak_windows
+    if recipe.source=='saved':
+        from tofscope.storage.integration_store import read_saved_integration,saved_integration_info
+        info=saved_integration_info(path,recipe.saved_id)
+        first,last=info['derivation']['frames']
+        if recipe.frames[0]<first or recipe.frames[1]>last or recipe.intervals!=tuple(tuple(w) for w in info['derivation']['intervals']):
+            raise ValueError('Saved reference coverage or intervals do not match its derivation.')
+        return read_saved_integration(path,recipe.saved_id)[recipe.frames[0]-first:recipe.frames[1]-first+1]
+    if recipe.source=='custom':
+        return custom_peak_windows(path,recipe.intervals,*recipe.frames,progress)
+    with h5py.File(path,'r') as f:
+        shape=f['PeakData/PeakData'].shape
+        if recipe.frames[1]>=shape[0] or recipe.stored_index>=shape[-1]:
+            raise ValueError('Stored channel or frame range is outside the acquisition.')
+    return stored_peak(path,recipe.stored_index)[recipe.frames[0]:recipe.frames[1]+1]

tofscope/science/volume_layers.py

@@ -0,0 +1,112 @@
+from contextlib import nullcontext
+"""Shared, acquisition-aligned previews with a total visible-voxel budget."""
+from collections import OrderedDict
+from dataclasses import dataclass,replace
+import math
+import numpy as np
+from tofscope.storage.explorer import inspect_file,file_key
+from tofscope.science.signals import SignalRecipe,read_signal
+from tofscope.science.depth_calibration import calibrated_window
+
+COLORSCALES=('Viridis','Magma','Plasma','Cividis','Reds','Blues','Greens','Purples')
+
+
+@dataclass
+class VolumeLayer:
+    id: str
+    recipe: SignalRecipe
+    visible: bool = True
+    colorscale: str = 'Viridis'
+    opacity: float = .12
+    percentile: float = 70.
+
+    def __post_init__(self):
+        if not isinstance(self.id,str) or not self.id:raise ValueError('Layer ID is required.')
+        if type(self.visible) is not bool or self.colorscale not in COLORSCALES:raise ValueError('Invalid layer visibility or colormap.')
+        if not math.isfinite(self.opacity) or not 0<=self.opacity<=1:raise ValueError('Opacity must lie between 0 and 1.')
+        if not math.isfinite(self.percentile) or not 0<=self.percentile<=100:raise ValueError('Percentile must lie between 0 and 100.')
+
+
+@dataclass(frozen=True)
+class PreviewGrid:
+    z: np.ndarray
+    y: np.ndarray
+    x: np.ndarray
+    edges: tuple[np.ndarray,np.ndarray,np.ndarray]
+    physical_xy: bool
+    xy_extent: tuple[float,float] | None = None
+
+
+@dataclass(frozen=True)
+class VolumePreview:
+    layer_id: str
+    recipe: SignalRecipe
+    grid: PreviewGrid
+    values: np.ndarray
+    coverage: np.ndarray
+    valid_counts: np.ndarray
+
+
+_CACHE=OrderedDict()
+_CACHE_BYTES=0
+
+def clear_preview_cache():
+    global _CACHE_BYTES
+    _CACHE.clear();_CACHE_BYTES=0
+
+
+def build_layer_previews(path,layers,roi,frames,*,quality,voxel_budget=500_000,reader=None,calibration=None,use_cache=True,reader_context=None):
+    global _CACHE_BYTES
+    enabled=[layer for layer in layers if layer.visible]
+    if not enabled:return []
+    if type(voxel_budget) is not int or voxel_budget<len(enabled):raise ValueError('Preview budget must allow at least one voxel per visible layer.')
+    if quality not in ('Fast','Detailed'):raise ValueError('Unknown preview quality.')
+    meta=inspect_file(path);shape=meta['shape']
+    if len(frames)!=2 or any(type(z) is not int for z in frames) or not 0<=frames[0]<=frames[1]<shape[0]:raise ValueError('Invalid preview depth window.')
+    frames=calibrated_window(frames,calibration)
+    if frames is None:return []
+    if len(roi)!=4 or any(type(z) is not int for z in roi) or not (0<=roi[0]<=roi[1]<shape[2] and 0<=roi[2]<=roi[3]<shape[1]):raise ValueError('Invalid preview ROI.')
+    x0,x1,y0,y1=roi
+    sizes=(frames[1]-frames[0]+1,y1-y0+1,x1-x0+1);limits=(96,32,32) if quality=='Fast' else (160,48,48)
+    steps=[max(1,math.ceil(n/limit)) for n,limit in zip(sizes,limits)]
+    counts=lambda:[math.ceil(n/step) for n,step in zip(sizes,steps)]
+    while math.prod(counts())*len(enabled)>voxel_budget:
+        axis=max(range(3),key=lambda i:counts()[i]);steps[axis]+=1
+    starts=(frames[0],y0,x0)
+    edges=tuple(np.r_[np.arange(start,start+size,step),start+size] for start,size,step in zip(starts,sizes,steps))
+    z,y,x=((e[:-1]+e[1:]-1)/2 for e in edges)
+    fov=meta['fov_um']
+    if fov:y=(y+.5)*fov/shape[1];x=(x+.5)*fov/shape[2]
+    extent=((x1-x0+1)*fov/shape[2],(y1-y0+1)*fov/shape[1]) if fov else (x1-x0+1,y1-y0+1)
+    if calibration:
+        z=np.array([np.mean(calibration.frame_to_depth(np.arange(lo,hi))) for lo,hi in zip(edges[0][:-1],edges[0][1:])])
+    grid=PreviewGrid(z,y,x,edges,bool(fov),extent);result=[];identity=file_key(path)
+    block_sizes=np.diff(edges[0])[:,None,None]*np.diff(edges[1])[None,:,None]*np.diff(edges[2])[None,None,:]
+    for layer in enabled:
+        r=layer.recipe
+        key=(identity,r.source,r.stored_index,r.saved_id,r.intervals,r.frames,tuple(roi),tuple(frames),tuple(steps))
+        cached=_CACHE.get(key) if use_cache else None
+        if cached is None:
+            context=reader_context(r) if reader_context else nullcontext((reader or read_signal)(path,r))
+            with context as data:
+                if data.shape!=(r.frames[1]-r.frames[0]+1,shape[1],shape[2]):raise ValueError('Volume coverage does not match its recipe.')
+                values=np.full(tuple(counts()),np.nan,dtype=np.float32);valid_counts=np.zeros(values.shape,dtype=np.int32)
+                for i,(lo,hi) in enumerate(zip(edges[0],edges[0][1:])):
+                    first=max(int(lo),r.frames[0]);last=min(int(hi)-1,r.frames[1])
+                    if first>last:continue
+                    part=data[first-r.frames[0]:last-r.frames[0]+1,y0:y1+1,x0:x1+1]
+                    valid=np.isfinite(part);sums=np.where(valid,part,0).sum(axis=0,dtype=np.float64);numbers=valid.sum(axis=0,dtype=np.int32)
+                    for axis,offset in ((0,y0),(1,x0)):
+                        idx=edges[axis+1][:-1]-offset
+                        sums=np.add.reduceat(sums,idx,axis=axis);numbers=np.add.reduceat(numbers,idx,axis=axis)
+                    valid_counts[i]=numbers;np.divide(sums,numbers,out=values[i],where=numbers>0)
+                coverage=(valid_counts/block_sizes).astype(np.float32)
+            cached=(values,coverage,valid_counts)
+            for array in cached:array.setflags(write=False)
+            if use_cache:
+                _CACHE[key]=cached;_CACHE_BYTES+=sum(a.nbytes for a in cached)
+                while _CACHE_BYTES>64*2**20 and len(_CACHE)>1:
+                    _,old=_CACHE.popitem(last=False);_CACHE_BYTES-=sum(a.nbytes for a in old)
+        else:_CACHE.move_to_end(key)
+        result.append(VolumePreview(layer.id,r,grid,*cached))
+    return result