dicomwf 0.3.0__tar.gz

dicomwf-0.3.0/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Inria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

dicomwf-0.3.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: dicomwf
+Version: 0.3.0
+Summary: A Python library for creating DICOM EEG waveform files
+Author: Clément Chesnin
+Author-email: Evgenia Kartsaki <evgenia.kartsaki@inria.fr>, Thomas Prampart <thomas.prampart@inria.fr>, Michael Kain <michael.kain@inria.fr>, Eric Poiseau <eric.poiseau@inria.fr>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.inria.fr/openvibe/dicomwf
+Project-URL: Repository, https://gitlab.inria.fr/openvibe/dicomwf
+Keywords: dicom,eeg,waveform,medical,imaging
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: ==3.11.*
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pydicom>=2.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: mne>=1.11.0; extra == "dev"
+Requires-Dist: build>=1.4.0; extra == "dev"
+Requires-Dist: twine>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# dicomwf
+
+A Python library for integrating waveforms in DICOM files.
+
+## Features
+
+Supported waveforms IODs:
+- RoutineScalpEEG
+
+## Installation
+
+### User Installation
+
+Install directly from PyPI:
+
+```bash
+pip install dicomwf
+```
+
+### Developer Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://gitlab.inria.fr/openvibe/dicomwf.git
+cd dicomwf
+```
+
+2. Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+
+# On Windows
+.venv\Scripts\activate
+
+# On Unix/macOS
+source .venv/bin/activate
+```
+
+3. Install in editable mode with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+This installs the package in editable mode along with development tools.
+
+## Quick Start
+
+We will use the EEG data in the edf format from the [EEGBCI dataset](https://doi.org/10.1109/TBME.2004.827072). 
+
+```python
+import numpy as np
+from dicomwf import *
+from urllib.request import urlretrieve
+import mne
+
+# Load EEG data
+url = "https://physionet.org/files/eegmmidb/1.0.0/S001/S001R01.edf?download"
+raw_fname = "S001R01.edf"
+urlretrieve(url, raw_fname)
+
+raw = mne.io.read_raw_edf(raw_fname, preload=True)
+
+# Create DICOM EEG
+dicom_eeg_data = RoutineScalpEEGData(
+    patient=Patient(name="Doe^John", birth_date="20250101", sex="M"),
+    study=GeneralStudy(id="1",date="19940423", time="101601.934000", accession_number="1"),
+    equipment=GeneralEquipment(
+        manufacturer="PyDICOM",
+        manufacturer_model_name="PyDICOM",
+        device_serial_number="1",
+        software_versions="1.0",
+    ),
+    waveform_identification=WaveformIdentification(),
+    waveform=Waveform(
+        channel_count=raw.info["nchan"],
+        sampling_frequency=raw.info["sfreq"],
+        channel_names=raw.ch_names,
+        data=np.transpose(raw.get_data()),
+    ),
+)
+
+dicom_eeg = RoutineScalpEEG(uid_root="1.2.3.4.5.", rse_data=dicom_eeg_data)
+dicom_eeg.save_as("output.dcm")
+```
+
+## Dependencies
+
+**Required:**
+- numpy >= 1.20.0
+- pydicom >= 2.3.0
+
+**Optional (for development):**
+- pytest >= 7.0.0
+- mne>=1.11.0
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+
+## Authors
+
+- Evgenia Kartsaki
+- Thomas Prampart
+- Michael Kain
+- Eric Poiseau
+- Clement Chesnin
+
+## Data Sources
+This project uses the following data for unit testing:
+* **[EEG Motor Movement/Imagery Dataset]**: Sourced from [https://physionet.org/content/eegmmidb/1.0.0/S001/].
+* **License**: This data is licensed under the [Open Data Commons Attribution License (ODC-By) v1.0](https://physionet.org/content/eegmmidb/view-license/1.0.0/).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

dicomwf-0.3.0/README.md

@@ -0,0 +1,124 @@
+# dicomwf
+
+A Python library for integrating waveforms in DICOM files.
+
+## Features
+
+Supported waveforms IODs:
+- RoutineScalpEEG
+
+## Installation
+
+### User Installation
+
+Install directly from PyPI:
+
+```bash
+pip install dicomwf
+```
+
+### Developer Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://gitlab.inria.fr/openvibe/dicomwf.git
+cd dicomwf
+```
+
+2. Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+
+# On Windows
+.venv\Scripts\activate
+
+# On Unix/macOS
+source .venv/bin/activate
+```
+
+3. Install in editable mode with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+This installs the package in editable mode along with development tools.
+
+## Quick Start
+
+We will use the EEG data in the edf format from the [EEGBCI dataset](https://doi.org/10.1109/TBME.2004.827072). 
+
+```python
+import numpy as np
+from dicomwf import *
+from urllib.request import urlretrieve
+import mne
+
+# Load EEG data
+url = "https://physionet.org/files/eegmmidb/1.0.0/S001/S001R01.edf?download"
+raw_fname = "S001R01.edf"
+urlretrieve(url, raw_fname)
+
+raw = mne.io.read_raw_edf(raw_fname, preload=True)
+
+# Create DICOM EEG
+dicom_eeg_data = RoutineScalpEEGData(
+    patient=Patient(name="Doe^John", birth_date="20250101", sex="M"),
+    study=GeneralStudy(id="1",date="19940423", time="101601.934000", accession_number="1"),
+    equipment=GeneralEquipment(
+        manufacturer="PyDICOM",
+        manufacturer_model_name="PyDICOM",
+        device_serial_number="1",
+        software_versions="1.0",
+    ),
+    waveform_identification=WaveformIdentification(),
+    waveform=Waveform(
+        channel_count=raw.info["nchan"],
+        sampling_frequency=raw.info["sfreq"],
+        channel_names=raw.ch_names,
+        data=np.transpose(raw.get_data()),
+    ),
+)
+
+dicom_eeg = RoutineScalpEEG(uid_root="1.2.3.4.5.", rse_data=dicom_eeg_data)
+dicom_eeg.save_as("output.dcm")
+```
+
+## Dependencies
+
+**Required:**
+- numpy >= 1.20.0
+- pydicom >= 2.3.0
+
+**Optional (for development):**
+- pytest >= 7.0.0
+- mne>=1.11.0
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+
+## Authors
+
+- Evgenia Kartsaki
+- Thomas Prampart
+- Michael Kain
+- Eric Poiseau
+- Clement Chesnin
+
+## Data Sources
+This project uses the following data for unit testing:
+* **[EEG Motor Movement/Imagery Dataset]**: Sourced from [https://physionet.org/content/eegmmidb/1.0.0/S001/].
+* **License**: This data is licensed under the [Open Data Commons Attribution License (ODC-By) v1.0](https://physionet.org/content/eegmmidb/view-license/1.0.0/).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

dicomwf-0.3.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dicomwf"
+version = "0.3.0" # will be replaced by CI
+description = "A Python library for creating DICOM EEG waveform files"
+readme = "README.md"
+requires-python = "==3.11.*"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [
+    {name = "Evgenia Kartsaki",  email = "evgenia.kartsaki@inria.fr"},
+    {name = "Thomas Prampart", email = "thomas.prampart@inria.fr"},
+    {name = "Michael Kain",    email = "michael.kain@inria.fr"},
+    {name = "Eric Poiseau",    email = "eric.poiseau@inria.fr"},
+    {name = "Clément Chesnin"},
+]
+keywords = ["dicom", "eeg", "waveform", "medical", "imaging"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Science/Research",
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Software Development :: Libraries"
+]
+
+dependencies = [
+    "numpy>=1.20.0",
+    "pydicom>=2.3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "mne>=1.11.0",
+    "build>=1.4.0",
+    "twine>=6.0.0",
+]
+
+[project.urls]
+Homepage = "https://gitlab.inria.fr/openvibe/dicomwf"
+Repository = "https://gitlab.inria.fr/openvibe/dicomwf"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dicomwf = ["py.typed"]

dicomwf-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dicomwf-0.3.0/src/dicomwf/__init__.py

@@ -0,0 +1,20 @@
+from .routinescalp import RoutineScalpEEG
+from .data import (
+    RoutineScalpEEGData,
+    GeneralEquipment,
+    Patient,
+    GeneralStudy,
+    Waveform,
+    WaveformIdentification,
+)
+
+__all__ = [
+    "RoutineScalpEEG",
+    "RoutineScalpEEGData",
+    "GeneralEquipment",
+    "Patient",
+    "GeneralStudy",
+    "Waveform",
+    "WaveformIdentification",
+]
+

dicomwf-0.3.0/src/dicomwf/data.py

@@ -0,0 +1,116 @@
+"""Data classes for DICOM Routine Scalp EEG waveform storage.
+
+Defines the structured data containers used to populate a DICOM
+Routine Scalp Electroencephalogram (EEG) Waveform object.
+"""
+
+import datetime
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class Patient:
+    """DICOM Patient module.
+
+    Attributes:
+        name: Patient's full name, using '^' as a separator (e.g. 'Doe^John') (DICOM keyword PatientName).
+        birth_date: Birth date (DICOM keyword PatientBirthDate) in DA format (YYYYMMDD).
+        sex: Patient sex — ``M``, ``F``, or ``O`` (DICOM keyword PatientSex).
+        id: Patient primary identifier. Defaults to ``name`` if not provided (DICOM keyword PatientID).
+    """
+
+    name: str
+    birth_date: str
+    sex: str
+    id: str | None = None
+
+    def __post_init__(self):
+        if self.id is None:
+            self.id = self.name
+
+
+@dataclass
+class GeneralStudy:
+    """DICOM General Study module.
+
+    Attributes:
+        id: Study identifier (DICOM keyword StudyID).
+        date: Date the study started (DICOM keyword StudyDate) in DICOM DA format (YYYYMMDD).
+        time: Time the study started (DICOM keyword StudyTime) in DICOM TM format (HHMMSS.FFFFFF).
+        accession_number: A departmental Information System generated number that identifies the Imaging Service Request (DICOM keyword AccessionNumber).
+    """
+
+    id: str
+    date: str
+    time: str
+    accession_number: str
+
+
+@dataclass
+class GeneralEquipment:
+    """DICOM Enhanced General Equipment module.
+
+    Attributes:
+        manufacturer: Equipment manufacturer name (DICOM keyword Manufacturer).
+        manufacturer_model_name: Manufacturer's model name of the equipment (DICOM keyword ManufacturerModelName).
+        device_serial_number: Manufacturer's serial number of the equipment (DICOM keyword DeviceSerialNumber).
+        software_versions: Manufacturer's designation of software version of the equipment (DICOM keyword SoftwareVersions).
+    """
+
+    manufacturer: str
+    manufacturer_model_name: str
+    device_serial_number: str
+    software_versions: str
+
+
+@dataclass
+class WaveformIdentification:
+    """DICOM Waveform Identification module.
+
+    Attributes:
+        content_date_time: Date/time the content was created.
+        acquisition_date_time: Date/time that the acquisition of data that resulted in this waveform started (DICOM keyword AcquisitionDateTime).
+        instance_number: A number that identifies this waveform (DICOM keyword InstanceNumber). Defaults to "1".
+    """
+
+    content_date_time: datetime.datetime = datetime.datetime.now()
+    acquisition_date_time: datetime.datetime = datetime.datetime.now()
+    instance_number: str = "1"
+
+
+@dataclass
+class Waveform:
+    """EEG waveform data and metadata. Not a direct mapping to a DICOM module, but used to populate the Waveform Sequence and Channel Definition Sequence.
+
+    Attributes:
+        channel_count: Number of EEG channels.
+        sampling_frequency: Sampling frequency in Hz.
+        channel_names: Ordered list of channel labels.
+        data: NumPy array of shape ``(samples, channels)`` holding the signal values.
+    """
+
+    channel_count: int
+    sampling_frequency: float
+    channel_names: list[str]
+    data: np.ndarray
+
+
+@dataclass
+class RoutineScalpEEGData:
+    """Aggregates all data needed to build a Routine Scalp EEG DICOM object.
+
+    Attributes:
+        patient: Patient module.
+        study: Study module.
+        equipment: Equipment module.
+        waveform_identification: Waveform Identification module.
+        waveform: The EEG signal data and channel metadata.
+    """
+
+    patient: Patient
+    study: GeneralStudy
+    equipment: GeneralEquipment
+    waveform_identification: WaveformIdentification
+    waveform: Waveform

dicomwf-0.3.0/src/dicomwf/routinescalp.py

@@ -0,0 +1,233 @@
+"""Builder for DICOM Routine Scalp EEG Waveform Storage objects.
+
+Constructs a complete DICOM dataset conforming to the Routine Scalp
+Electroencephalogram Waveform IOD (SOP Class 1.2.840.10008.5.1.4.1.1.9.1.2).
+"""
+
+import numpy as np
+import pydicom
+from pydicom.dataset import Dataset, FileMetaDataset
+from pydicom.uid import UID, ExplicitVRLittleEndian, ImplicitVRLittleEndian
+from typing import Tuple
+
+from dicomwf.data import (
+    Patient,
+    GeneralStudy,
+    GeneralEquipment,
+    WaveformIdentification,
+    Waveform,
+    RoutineScalpEEGData,
+)
+
+
+class RoutineScalpEEG:
+    """Builds and saves a DICOM Routine Scalp EEG Waveform dataset.
+
+    The constructor populates every required DICOM module from a
+    ``RoutineScalpEEGData`` instance.  Call ``save_as`` to write the
+    result to disk.
+
+    Attributes:
+        ds: A DICOM dataset as a mutable mapping of DICOM Data Elements.
+        sop_class_uid: SOP Class UID for Routine Scalp EEG Waveform Storage.
+        uid_root: Organisation UID root used to derive all generated UIDs.
+        sop_instance_uid: Unique identifier for this SOP instance.
+        implementation_class_uid: Implementation Class UID written to file meta.
+    """
+
+    def __init__(
+        self,
+        uid_root: str,
+        rse_data: RoutineScalpEEGData,
+    ):
+        """Initialise the dataset and populate all DICOM modules.
+
+        Args:
+            uid_root: Organisation-specific UID prefix used when generating
+                DICOM UIDs (Study, Series, SOP Instance).
+            rse_data: Structured container holding patient, study, equipment,
+                waveform identification, and waveform data.
+        """
+        self.ds = Dataset()
+        self.sop_class_uid = pydicom.uid.RoutineScalpElectroencephalogramWaveformStorage
+        self.uid_root = uid_root
+        self.sop_instance_uid = pydicom.uid.generate_uid(prefix=self.uid_root)
+        self.implementation_class_uid = UID("1.2.3.4")
+
+        self._build_metadata()
+        self._build_patient(rse_data.patient)
+        self._build_study(rse_data.study)
+        self._build_series()
+        self._build_enhanced_general_equipment(rse_data.equipment)
+        self._build_waveform_identification(rse_data.waveform_identification)
+        self._build_waveform(rse_data.waveform)
+
+    def _build_metadata(self):
+        """Populate the DICOM File Meta Information header."""
+        file_meta = FileMetaDataset()
+        file_meta.MediaStorageSOPClassUID = self.sop_class_uid
+        file_meta.MediaStorageSOPInstanceUID = self.sop_instance_uid
+        file_meta.ImplementationClassUID = self.implementation_class_uid
+        file_meta.TransferSyntaxUID = ExplicitVRLittleEndian
+        self.ds.file_meta = file_meta
+
+    def _build_patient(self, patient: Patient):
+        """Populate the Patient module attributes."""
+        self.ds.PatientName = patient.name
+        self.ds.PatientID = patient.id
+        self.ds.PatientBirthDate = patient.birth_date
+        self.ds.PatientSex = patient.sex
+
+    def _build_study(self, study: GeneralStudy):
+        """Populate the General Study module attributes."""
+        self.ds.StudyDate = study.date
+        self.ds.StudyTime = study.time
+        self.ds.AccessionNumber = study.accession_number
+        self.ds.ReferringPhysicianName = ""
+        self.ds.StudyInstanceUID = pydicom.uid.generate_uid(prefix=self.uid_root)
+        self.ds.StudyID = study.id
+
+    def _build_series(self):
+        """Populate the General Series module (modality fixed to EEG)."""
+        self.ds.Modality = "EEG"
+        self.ds.SeriesInstanceUID = pydicom.uid.generate_uid(prefix=self.uid_root)
+        self.ds.SeriesNumber = "1"
+
+    def _build_enhanced_general_equipment(self, equipment: GeneralEquipment):
+        """Populate the Enhanced General Equipment module attributes."""
+        self.ds.Manufacturer = equipment.manufacturer
+        self.ds.ManufacturerModelName = equipment.manufacturer_model_name
+        self.ds.DeviceSerialNumber = equipment.device_serial_number
+        self.ds.SoftwareVersions = equipment.software_versions
+
+    def _build_waveform_identification(self, identification: WaveformIdentification):
+        """Populate the Waveform Identification module (content and acquisition timestamps)."""
+        self.ds.ContentDate = identification.content_date_time.strftime("%Y%m%d")
+        self.ds.ContentTime = identification.content_date_time.strftime("%H%M%S.%f")
+        self.ds.AcquisitionDateTime = identification.acquisition_date_time.strftime(
+            "%Y%m%d%H%M%S.%f"
+        )
+        self.ds.InstanceNumber = identification.instance_number
+
+    def _build_channel_definition_sequence(
+        self,
+        channel_name: str,
+        factor: float,
+        offset: float,
+    ):
+        """Build a single Channel Definition Sequence item.
+
+        Args:
+            channel_name: Human-readable label for the channel (stored as
+                ``CodeMeaning`` in the Channel Source Sequence).
+            factor: Scaling factor (``ChannelSensitivity``) used to convert
+                stored integer values back to real-world units.
+            offset: Baseline offset (``ChannelBaseline``) added after scaling.
+
+        Returns:
+            A ``pydicom.Dataset`` representing one channel definition.
+        """
+        channel_definition = Dataset()
+        channel_definition.ChannelSampleSkew = "0"
+        channel_definition.ChannelSensitivity = f"{factor:.10g}"
+        channel_definition.ChannelBaseline = f"{offset:.10g}"
+        channel_definition.WaveformBitsStored = 64
+        channel_definition.ChannelSourceSequence = [Dataset()]
+        source = channel_definition.ChannelSourceSequence[0]
+        source.CodeValue = "1.0"
+        source.CodingSchemeDesignator = "PYDICOM"
+        source.CodingSchemeVersion = "1.0"
+        source.CodeMeaning = channel_name
+
+        return channel_definition
+
+    def quantize_to_int64(self, data: np.ndarray) -> Tuple[np.ndarray, np.float64, np.float64]:
+        """Linearly quantize floating-point waveform data to signed 64-bit integers.
+
+        The input range ``[min, max]`` is mapped to ``[0, 2**31 - 1]`` so
+        the original values can be reconstructed as
+        ``value = stored * factor + offset``.
+
+        Args:
+            data: Array of floating-point samples to quantize.
+
+        Returns:
+            A tuple of ``(quantized_data, factor, offset)`` where
+            *quantized_data* is an ``int64`` C-contiguous array, *factor*
+            is the scaling multiplier, and *offset* is the baseline value.
+        """
+        min, max = data.min(), data.max()
+
+        offset = min
+
+        target_range = 2**31 - 1
+        factor = (max - min) / target_range if min != max else 1.0
+
+        quantized_data = np.round((data - offset) / factor).astype(np.int64).copy(order="C")
+        return quantized_data, factor, offset
+
+    def _build_waveform_sequence(
+        self,
+        channel_count: int,
+        sampling_frequency: float,
+        channel_names: list[str],
+        data: np.ndarray,
+    ):
+        """Build a single Waveform Sequence item containing all channels.
+
+        The floating-point signal data is quantized to ``int64`` via
+        ``quantize_to_int64`` and a ``ChannelDefinitionSequence`` is
+        created with the corresponding sensitivity/baseline values.
+
+        Args:
+            channel_count: Number of channels in the waveform.
+            sampling_frequency: Sampling frequency in Hz.
+            channel_names: Ordered list of channel labels.
+            data: Array of shape ``(samples, channels)`` with signal values.
+
+        Returns:
+            A ``pydicom.Dataset`` representing one Waveform Sequence item.
+        """
+        new = Dataset()
+        new.WaveformOriginality = "ORIGINAL"
+        new.NumberOfWaveformChannels = channel_count
+        new.NumberOfWaveformSamples = data.shape[0]
+        new.SamplingFrequency = sampling_frequency
+
+        quantized_data, factor, offset = self.quantize_to_int64(data)
+
+        new.ChannelDefinitionSequence = []
+        for i in range(channel_count):
+            new.ChannelDefinitionSequence.append(
+                self._build_channel_definition_sequence(channel_names[i], factor, offset)
+            )
+
+        new.WaveformBitsAllocated = 64
+        new.WaveformSampleInterpretation = "SV"
+        new.WaveformData = quantized_data
+
+        return new
+
+    def _build_waveform(
+        self,
+        waveform: Waveform,
+    ):
+        """Populate the SOP Common module and the Waveform Sequence."""
+        self.ds.SOPInstanceUID = self.sop_instance_uid
+        self.ds.SOPClassUID = self.sop_class_uid
+        self.ds.WaveformSequence = [
+            self._build_waveform_sequence(
+                waveform.channel_count,
+                waveform.sampling_frequency,
+                waveform.channel_names,
+                waveform.data,
+            )
+        ]
+
+    def save_as(self, filename: str):
+        """Write the DICOM dataset to a file.
+
+        Args:
+            filename: Destination file path.
+        """
+        self.ds.save_as(filename, enforce_file_format=True)

dicomwf-0.3.0/src/dicomwf.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: dicomwf
+Version: 0.3.0
+Summary: A Python library for creating DICOM EEG waveform files
+Author: Clément Chesnin
+Author-email: Evgenia Kartsaki <evgenia.kartsaki@inria.fr>, Thomas Prampart <thomas.prampart@inria.fr>, Michael Kain <michael.kain@inria.fr>, Eric Poiseau <eric.poiseau@inria.fr>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.inria.fr/openvibe/dicomwf
+Project-URL: Repository, https://gitlab.inria.fr/openvibe/dicomwf
+Keywords: dicom,eeg,waveform,medical,imaging
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: ==3.11.*
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pydicom>=2.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: mne>=1.11.0; extra == "dev"
+Requires-Dist: build>=1.4.0; extra == "dev"
+Requires-Dist: twine>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# dicomwf
+
+A Python library for integrating waveforms in DICOM files.
+
+## Features
+
+Supported waveforms IODs:
+- RoutineScalpEEG
+
+## Installation
+
+### User Installation
+
+Install directly from PyPI:
+
+```bash
+pip install dicomwf
+```
+
+### Developer Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://gitlab.inria.fr/openvibe/dicomwf.git
+cd dicomwf
+```
+
+2. Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+
+# On Windows
+.venv\Scripts\activate
+
+# On Unix/macOS
+source .venv/bin/activate
+```
+
+3. Install in editable mode with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+This installs the package in editable mode along with development tools.
+
+## Quick Start
+
+We will use the EEG data in the edf format from the [EEGBCI dataset](https://doi.org/10.1109/TBME.2004.827072). 
+
+```python
+import numpy as np
+from dicomwf import *
+from urllib.request import urlretrieve
+import mne
+
+# Load EEG data
+url = "https://physionet.org/files/eegmmidb/1.0.0/S001/S001R01.edf?download"
+raw_fname = "S001R01.edf"
+urlretrieve(url, raw_fname)
+
+raw = mne.io.read_raw_edf(raw_fname, preload=True)
+
+# Create DICOM EEG
+dicom_eeg_data = RoutineScalpEEGData(
+    patient=Patient(name="Doe^John", birth_date="20250101", sex="M"),
+    study=GeneralStudy(id="1",date="19940423", time="101601.934000", accession_number="1"),
+    equipment=GeneralEquipment(
+        manufacturer="PyDICOM",
+        manufacturer_model_name="PyDICOM",
+        device_serial_number="1",
+        software_versions="1.0",
+    ),
+    waveform_identification=WaveformIdentification(),
+    waveform=Waveform(
+        channel_count=raw.info["nchan"],
+        sampling_frequency=raw.info["sfreq"],
+        channel_names=raw.ch_names,
+        data=np.transpose(raw.get_data()),
+    ),
+)
+
+dicom_eeg = RoutineScalpEEG(uid_root="1.2.3.4.5.", rse_data=dicom_eeg_data)
+dicom_eeg.save_as("output.dcm")
+```
+
+## Dependencies
+
+**Required:**
+- numpy >= 1.20.0
+- pydicom >= 2.3.0
+
+**Optional (for development):**
+- pytest >= 7.0.0
+- mne>=1.11.0
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+
+## Authors
+
+- Evgenia Kartsaki
+- Thomas Prampart
+- Michael Kain
+- Eric Poiseau
+- Clement Chesnin
+
+## Data Sources
+This project uses the following data for unit testing:
+* **[EEG Motor Movement/Imagery Dataset]**: Sourced from [https://physionet.org/content/eegmmidb/1.0.0/S001/].
+* **License**: This data is licensed under the [Open Data Commons Attribution License (ODC-By) v1.0](https://physionet.org/content/eegmmidb/view-license/1.0.0/).
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

dicomwf-0.3.0/src/dicomwf.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE.md
+README.md
+pyproject.toml
+src/dicomwf/__init__.py
+src/dicomwf/data.py
+src/dicomwf/routinescalp.py
+src/dicomwf.egg-info/PKG-INFO
+src/dicomwf.egg-info/SOURCES.txt
+src/dicomwf.egg-info/dependency_links.txt
+src/dicomwf.egg-info/requires.txt
+src/dicomwf.egg-info/top_level.txt
+tests/test_routinescalp.py
+tests/test_routinescalp_unit.py

dicomwf-0.3.0/src/dicomwf.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dicomwf-0.3.0/src/dicomwf.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy>=1.20.0
+pydicom>=2.3.0
+
+[dev]
+pytest>=7.0.0
+mne>=1.11.0
+build>=1.4.0
+twine>=6.0.0

dicomwf-0.3.0/src/dicomwf.egg-info/top_level.txt

@@ -0,0 +1 @@
+dicomwf

dicomwf-0.3.0/tests/test_routinescalp.py

@@ -0,0 +1,78 @@
+import pytest
+
+import mne
+import numpy as np
+import pydicom
+
+from dicomwf import *
+from urllib.request import urlretrieve
+
+def test_routinescalp():
+
+    # Load EEG data
+    url = "https://physionet.org/files/eegmmidb/1.0.0/S001/S001R01.edf?download"
+    raw_fname = "S001R01.edf"
+    urlretrieve(url, raw_fname)
+
+    raw = mne.io.read_raw_edf(raw_fname, preload=True)
+
+    # Create a DICOM EEG
+    dicom_eeg_data = RoutineScalpEEGData(
+        patient=Patient(name="John^Doe", birth_date="20250101", sex="M"),
+        study=GeneralStudy(
+            date="19940423", time="101601.934000", accession_number="1", id="847542"
+        ),
+        equipment=GeneralEquipment(
+            manufacturer="PyDICOM",
+            manufacturer_model_name="PyDICOM",
+            device_serial_number="1",
+            software_versions="1.0",
+        ),
+        waveform_identification=WaveformIdentification(),
+        waveform=Waveform(
+            channel_count=raw.info["nchan"],
+            sampling_frequency=raw.info["sfreq"],
+            channel_names=raw.ch_names,
+            data=np.transpose(raw.get_data()),
+        ),
+    )
+
+    dicom_eeg = RoutineScalpEEG(uid_root="1.2.3.4.5.", rse_data=dicom_eeg_data)
+    dicom_eeg.save_as("toto.dcm")
+
+    pydicom_eeg = pydicom.dcmread("toto.dcm")
+    assert pydicom_eeg.Modality == "EEG"
+    assert pydicom_eeg.PatientName == "John^Doe"
+    assert pydicom_eeg.PatientBirthDate == "20250101"
+    assert pydicom_eeg.PatientSex == "M"
+    assert pydicom_eeg.PatientID == "John^Doe"
+    assert pydicom_eeg.AccessionNumber == "1"
+    assert pydicom_eeg.StudyDate == "19940423"
+    assert pydicom_eeg.StudyTime == "101601.934000"
+    assert pydicom_eeg.StudyID == "847542"
+    assert pydicom_eeg.Manufacturer == "PyDICOM"
+    assert pydicom_eeg.ManufacturerModelName == "PyDICOM"
+    assert pydicom_eeg.DeviceSerialNumber == "1"
+    assert pydicom_eeg.SoftwareVersions == "1.0"
+
+    assert len(pydicom_eeg.WaveformSequence) == 1
+    waveform = pydicom_eeg.WaveformSequence[0]
+    assert waveform.NumberOfWaveformChannels == raw.info["nchan"]
+    assert waveform.SamplingFrequency == raw.info["sfreq"]
+
+    
+    assert len(waveform.ChannelDefinitionSequence) == raw.info["nchan"]
+    factor = waveform.ChannelDefinitionSequence[0].ChannelSensitivity
+    offset = waveform.ChannelDefinitionSequence[0].ChannelBaseline
+
+    for i in range(raw.info["nchan"]):
+        assert waveform.ChannelDefinitionSequence[i].ChannelSourceSequence[0].CodeMeaning == raw.ch_names[i]
+    
+    print(len(waveform.WaveformData))
+
+    data = np.frombuffer(waveform.WaveformData, dtype=np.int64)
+    assert len(data) == raw.info["nchan"] * raw.n_times
+
+    data = np.reshape(data, (raw.n_times, raw.info["nchan"]))
+    data = np.transpose(data * factor + offset)
+    assert np.allclose(data, raw.get_data(), atol=1e-6)

dicomwf-0.3.0/tests/test_routinescalp_unit.py

@@ -0,0 +1,154 @@
+import tempfile
+import os
+
+import pytest
+import numpy as np
+import pydicom
+from pydicom.uid import ExplicitVRLittleEndian
+
+from dicomwf.routinescalp import RoutineScalpEEG
+from dicomwf.data import Patient
+
+
+class TestRoutineScalpEEG:
+
+    def test_init(self, sample_rse_data):
+        # Test uid_root is stored
+        eeg = RoutineScalpEEG(uid_root="9.8.7.6.5.", rse_data=sample_rse_data)
+        assert eeg.uid_root == "9.8.7.6.5."
+
+        # Test sop_instance_uid uses root
+        assert eeg.sop_instance_uid.startswith("9.8.7.6.5.")
+
+        # Test dataset is created
+        assert eeg.ds is not None
+
+    def test_build_metadata(self, routine_scalp_eeg):
+        assert hasattr(routine_scalp_eeg.ds, "file_meta")
+        assert routine_scalp_eeg.ds.file_meta is not None
+        assert routine_scalp_eeg.ds.file_meta.MediaStorageSOPClassUID == pydicom.uid.RoutineScalpElectroencephalogramWaveformStorage
+        assert routine_scalp_eeg.ds.file_meta.MediaStorageSOPInstanceUID == routine_scalp_eeg.sop_instance_uid
+        assert routine_scalp_eeg.sop_instance_uid.startswith("1.2.3.4.5.")
+        assert routine_scalp_eeg.ds.file_meta.ImplementationClassUID == "1.2.3.4"
+        assert routine_scalp_eeg.ds.file_meta.TransferSyntaxUID == ExplicitVRLittleEndian
+
+    def test_build_patient(self, routine_scalp_eeg):
+        assert routine_scalp_eeg.ds.PatientName == "Test^Patient"
+        assert routine_scalp_eeg.ds.PatientID == "PAT001"
+        assert routine_scalp_eeg.ds.PatientBirthDate == "19900101"
+        assert routine_scalp_eeg.ds.PatientSex == "F"
+
+        # Test patient id defaults to name
+        patient = Patient(name="Default^Name", birth_date="20000101", sex="M")
+        assert patient.id == "Default^Name"
+
+    def test_build_study(self, routine_scalp_eeg):
+        assert routine_scalp_eeg.ds.StudyDate == "20240115"
+        assert routine_scalp_eeg.ds.StudyTime == "143022.000000"
+        assert routine_scalp_eeg.ds.AccessionNumber == "ACC123"
+        assert routine_scalp_eeg.ds.ReferringPhysicianName == ""
+        assert routine_scalp_eeg.ds.StudyInstanceUID.startswith("1.2.3.4.5.")
+        assert routine_scalp_eeg.ds.StudyID == "847542"
+
+    def test_build_series(self, routine_scalp_eeg):
+        assert routine_scalp_eeg.ds.Modality == "EEG"
+        assert routine_scalp_eeg.ds.SeriesInstanceUID.startswith("1.2.3.4.5.")
+        assert routine_scalp_eeg.ds.SeriesNumber == "1"
+
+    def test_build_enhanced_general_equipment(self, routine_scalp_eeg):
+        assert routine_scalp_eeg.ds.Manufacturer == "TestManufacturer"
+        assert routine_scalp_eeg.ds.ManufacturerModelName == "TestModel"
+        assert routine_scalp_eeg.ds.DeviceSerialNumber == "SN12345"
+        assert routine_scalp_eeg.ds.SoftwareVersions == "2.0.1"
+
+    def test_build_waveform_identification(self, routine_scalp_eeg):
+        assert routine_scalp_eeg.ds.ContentDate == "20240115"
+        assert routine_scalp_eeg.ds.ContentTime == "143022.123456"
+        assert routine_scalp_eeg.ds.AcquisitionDateTime == "20240115142500.000000"
+        assert routine_scalp_eeg.ds.InstanceNumber == "5"
+
+    def test_build_channel_definition_sequence(self, routine_scalp_eeg):
+        channel_def = routine_scalp_eeg._build_channel_definition_sequence("TestChannel", 1.5, 0.5)
+
+        assert channel_def.ChannelSampleSkew == "0"
+        assert float(channel_def.ChannelSensitivity) == 1.5
+        assert float(channel_def.ChannelBaseline) == 0.5
+        # Verify DS values fit within 16 character limit
+        assert len(str(channel_def.ChannelSensitivity)) <= 16
+        assert len(str(channel_def.ChannelBaseline)) <= 16
+        assert channel_def.WaveformBitsStored == 64
+
+        # Test channel source sequence
+        assert len(channel_def.ChannelSourceSequence) == 1
+        source = channel_def.ChannelSourceSequence[0]
+        assert source.CodeValue == "1.0"
+        assert source.CodingSchemeDesignator == "PYDICOM"
+        assert source.CodingSchemeVersion == "1.0"
+        assert source.CodeMeaning == "TestChannel"
+
+    def test_quantize_to_int64(self, routine_scalp_eeg):
+        # Basic quantization
+        data = np.array([[0.0, 1.0], [0.5, 0.75]])
+        quantized, factor, offset = routine_scalp_eeg.quantize_to_int64(data)
+        assert quantized.dtype == np.int64
+        assert offset == 0.0
+        assert factor == 1.0 / (2**31 - 1)
+
+        # Shape preservation
+        data = np.random.randn(100, 5)
+        quantized, factor, offset = routine_scalp_eeg.quantize_to_int64(data)
+        assert quantized.shape == data.shape
+
+        # Constant data (factor should be 1.0)
+        data = np.ones((10, 3)) * 5.0
+        quantized, factor, offset = routine_scalp_eeg.quantize_to_int64(data)
+        assert factor == 1.0
+        assert offset == 5.0
+        assert np.all(quantized == 0)
+
+        # Range mapping
+        data = np.array([[-100.0], [100.0]])
+        quantized, factor, offset = routine_scalp_eeg.quantize_to_int64(data)
+        assert offset == -100.0
+        assert factor == pytest.approx(0.0000000931323, abs=1e-13)
+        assert quantized[0, 0] == 0
+        assert quantized[1, 0] == 2**31 - 1
+
+        # C-order output
+        data = np.array([[1.0, 2.0], [3.0, 4.0]], order='F')
+        quantized, _, _ = routine_scalp_eeg.quantize_to_int64(data)
+        assert quantized.flags['C_CONTIGUOUS']
+
+    def test_build_waveform_sequence(self, routine_scalp_eeg):
+        data = np.random.randn(150, 3)
+        seq = routine_scalp_eeg._build_waveform_sequence(3, 512.0, ["Ch1", "Ch2", "Ch3"], data)
+
+        assert seq.WaveformOriginality == "ORIGINAL"
+        assert seq.NumberOfWaveformChannels == 3
+        assert seq.NumberOfWaveformSamples == 150
+        assert seq.SamplingFrequency == 512.0
+        assert len(seq.ChannelDefinitionSequence) == 3
+        assert seq.WaveformBitsAllocated == 64
+        assert seq.WaveformSampleInterpretation == "SV"
+
+    def test_build_waveform(self, routine_scalp_eeg):
+        assert routine_scalp_eeg.ds.SOPInstanceUID == routine_scalp_eeg.sop_instance_uid
+        assert routine_scalp_eeg.ds.SOPClassUID == pydicom.uid.RoutineScalpElectroencephalogramWaveformStorage
+        assert hasattr(routine_scalp_eeg.ds, "WaveformSequence")
+        assert len(routine_scalp_eeg.ds.WaveformSequence) == 1
+
+    def test_save_as(self, routine_scalp_eeg):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filepath = os.path.join(tmpdir, "test_output.dcm")
+            routine_scalp_eeg.save_as(filepath)
+
+            assert os.path.exists(filepath)
+
+            # Read back and verify
+            ds = pydicom.dcmread(filepath)
+            assert ds.Modality == "EEG"
+            assert ds.PatientName == "Test^Patient"
+
+            # Verify it's a valid DICOM file
+            assert hasattr(ds, "file_meta")
+            assert ds.file_meta.TransferSyntaxUID == ExplicitVRLittleEndian