Merge branch 'meg-ctf-head-files-orm-models' into HEAD

Author: MaximeBICMTL

python/lib/db/models/meg_ctf_head_shape_file.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+import lib.db.models.meg_ctf_head_shape_point as db_meg_ctf_head_shape_point
+from lib.db.base import Base
+from lib.db.decorators.string_path import StringPath
+
+
+class DbMegCtfHeadShapeFile(Base):
+    """
+    A MEG CTF `headshape.pos` file. This file contains 3D points positioned on the subject head and
+    is shared by all the CTF files of an MEG acquisition.
+    """
+
+    __tablename__ = 'meg_ctf_head_shape_file'
+
+    id: Mapped[int]  = mapped_column('ID', primary_key=True)
+    """
+    ID of the head shape file.
+    """
+
+    path: Mapped[Path] = mapped_column('Path', StringPath)
+    """
+    Path of the head shape file relative to the LORIS data directory.
+    """
+
+    blake2b_hash: Mapped[str] = mapped_column('Blake2bHash')
+    """
+    Blake2B hash of the head shape file, which may be used to check that the on-disk file data
+    matches the file registered in the LORIS database.
+    """
+
+    points: Mapped[list['db_meg_ctf_head_shape_point.DbMegCtfHeadShapePoint']] = relationship('DbMegCtfHeadShapePoint', back_populates='file')
+    """
+    3D points present in the head shape file.
+    """

python/lib/db/models/meg_ctf_head_shape_point.py

@@ -0,0 +1,52 @@
+from decimal import Decimal
+
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+import lib.db.models.meg_ctf_head_shape_file as db_meg_ctf_head_shape_file
+from lib.db.base import Base
+
+
+# TODO: It might be possible that headshape files contain points in other units than centimeters,
+# in which case the database should be extended to handle it.
+class DbMegCtfHeadShapePoint(Base):
+    """
+    A 3D point present in a MEG CTF `headshape.pos` file.
+    """
+
+    __tablename__ = 'meg_ctf_head_shape_point'
+
+    id: Mapped[int] = mapped_column('ID', primary_key=True)
+    """
+    ID of the head shape point.
+    """
+
+    file_id: Mapped[int] = mapped_column('FileID', ForeignKey('meg_ctf_head_shape_file.ID'))
+    """
+    ID of the head shape file to which this point belongs.
+    """
+
+    name: Mapped[str] = mapped_column('Name')
+    """
+    Name of the point, which may either be an integer or an anatomical landmark label.
+    """
+
+    x: Mapped[Decimal] = mapped_column('X')
+    """
+    X coordinate of the point in the head shape file, in centimeters.
+    """
+
+    y: Mapped[Decimal] = mapped_column('Y')
+    """
+    Y coordinate of the point in the head shape file, in centimeters.
+    """
+
+    z: Mapped[Decimal] = mapped_column('Z')
+    """
+    Z coordinate of the point in the head shape file, in centimeters.
+    """
+
+    file: Mapped['db_meg_ctf_head_shape_file.DbMegCtfHeadShapeFile'] = relationship('DbMegCtfHeadShapeFile', back_populates='points')
+    """
+    The head shape file to which this point belongs.
+    """

python/lib/db/models/physio_file.py

@@ -4,6 +4,7 @@
 from sqlalchemy import ForeignKey
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
+import lib.db.models.meg_ctf_head_shape_file as db_meg_ctf_head_shape_file
 import lib.db.models.physio_channel as db_physio_channel
 import lib.db.models.physio_event_archive as db_physio_event_archive
 import lib.db.models.physio_event_file as db_physio_event_file
@@ -42,6 +43,11 @@ class DbPhysioFile(Base):
     file or an archive. The path is relative to the LORIS data directory.
     """
 
+    head_shape_file_id: Mapped[int | None] = mapped_column('HeadShapeFileID', ForeignKey('meg_ctf_head_shape_file.ID'))
+    """
+    ID of the head shape file associated to this file, which is only present for MEG CTF files.
+    """
+
     output_type   : Mapped['db_physio_output_type.DbPhysioOutputType']             = relationship('DbPhysioOutputType')
     modality      : Mapped['db_physio_modality.DbPhysioModality | None']           = relationship('DbPhysioModality')
     session       : Mapped['db_session.DbSession']                                 = relationship('DbSession')
@@ -50,3 +56,8 @@ class DbPhysioFile(Base):
     channels      : Mapped[list['db_physio_channel.DbPhysioChannel']]              = relationship('DbPhysioChannel', back_populates='physio_file')
     parameters    : Mapped[list['db_phyiso_file_parameter.DbPhysioFileParameter']] = relationship('DbPhysioFileParameter', back_populates='file')
     event_files   : Mapped[list['db_physio_event_file.DbPhysioEventFile']]         = relationship('DbPhysioEventFile', back_populates='physio_file')
+
+    head_shape_file: Mapped['db_meg_ctf_head_shape_file.DbMegCtfHeadShapeFile | None'] = relationship('DbMegCtfHeadShapeFile')
+    """
+    The head shape file associated to this file, which is only present for MEG CTF files.
+    """