Metadata-Version: 2.4
Name: perception-pnrf
Version: 1.1.0
Summary: A Perception PNRF binary file reader.
Home-page: https://codeberg.org/Apollo3zehn
Author: https://codeberg.org/Apollo3zehn
License: MIT
Project-URL: Project, https://codeberg.org/Apollo3zehn/perception-pnrf
Project-URL: Repository, https://codeberg.org/Apollo3zehn/perception-pnrf
Keywords: Perception HBM HBK PNRF reader
Platform: any
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.4.6
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: platform
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# perception-pnrf

Python parser for the **PNRF** binary measurement format (HBK Perception).

PNRF files (`.pnrf`) are produced by [HBK Perception](https://www.hbkworld.com/en/products/software/data-acquisition/perception) data acquisition software and contain high-speed analog waveforms, digital events, CAN/fieldbus data, and SPT harmonic analysis results.

## Installation

```bash
pip install perception-pnrf
```

Requires Python 3.10+ and NumPy.

## Usage

```python
from perception_pnrf import PnrfFile

# Open a PNRF file
with PnrfFile.open("measurement.pnrf") as pnrf:
    # Iterate recorders and channels
    for rec in pnrf.recorders:
        print(f"Recorder: {rec.logical_name}")
        for ch in rec.channels:
            print(f"  {ch.logical_name}: {ch.sample_count} samples, unit={ch.units}")

            # Read sample data into a NumPy buffer
            data = np.empty(min(ch.sample_count, 1000), dtype=np.float64)
            count = ch.read_f64(data)
            print(f"  Read {count} samples")
```

### Key Classes

| Class | Description |
|-------|-------------|
| `PnrfFile` | Top-level file handle; provides `.recorders`, `.groups`, `.metadata` |
| `PnrfRecorder` | A data acquisition module with channels |
| `PnrfChannel` | A measurement channel with metadata and data access |
| `PnrfGroup` | Logical grouping of recorders |

### Reading Data

```python
import numpy as np

# Read a slice of samples into a preallocated buffer
values = np.empty(5000, dtype=np.float64)
count = ch.read_f64(values, start=0)

# Read all samples at once
all_values = np.empty(ch.sample_count, dtype=np.float64)
count = ch.read_f64(all_values)

# Read from a specific segment with a starting offset
segment_values = np.empty(100, dtype=np.float64)
count = ch.read_f64(segment_values, segment_index=0, start=0)
```

### Channel Types

- **Analog waveform** — continuous or sweep-triggered time-series data
- **Digital event** — binary state channels
- **SPT blob** — Signal Processing Toolkit results (harmonics, order tracking)
- **MATD** — asynchronous sparse-pair data (CAN bus, fieldbus)

### File Metadata

```python
meta = pnrf.metadata
print(meta.title, meta.comment)
if meta.recording_start_utc is not None:
    print(meta.recording_start_utc.isoformat())
```

## Dump Tool

A CLI tool is included for inspecting PNRF files:

```bash
pnrf-dump recording.pnrf
```

Or via module invocation:

```bash
python -m perception_pnrf.dump recording.pnrf
```

Produces a structured text dump showing file metadata, recorder/channel hierarchy, segment boundaries, and sample previews.

## Specification

The full reverse-engineered format specification is available in the [spec/ directory](https://codeberg.org/Apollo3zehn/perception-pnrf/src/branch/main/spec) of the source repository.

## License

MIT
