# ADTF File Python Processor Plugin

This plugin enables the processing of data supported by the adtf_file library and additional plugins using **Python
scripts**. It acts as a bridge between the C++ `adtfdat_processing` framework and the Python runtime, allowing
developers to write custom exporters, analyzers, or data processors purely in Python without recompiling C++ code.

## Features

* **Embedded Python Interpreter:** Runs a dedicated Python environment within the ADTF processing pipeline.
* **Dynamic Script Loading:** Loads user-defined Python scripts at runtime via the `script` property.
* **Full Data Access:** Exposes ADTF streams, items, and samples to Python using `pybind11`.
* **Automatic Path handling:** Automatically adds the plugin's directory to `sys.path` to facilitate loading the
  `adtf_file` Python bindings.

## Configuration

The processor is registered with the identifier `python`.

### Properties

| Property | Type     | Description                                                                                                  |
|----------|----------|--------------------------------------------------------------------------------------------------------------|
| `script` | `String` | **Required.** The absolute or relative path to the Python script (`.py`) that contains the processing logic. |

## Python Script Interface

To use this processor, your Python script must implement the following two functions. The plugin expects the `adtf_file`
python module to be available.

### 1. `open(streams, destination_url)`

Called once at the beginning of the processing sequence.

* **`streams`**: A list of stream objects available in the source file. Each stream object contains metadata like
  `.name`, `.stream_id`, and `.initial_type`.
* **`destination_url`**: The target path/URL provided to the processor (e.g., for an output file).

### 2. `process(item)`

Called for every item found in the ADTF file (samples, stream type updates, events).

* **`item`**: The `adtf_file.FileItem` object.
* `item.type`: The type of item (e.g., `StreamType`, `Sample`).
* `item.stream_id`: The ID of the stream this item belongs to.
* `item.stream_type`: The stream type of the data (if `item.type` is `StreamType`).
* `item.sample`: The sample data (if `item.type` is `Sample`).

## Example Usage

Below is an example of a valid Python processor script (based on `demo_exporter.py`). This script iterates over streams,
initializes decoders, and prints sample data to the console.

```python
import adtf_file

print('Exporter module imported')

# Dictionary to hold decoders for each stream ID
sample_decoder = {}


def open(streams, destination_url):
    """
    Called during initialization.
    """
    global sample_decoder

    for stream in streams:
        print(f'Found stream: {stream.name} (ID: {stream.stream_id})')
        # Initialize a decoder using the stream's initial type
        sample_decoder[stream.stream_id] = adtf_file.SampleDecoder(stream.initial_type)


def process(item):
    """
    Called for every file item.
    """
    global sample_decoder

    # Update decoder if the stream type changes during recording
    if item.type == adtf_file.ItemType.StreamType:
        sample_decoder[item.stream_id] = adtf_file.SampleDecoder(item.stream_type)

    # Process actual data samples
    if item.type == adtf_file.ItemType.Sample:
        sample = item.sample

        # Decode the raw binary data into a usable structure
        decoder = sample_decoder.get(item.stream_id)
        decoded_data = decoder.decode(sample) if decoder else "No Decoder"

        print(f'Sample on Stream {item.stream_id}:')
        print(f'  Timestamp: {sample.time_stamp}')
        print(f'  Data: {decoded_data}')

```
