perception-pnrf 1.0.0__py3-none-any.whl

perception_pnrf/__init__.py

@@ -0,0 +1,31 @@
+from .models import (
+    AcquisitionRecord,
+    GlobalMeta,
+    MainframeRole,
+    PnrfChannel,
+    PnrfGroup,
+    PnrfRecorder,
+    PnrfSegment,
+    SampleEncoding,
+    SegmentRelation,
+    SptFrame,
+    TriggerRecord,
+    TriggerSource,
+)
+from .pnrf import PnrfFile
+
+__all__ = [
+    "AcquisitionRecord",
+    "GlobalMeta",
+    "MainframeRole",
+    "PnrfChannel",
+    "PnrfFile",
+    "PnrfGroup",
+    "PnrfRecorder",
+    "PnrfSegment",
+    "SampleEncoding",
+    "SegmentRelation",
+    "SptFrame",
+    "TriggerRecord",
+    "TriggerSource",
+]

perception_pnrf/dump.py

@@ -0,0 +1,310 @@
+# pyright: reportPrivateUsage=false
+
+"""Dump PNRF file contents in HDF5-style format for comparison testing."""
+
+from __future__ import annotations
+
+import math
+import sys
+from pathlib import Path
+from typing import TextIO
+
+import numpy as np
+
+from .models import PnrfChannel, PnrfSegment, SegmentRelation
+from .pnrf import PnrfFile
+
+_SAMPLES_PER_SECTION = 3
+
+
+def _format_value(value: float) -> str:
+    """Format a value with 6 significant digits (matching C# G6)."""
+    if math.isnan(value):
+        return "NaN"
+    if value == 0.0:
+        return "0"
+    s = f"{value:.6g}"
+    # C# G6 uses uppercase E for exponent
+    return s.replace("e+", "E+").replace("e-", "E-")
+
+
+def _utc_start_str(pnrf: PnrfFile) -> str:
+    """Format the UTC start time."""
+    meta = pnrf.metadata
+    if meta.recording_start_utc is not None:
+        dt = meta.recording_start_utc
+        ticks = meta._utc_start_frac_ticks
+        return f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d}T{dt.hour:02d}:{dt.minute:02d}:{dt.second:02d}.{ticks:07d}Z"
+    return "(unknown)"
+
+
+def _time_mark_type_name(channel_bitmask: int) -> str:
+    """Convert trigger channel bitmask to TimeMarkType name."""
+    low = channel_bitmask & 0xFFFF
+    names = {0: "TimeMarkType_Started", 1: "TimeMarkType_Finished", 2: "TimeMarkType_Triggered", 3: "TimeMarkType_Trigger"}
+    return names.get(low, f"TimeMarkType_{low}")
+
+
+def dump(pnrf: PnrfFile, writer: TextIO) -> None:
+    """Dump a PNRF file in HDF5-style format."""
+    meta = pnrf.metadata
+    recorders = pnrf.recorders
+
+    title = meta.title
+    if not title:
+        title = Path(meta.filename).stem
+
+    utc_start = _utc_start_str(pnrf)
+
+    writer.write("HDF5-style dump (PNRF)\n")
+    writer.write("FILE {\n")
+    writer.write("   FILE_ATTRIBUTES {\n")
+    writer.write(f'      TITLE     = "{title}"\n')
+    comment_str = meta.comment.replace("\n", "\r\n") if meta.comment else "(null)"
+    writer.write(f'      COMMENT   = "{comment_str}"\n')
+    writer.write("   }\n")
+
+    # Data values (excluding Title)
+    data_values = [(k, v) for k, v in meta.data_values.items() if k != "Title"]
+    if data_values:
+        writer.write("   DATA_VALUES {\n")
+        for key, val in data_values:
+            escaped = val.replace("\n", "\r\n")
+            writer.write(f'      "{key}" (DataSourceDataType_String) = "{escaped}"\n')
+        writer.write("   }\n")
+
+    writer.write(f"   RECORDERS ({len(recorders)}) {{\n")
+
+    for recorder_index, recorder in enumerate(recorders):
+        writer.write(f'      RECORDER[{recorder_index + 1}] "{recorder.logical_name}" {{\n')
+        writer.write(f'         PHYSICAL_NAME = "{recorder.physical_name}"\n')
+        writer.write('         X_UNITS       = "s"\n')
+
+        # Triggers
+        if recorder.trigger_records:
+            writer.write(f"         TRIGGERS ({len(recorder.trigger_records)}) {{\n")
+            for trigger_index, trigger in enumerate(recorder.trigger_records):
+                writer.write(
+                    f"            [{trigger_index + 1}] time={_format_value(trigger.time)}"
+                    f"  type={_time_mark_type_name(trigger._channel_bitmask)}\n"
+                )
+            writer.write("         }\n")
+
+        # Visible channels
+        visible_channels = [
+            ch for ch in recorder.channels if len(ch.segments) > 0 or (ch.is_spt and len(ch._raw_segments) > 0)
+        ]
+
+        writer.write(f"         CHANNELS ({len(visible_channels)}) {{\n")
+
+        for channel_index, channel in enumerate(visible_channels):
+            writer.write(f'            CHANNEL[{channel_index + 1}] "{channel.logical_name}" {{\n')
+
+            if channel.is_spt:
+                channel_type = "DataChannelType_Blob"
+            elif channel.is_event:
+                channel_type = "DataChannelType_Event"
+            else:
+                channel_type = "DataChannelType_Analog"
+
+            writer.write(f"               TYPE      = {channel_type}\n")
+            writer.write("               TIMESHIFT = 0 s\n")
+
+            if channel.is_spt:
+                writer.write("               // (non-waveform channel, skipping data)\n")
+                writer.write("            }\n")
+                continue
+
+            writer.write(f'               X_UNIT    = "s"\n')
+            writer.write(f'               Y_UNIT    = "{channel.units}"\n')
+
+            data_type = "DataSourceDataType_DigitalWaveform" if channel.is_event else "DataSourceDataType_AnalogWaveform"
+            writer.write(f"               DATA_TYPE = {data_type}\n")
+
+            has_matd = any(s._tag == "MATD" for s in channel.segments)
+            time_info = "DataSourceTimeInfo_Explicit" if has_matd else "DataSourceTimeInfo_Implicit"
+            writer.write(f"               TIME_INFO = {time_info}\n")
+            writer.write(f"               UTC_START = {utc_start}\n")
+
+            segments = channel.segments
+            sweep_records = recorder.sweep_records
+
+            # Sweep range
+            if segments:
+                range_start = min(_segment_range_start(s) for s in segments)
+                range_end = max(s.start_time + (s.sample_count - 1) * s.sample_interval for s in segments)
+
+                # Apply recording_end_time for MATD channels
+                if has_matd and channel.recording_end_time is not None:
+                    if recorder.continuous_records:
+                        cont_record = recorder.continuous_records[0]
+                        cdi_end = (
+                            cont_record.start_time
+                            + recorder.time_base_offset
+                            + (cont_record.sample_count - 1) * cont_record.sample_interval
+                        )
+                        range_end = max(range_end, min(cdi_end, channel.recording_end_time))
+                    else:
+                        range_end = max(range_end, channel.recording_end_time)
+
+                writer.write(
+                    f"               SWEEP_RANGE = [{_format_value(range_start)} s .. {_format_value(range_end)} s]"
+                    f"  count={len(sweep_records)}\n"
+                )
+
+            # Sweeps
+            if sweep_records:
+                writer.write(f"               SWEEPS ({len(sweep_records)}) {{\n")
+                for sweep_index, sweep in enumerate(sweep_records):
+                    sweep_start = sweep.start_time + recorder.time_base_offset
+                    sweep_end = sweep_start + (sweep.sample_count - 1) * sweep.sample_interval
+                    sweep_trigger = sweep.trigger_time + recorder.time_base_offset
+                    writer.write(
+                        f"                  [{sweep_index + 1}] start={_format_value(sweep_start)} s"
+                        f"  end={_format_value(sweep_end)} s"
+                        f"  trigger={_format_value(sweep_trigger)} s"
+                        f"  source=TriggerSource_{sweep.trigger_source.name.capitalize()}"
+                        f"  finished=True\n"
+                    )
+                writer.write("               }\n")
+
+            # Segments
+            writer.write(f"               SEGMENTS ({len(segments)}) {{\n")
+            for segment_index, segment in enumerate(segments):
+                end_time = segment.start_time + (segment.sample_count - 1) * segment.sample_interval
+                sample_rate = 1.0 / segment.sample_interval if segment.sample_interval != 0 else 0.0
+
+                # Compute relation dynamically
+                if segment_index == 0:
+                    relation = SegmentRelation.NONE
+                else:
+                    prev = segments[segment_index - 1]
+                    prev_end = prev.start_time + (prev.sample_count - 1) * prev.sample_interval
+                    gap = segment.start_time - prev_end
+                    relation = (
+                        SegmentRelation.CONTINUOUS
+                        if gap <= max(prev.sample_interval, segment.sample_interval) + 1e-9
+                        else SegmentRelation.NONE
+                    )
+
+                writer.write(f"                  SEGMENT[{segment_index + 1}] {{\n")
+                writer.write(f"                     START_TIME       = {_format_value(segment.start_time)} s\n")
+                writer.write(f"                     END_TIME         = {_format_value(end_time)} s\n")
+                writer.write(
+                    f"                     SAMPLE_INTERVAL  = {_format_value(segment.sample_interval)} s"
+                    f"  ({_format_value(sample_rate)} Hz)\n"
+                )
+                writer.write(f"                     TOTAL_SAMPLES    = {segment.sample_count}\n")
+                writer.write(
+                    f"                     RELATION_TO_PREV = SegmentRelation_{relation.name.capitalize()}\n"
+                )
+                writer.write(f"                     Y0               = {_format_value(segment._y0)}\n")
+                writer.write(f"                     Y_STEP           = {_format_value(segment._y_step)}\n")
+
+                # Data samples
+                total_samples = segment.sample_count
+                fetch_count = min(_SAMPLES_PER_SECTION, total_samples)
+                writer.write(f"                     DATA (first {fetch_count} of {total_samples} samples) {{\n")
+
+                # First N samples
+                _print_samples(channel, segment_index, 0, fetch_count, writer)
+
+                if total_samples > _SAMPLES_PER_SECTION:
+                    center = total_samples // 2 - _SAMPLES_PER_SECTION // 2
+                    if center >= _SAMPLES_PER_SECTION:
+                        writer.write(f"                        ... ({center} more values omitted)\n")
+                        _print_samples(channel, segment_index, center, _SAMPLES_PER_SECTION, writer)
+
+                        end_idx = total_samples - _SAMPLES_PER_SECTION
+                        if end_idx >= center + _SAMPLES_PER_SECTION:
+                            omitted2 = end_idx - (center + _SAMPLES_PER_SECTION)
+                            if omitted2 > 0:
+                                writer.write(f"                        ... ({omitted2} more values omitted)\n")
+                            _print_samples(channel, segment_index, end_idx, _SAMPLES_PER_SECTION, writer)
+
+                writer.write("                     }\n")
+                writer.write("                  }\n")
+            writer.write("               }\n")
+            writer.write("            }\n")
+        writer.write("         }\n")
+        writer.write("      }\n")
+    writer.write("   }\n")
+
+    # CHANNELS_FLAT
+    all_channels: list[tuple[str, str, bool, bool]] = []
+    for recorder in recorders:
+        visible_ch = [
+            ch for ch in recorder.channels if len(ch.segments) > 0 or (ch.is_spt and len(ch._raw_segments) > 0)
+        ]
+        for channel in visible_ch:
+            all_channels.append((channel.logical_name, recorder.logical_name, channel.is_event, channel.is_spt))
+
+    writer.write(f"   CHANNELS_FLAT ({len(all_channels)}) {{\n")
+    for flat_index, (channel_name, recorder_name, is_event, is_spt) in enumerate(all_channels):
+        if is_spt:
+            channel_type = "DataChannelType_Blob"
+        elif is_event:
+            channel_type = "DataChannelType_Event"
+        else:
+            channel_type = "DataChannelType_Analog"
+        writer.write(f'      [{flat_index + 1}] "{channel_name}"  recorder="{recorder_name}"  type={channel_type}\n')
+    writer.write("   }\n")
+    writer.write("}\n")
+
+
+def _segment_range_start(s: PnrfSegment) -> float:
+    """Get the effective start time for sweep range calculation."""
+    if s._tag == "MATD" and s._matd_first_time is not None:
+        if s.sample_interval > 0 and s.start_time < s._matd_first_time - 1e-9:
+            return s.start_time
+        return s._matd_first_time
+    return s.start_time
+
+
+def _print_samples(channel: PnrfChannel, segment_index: int, offset: int, count: int, writer: TextIO) -> None:
+    """Print sample values for a segment."""
+    segment = channel.segments[segment_index]
+    try:
+        buffer = np.empty(count, dtype=np.float64)
+        n = channel.read_f64(buffer, segment_index=segment_index, start=offset, matd_interpolated=True)
+        for i in range(n):
+            idx = offset + i
+            t = segment.start_time + idx * segment.sample_interval
+            writer.write(f"                        [{idx:6}]  t={_format_value(t):>20}  y={_format_value(buffer[i]):>20}\n")
+    except Exception:
+        for i in range(count):
+            idx = offset + i
+            t = segment.start_time + idx * segment.sample_interval
+            writer.write(f"                        [{idx:6}]  t={_format_value(t):>20}  y={_format_value(0.0):>20}\n")
+
+
+def dump_file(path: str | Path, output: str | Path | None = None) -> None:
+    """Dump a PNRF file."""
+    path = Path(path)
+
+    if output:
+        out = open(output, "w", newline="")
+    else:
+        out = sys.stdout
+
+    try:
+        with PnrfFile.open(path) as pnrf:
+            dump(pnrf, out)
+    finally:
+        if output and out is not sys.stdout:
+            out.close()
+
+
+def main() -> None:
+    """Main entry point."""
+    if len(sys.argv) < 2:
+        print("Usage: python -m perception_pnrf.dump <pnrf_file> [output_file]", file=sys.stderr)
+        sys.exit(1)
+
+    path = sys.argv[1]
+    output = sys.argv[2] if len(sys.argv) > 2 else None
+    dump_file(path, output)
+
+
+if __name__ == "__main__":
+    main()

perception_pnrf/models.py

@@ -0,0 +1,288 @@
+# pyright: reportPrivateUsage=false
+
+"""Public model classes matching the C# PerceptionPnrf.Models namespace."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import IntEnum
+from typing import Any, Optional
+
+import numpy as np
+
+
+class MainframeRole(IntEnum):
+    """Synchronization role of a mainframe."""
+
+    UNSYNCHRONIZED = 0
+    MASTER = 1
+    SLAVE = 2
+
+
+class SegmentRelation(IntEnum):
+    """Relationship of a segment to the preceding one."""
+
+    NONE = 0
+    CONTINUOUS = 1
+
+
+class TriggerSource(IntEnum):
+    """Source that triggered an acquisition."""
+
+    INTERNAL = 0
+    EXTERNAL = 1
+    SOFTWARE = 2
+    MANUAL = 3
+
+
+class SampleEncoding(IntEnum):
+    """Sample encoding within the NSS container."""
+
+    INT16 = 0
+    INT32 = 1
+    FLOAT32 = 2
+    FLOAT64 = 3
+    MATD = 4
+    SPT = 5
+    INT64 = 6
+
+
+class GlobalMeta:
+    """Global metadata from RecordingInfo.xml and InfoData."""
+
+    def __init__(self) -> None:
+        self.title: Optional[str] = None
+        self.filename: str = ""
+        self.comment: Optional[str] = None
+        self.recording_start_utc: Optional[datetime] = None
+        self.data_values: dict[str, str] = {}
+
+        # Internal fields
+        self._mainframe_time_offsets: dict[str, float] = {}
+        self._mainframe_roles: dict[str, "MainframeRole"] = {}
+        self._recorder_names: dict[str, str] = {}
+        self._utc_start_frac_ticks: int = 0  # 100ns ticks for 7-digit sub-second precision
+
+    def __repr__(self) -> str:
+        return self.title or self.filename
+
+
+class PnrfSegment:
+    """A contiguous block of samples within a channel."""
+
+    def __init__(self) -> None:
+        self.start_time: float = 0.0
+        self.sample_interval: float = 0.0
+        self.sample_count: int = 0
+        self.source_encoding: SampleEncoding = SampleEncoding.INT16
+
+        # Internal fields (used by reader, not part of public API contract)
+        self._y0: float = 0.0
+        self._y_step: float = 1.0
+        self._relation: SegmentRelation = SegmentRelation.NONE
+        self._tag: str = ""
+        self._source_start_sector: int = 0
+        self._source_sample_offset: int = 0
+        self._source_size_bytes: int = 0
+        self._matd_first_time: Optional[float] = None
+        self._source_bit_index: int = -1
+
+    def __repr__(self) -> str:
+        return f"t={self.start_time}, n={self.sample_count}, dt={self.sample_interval}"
+
+
+class PnrfChannel:
+    """A measurement channel."""
+
+    def __init__(self) -> None:
+        self.physical_name: str = ""
+        self.logical_name: str = ""
+        self.units: str = ""
+        self.is_event: bool = False
+        self.is_spt: bool = False
+        self.segments: list[PnrfSegment] = []
+        self.recording_end_time: Optional[float] = None
+
+        # Internal wiring
+        self._owner: Optional[object] = None  # PnrfFile back-reference
+        self._owner_recorder: Optional[PnrfRecorder] = None
+        self._physical_index: int = 0
+        self._channel_type: int = 0
+        self._data_type_code: int = 0
+        self._tag: str = ""
+        self._alias_recorder_index: Optional[int] = None
+        self._alias_channel_index: Optional[int] = None
+        self._raw_segments: list[Any] = []
+
+    def __repr__(self) -> str:
+        return f"{self.logical_name} [{self.units}], {len(self.segments)} seg"
+
+    @property
+    def recorder(self) -> PnrfRecorder:
+        """The recorder this channel belongs to."""
+        assert self._owner_recorder is not None
+        return self._owner_recorder
+
+    @property
+    def sample_count(self) -> int:
+        """Total samples across all segments (computed)."""
+        return sum(s.sample_count for s in self.segments)
+
+    def read_f64(
+        self,
+        values: np.ndarray,
+        times: Optional[np.ndarray] = None,
+        segment_index: int = 0,
+        start: int = 0,
+        matd_interpolated: bool = False,
+    ) -> int:
+        """Read calibrated float64 samples.
+
+        Args:
+            values: Output array to fill with sample values.
+            times: Optional output array to fill with timestamps.
+            segment_index: Starting segment index.
+            start: Sample offset within the starting segment.
+            matd_interpolated: Use ZOH interpolation for MATD channels.
+
+        Returns:
+            Number of samples actually read.
+        """
+        from .pnrf import PnrfFile
+
+        assert isinstance(self._owner, PnrfFile)
+        return self._owner._read_channel(self, values, times, segment_index, start, matd_interpolated)
+
+    def read_f32(
+        self,
+        values: np.ndarray,
+        times: Optional[np.ndarray] = None,
+        segment_index: int = 0,
+        start: int = 0,
+        matd_interpolated: bool = False,
+    ) -> int:
+        """Read calibrated float32 samples.
+
+        Args:
+            values: Output array (float32) to fill with sample values.
+            times: Optional output array (float32) to fill with timestamps.
+            segment_index: Starting segment index.
+            start: Sample offset within the starting segment.
+            matd_interpolated: Use ZOH interpolation for MATD channels.
+
+        Returns:
+            Number of samples actually read.
+        """
+        from .pnrf import PnrfFile
+
+        assert isinstance(self._owner, PnrfFile)
+        return self._owner._read_channel_f32(self, values, times, segment_index, start, matd_interpolated)
+
+    def read_spt_frames(self, start: int = 0, count: Optional[int] = None) -> list[SptFrame]:
+        """Read SPT spectral frames."""
+        from .pnrf import PnrfFile
+
+        assert isinstance(self._owner, PnrfFile)
+        return self._owner._read_spt_frames(self, start, count)
+
+    def read_spt_harmonics(
+        self,
+        orders: Optional[list[int]] = None,
+        start: int = 0,
+        count: Optional[int] = None,
+        rms: bool = True,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Compute harmonic amplitudes from SPT frames.
+
+        Returns:
+            Tuple of (values, times) numpy arrays.
+        """
+        from .pnrf import PnrfFile
+
+        assert isinstance(self._owner, PnrfFile)
+        return self._owner._read_spt_harmonics(self, orders, start, count, rms)
+
+
+class PnrfRecorder:
+    """A recorder (data acquisition unit) containing channels."""
+
+    def __init__(self) -> None:
+        self.physical_name: str = ""
+        self.logical_name: str = ""
+        self.group: Optional[PnrfGroup] = None
+        self.mainframe_network_name: Optional[str] = None
+        self.mainframe_serial_number: Optional[str] = None
+        self.serial_number: Optional[str] = None
+        self.time_base_offset: float = 0.0
+        self.mainframe_role: MainframeRole = MainframeRole.UNSYNCHRONIZED
+        self.recording_end_time: Optional[float] = None
+        self.channels: list[PnrfChannel] = []
+        self.sweep_records: list[AcquisitionRecord] = []
+        self.continuous_records: list[AcquisitionRecord] = []
+        self.trigger_records: list[TriggerRecord] = []
+
+    def __repr__(self) -> str:
+        return f"{self.logical_name} ({self.physical_name}), {len(self.channels)} ch"
+
+
+class AcquisitionRecord:
+    """Sweep or continuous acquisition timing record."""
+
+    def __init__(self) -> None:
+        self.start_time: float = 0.0
+        self.sample_interval: float = 0.0
+        self.sample_count: int = 0
+        self.trigger_time: float = 0.0
+        self.trigger_source: TriggerSource = TriggerSource.INTERNAL
+
+    def __repr__(self) -> str:
+        return f"t={self.start_time}, n={self.sample_count}, dt={self.sample_interval}"
+
+
+class TriggerRecord:
+    """A trigger event record."""
+
+    def __init__(self) -> None:
+        self.time: float = 0.0
+        # Internal fields
+        self._channel_bitmask: int = 0
+        self._trigger_source: TriggerSource = TriggerSource.INTERNAL
+
+    def __repr__(self) -> str:
+        return f"t={self.time}"
+
+
+class PnrfGroup:
+    """A named group of recorders."""
+
+    def __init__(self, name: str = "") -> None:
+        self.name: str = name
+        self.recorders: list[PnrfRecorder] = []
+
+    def __repr__(self) -> str:
+        return f"{self.name}, {len(self.recorders)} recorders"
+
+    def get_recorder(self, name: str) -> Optional[PnrfRecorder]:
+        """Find recorder by logical or physical name (case-insensitive)."""
+        name_lower = name.lower()
+        for r in self.recorders:
+            if r.logical_name.lower() == name_lower or r.physical_name.lower() == name_lower:
+                return r
+        return None
+
+
+class SptFrame:
+    """Spectral (FFT) frame from SPT blob data."""
+
+    def __init__(self) -> None:
+        self.timestamp: float = 0.0
+        self.length: int = 0
+        self.fundamental_frequency: float = 0.0
+        self.frequency_bin_count_per_harmonic_order: int = 0
+        self.fundamental_phase: float = 0.0
+        self.frequency_bin_count_per_component: int = 0
+        self.real: np.ndarray = np.empty(0, dtype=np.float64)
+        self.imag: np.ndarray = np.empty(0, dtype=np.float64)
+
+    def __repr__(self) -> str:
+        return f"t={self.timestamp}, len={self.length}, f0={self.fundamental_frequency}"