Metadata-Version: 2.4
Name: listmode-parser
Version: 0.1.0
Summary: Dependency-free metadata parser for Siemens listmode raw tail DICOM headers.
Author: Edinburgh Imaging IT
Maintainer: Edinburgh Imaging IT
License-Expression: MIT
Project-URL: Homepage, https://github.com/tomesparon/listmode-parser
Project-URL: Repository, https://github.com/tomesparon/listmode-parser
Project-URL: Issues, https://github.com/tomesparon/listmode-parser/issues
Keywords: pet,ct,listmode,siemens,dicom,metadata,raw-data
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# listmode-parser

Dependency-free Python parser for metadata embedded near the tail of Siemens listmode/raw files such as `.ptr` and `.ptd`.

Tested with Siemens listmode/raw files from:

- Siemens NAEOTOM Alpha
- Siemens Biograph 128
- Siemens Biograph Vision Quadra

- read tail ranges of `64 KiB`, `384 KiB`, then `1 MiB`
- find the embedded `DICM` marker used by the raw tail metadata
- parse explicit VR little-endian DICOM elements
- expose all parseable top-level tags, not only PatientID

## Install

```powershell
pip install listmode-parser
```

## Library Use

```python
from listmode_parser import build_sidecar, get_patient_id, read_metadata_dict, write_sidecar

path = r"C:\path\file.ptd"

metadata = read_metadata_dict(path)
patient_id = get_patient_id(path)
sidecar_payload = build_sidecar(path)
sidecar_path = write_sidecar(path)

print(patient_id)
print(metadata["0010,0020"]["value"])
print(sidecar_payload["source"]["name"])
print(sidecar_path)
```

## CLI Use

```powershell
listmode-parser C:\path\file.ptd --tag 0010,0020
listmode-parser C:\path\file.ptd --patient-id
listmode-parser C:\path\file.ptd --json
listmode-parser C:\path\file.ptd --sidecar
listmode-parser C:\path\file.ptd --sidecar --out C:\metadata\file.ptd.metadata.json
```

The same CLI is available through the module entry point:

```powershell
python -m listmode_parser C:\path\file.ptr --json
```

## Limitations

This is a tail-DICOM metadata reader for Siemens listmode/raw files. It is not a full DICOM parser, reconstruction tool, or anonymisation tool.

Sidecar export writes JSON metadata only. It does not modify or anonymise the source raw file.

Flywheel's `fw-file` can extract some similar metadata, but it does not currently cover CT raw files.
