fctpd 0.1.0__py3-none-any.whl

fctpd/__init__.py

@@ -0,0 +1,11 @@
+from .enums import AnonymizationLevel, PixelEncoding, WriteMode
+from .field_map import FieldMap
+from .fpb_reader import FPBReader
+from .fpb_writer import FPBWriter
+from .fph_reader import FPHReader
+from .fph_writer import FPHWriter
+from .header import Header
+from .marshaler import ProjectionMarshaler
+from .projection import Projection
+from .unmarshaler import ProjectionUnmarshaler
+from .writer import WriteOptions

fctpd/enums.py

@@ -0,0 +1,31 @@
+from enum import Enum
+
+
+class AnonymizationLevel(Enum):
+    """
+    AnonymizationLevel describes how a Reader or Writer should treat
+    the sensitive entry collection.
+    """
+
+    High = 0
+    Medium = 1
+    Low = 2
+    NA = 3
+
+
+class PixelEncoding(Enum):
+    """
+    PixelEncoding describes how a Writer should serialize pixel data.
+    """
+
+    F32 = 0
+    U16 = 1
+
+
+class WriteMode(Enum):
+    """
+    WriteMode describes how an FPHWriter writes its projection data.
+    """
+
+    Single = 0
+    Multi = 1

fctpd/fetcher.py

@@ -0,0 +1,123 @@
+from . import fields
+from .field_map import FieldMap
+from requests import get, Response
+from typing import Any
+from urllib.parse import ParseResult, urlparse
+import os
+
+
+class SelfValue(Any):
+    def __init__(self, offset: int, range: int | None) -> None:
+        self._offset: int = offset
+        self._range: int | None = range
+
+    @property
+    def offset(self) -> int:
+        return self._offset
+
+    @property
+    def range(self) -> int | None:
+        return self._range
+
+
+class Fetcher:
+    def __init__(self) -> None:
+        return
+
+    def fetch(self, val: Any) -> Any:
+        """
+        Fetch either standard and URI-linked data from an input value.
+
+        Parameters
+        ----------
+        - val (Any): Value to parse.
+
+        Returns
+        -------
+        - data (Any): Data linked by the value.
+        """
+        # If we don't have a FieldMap, there's nothing to fetch
+        if not isinstance(val, FieldMap) and not isinstance(val, dict):
+            return val
+
+        # If the URI is absent, we cannot treat the value as a
+        # URI-addressed value; simply return it
+        if fields.URI not in val:
+            return val
+
+        # Set the byte offset and range
+        uri: str = val[fields.URI]
+        offset: int = val[fields.ByteOffset] if fields.ByteOffset in val else 0
+        range: int | None = val[fields.ByteRange] if fields.ByteRange in val else None
+
+        # Validate whether the URI is valid
+        uri_parse: ParseResult = urlparse(uri)
+        if not uri_parse.scheme:
+            raise ValueError("invalid URI-addressed value: URI is invalid")
+
+        # Match on the scheme
+        match uri_parse.scheme:
+            case "file":
+                return self._fetch_file(uri_parse.path, offset, range)
+
+            case "http" | "https":
+                return self._fetch_http(uri, offset, range)
+
+            case "self":
+                return SelfValue(offset, range)
+
+            case _:
+                raise NotImplementedError(
+                    f"URI scheme {uri_parse.scheme} not supported"
+                )
+
+    def _fetch_file(self, path: str, offset: int, range: int | None) -> bytes:
+        """
+        Internal fetch function for local files.
+
+        Parameters
+        ----------
+        - path (str): Local file path to data.
+        - offset (int): File byte offset to data.
+        - range: (int | None): Size of byte data to read.
+        """
+        # Check the path exists and is a file
+        if not os.path.exists(path) or os.path.isdir(path):
+            raise FileNotFoundError
+
+        # Adjust the range
+        if range is None:
+            range = os.path.getsize(path)
+
+        # Load the file pointer into memory
+        with open(path, "rb", buffering=0) as f:
+            f.seek(offset, os.SEEK_SET)
+            data: bytes = f.read(range)
+            f.close()
+
+        return data
+
+    def _fetch_http(self, uri: str, offset: int, range: int | None) -> bytes:
+        """
+        Internal fetch function for HTTP/HTTPS.
+
+        Parameters
+        ----------
+        - uri (str): HTTP-schemed URI to data.
+        - offset (int): File byte offset to data.
+        - range: (int | None): Size of byte data to read.
+        """
+
+        # Get the range header
+        range_hdr: dict[str, str] = (
+            {"Range": f"bytes={offset}-"}
+            if range is None
+            else {"Range": f"bytes={offset}-{offset+range}"}
+        )
+
+        # Perform the request
+        resp: Response = get(uri, headers=range_hdr)
+        resp.raise_for_status()
+
+        # Return the response body
+        return resp.content

fctpd/field_map.py

@@ -0,0 +1,104 @@
+from . import fields
+from .enums import AnonymizationLevel
+from .timing import date
+from .uid import generate_accession_number, generate_uid
+from numpy import number
+from re import match
+from typing import Any
+
+
+class FieldMap(dict[str, Any]):
+    """
+    FieldMap is a hash map with string-valued keys and
+    any-valued values.
+    """
+
+    def __init__(self, entries: dict[str, Any] | None = None) -> None:
+        """
+        Constructor for a FieldMap object.
+
+        Parameters
+        ----------
+        - entries (dict[str, Any]): Entries to initialize the FieldMap
+          with [default: `{}`].
+        """
+        super().__init__({} if entries is None else entries)
+
+    def anonymized(self, anon_level: AnonymizationLevel) -> FieldMap:
+        """
+        Returns an anonymized copy of the FieldMap object.
+
+        Parameters
+        ----------
+        - anon_level (AnonymizationLevel): Degree of anonymization to apply
+          to the copied FieldMap.
+
+        Returns
+        -------
+        - anon_fm (FieldMap): Anonymized FieldMap object.
+        """
+        # Iterate through sensitive fields and anonymize
+        anon_fm: FieldMap = FieldMap()
+        for fld in fields.SensitiveFields:
+            # Skip fields that are absent
+            if fld not in self:
+                continue
+
+            # Switch on anonymization level
+            val = self.pop(fld)
+            match anon_level:
+                case AnonymizationLevel.High:
+                    # Leave the entry out
+                    continue
+
+                case AnonymizationLevel.Medium:
+                    # Switch on the value type
+                    match val:
+                        case str():
+                            anon_fm[fld] = ""
+                        case number():
+                            anon_fm[fld] = 0
+
+                case AnonymizationLevel.Low:
+                    # Switch on the value type
+                    match val:
+                        case str():
+                            anon_fm[fld] = _anonymize_string_field(fld, val)
+                        case number():
+                            anon_fm[fld] = 0
+
+                case AnonymizationLevel.NA:
+                    # Reinstate the entry
+                    anon_fm[fld] = val
+
+        return anon_fm
+
+
+def _anonymize_string_field(fld: str, val: str) -> str:
+    """
+    Internal string anonymization function.
+
+    Parameters
+    ----------
+    - fld (str): Name of the entry.
+    - val (str): String-typed value associated with the entry.
+
+    Returns
+    -------
+    - anonymized string value (str)
+    """
+    lower: str = fld.lower()
+    if "date" in lower:
+        return date()
+    elif "pregnan" in lower:
+        return "PregnancyUnknown"
+    elif "uid" in lower:
+        return generate_uid()
+    elif "time" in lower:
+        return "0.000"
+    elif fld == fields.AccessionNumber:
+        return generate_accession_number()
+    elif match(r"[\w+]Y", val):
+        return "000Y"
+    else:
+        return "ANON"

fctpd/fields.py

@@ -0,0 +1,212 @@
+# File IO fields
+ByteOffset: str = "ByteOffset"
+ByteRange: str = "ByteRange"
+URI: str = "URI"
+
+# Scanner fields
+Rows: str = "NumberOfRows"
+Channels: str = "NumberOfChannels"
+CollimatedSliceWidth: str = "CollimatedSliceWidth"
+CentralRow: str = "CentralRow"
+CentralChannel: str = "CentralChannel"
+AcquisitionFOV: str = "AcquisitionFOV"
+RowWidth: str = "RowWidth"
+ChannelWidth: str = "ChannelWidth"
+AnodeAngle: str = "AnodeAngle"
+Manufacturer: str = "Manufacturer"
+ScannerModel: str = "ScannerModel"
+DistanceSourceToIsocenter: str = "DistanceSourceToIsocenter"
+DistanceSourceToDetector: str = "DistanceSourceToDetector"
+Modality: str = "Modality"
+DetectorShape: str = "DetectorShape"
+CentralChannelOffset: str = "CentralChannelOffset"
+WedgeProfile: str = "WedgeProfile"
+
+# Acquisition fields
+TableSpeed: str = "TableSpeed"
+RotationTime: str = "RotationTime"
+ScanTime: str = "ScanTime"
+TableHeight: str = "TableHeight"
+TableFeedDirection: str = "TableFeedDirection"
+TubeAngleDirection: str = "TubeAngleDirection"
+FlyingFocalSpotMode: str = "FlyingFocalSpotMode"
+Exposure: str = "Exposure"
+ExposureNominal: str = "ExposureNominal"
+TubeVoltage: str = "TubeVoltage"
+CTDIvol: str = "CTDIvol"
+CTDIw: str = "CTDIw"
+PatientPosition: str = "PatientPosition"
+BodyPartExamined: str = "BodyPartExamined"
+StartTablePosition: str = "StartTablePosition"
+EndTablePosition: str = "EndTablePosition"
+StartTubeAngle: str = "StartTubeAngle"
+EndTubeAngle: str = "EndTubeAngle"
+ProtocolName: str = "ProtocolName"
+SeriesDescription: str = "SeriesDescription"
+StudyDescription: str = "StudyDescription"
+NumberOfSpectra: str = "NumberOfSpectra"
+SpectrumIndex: str = "SpectrumIndex"
+NoiseEquivalentQuanta: str = "NoiseEquivalentQuanta"
+SourcePath: str = "SourcePath"
+RayGeometry: str = "RayGeometry"
+NumberOfProjections: str = "NumberOfProjections"
+LogarithmicEncoding: str = "LogarithmicEncoding"
+
+# Projection-specific fields
+TablePosition: str = "TablePosition"
+TubeAngle: str = "TubeAngle"
+SourceAngularPositionShift: str = "SourceAngularPositionShift"
+SourceAxialPositionShift: str = "SourceAxialPositionShift"
+SourceRadialDistanceShift: str = "SourceRadialDistanceShift"
+ReadingIndex: str = "ReadingIndex"
+Timestamp: str = "Timestamp"
+MinimumPixelValue: str = "MinimumPixelValue"
+MaximumPixelValue: str = "MaximumPixelValue"
+TubeCurrent: str = "TubeCurrent"
+Data: str = "Data"
+View: str = "View"
+
+# Reconstruction fields
+ConeAngle: str = "ConeAngle"
+ProjectionsPerRotation: str = "ProjectionsPerRotation"
+TableFeedPerRotation: str = "TableFeedPerRotation"
+FanAngleIncrement: str = "FanAngleIncrement"
+Pitch: str = "Pitch"
+
+# Image fields
+RescaleSlope: str = "RescaleSlope"
+RescaleIntercept: str = "RescaleIntercept"
+HounsfieldUnitCalibration: str = "HounsfieldUnitCalibration"
+PixelRepresentation: str = "PixelRepresentation"
+PhotometricInterpretation: str = "PhotometricInterpretation"
+HighBit: str = "HighBit"
+BitsAllocated: str = "BitsAllocated"
+BitsStored: str = "BitsStored"
+SamplesPerPixel: str = "SamplesPerPixel"
+MatrixRows: str = "MatrixRows"
+MatrixColumns: str = "MatrixColumns"
+
+# Sensitive Fields
+PatientAge: str = "PatientAge"
+PatientBirthDate: str = "PatientBirthDate"
+PatientID: str = "PatientID"
+PatientName: str = "PatientName"
+PatientSex: str = "PatientSex"
+PatientSize: str = "PatientSize"
+PatientWeight: str = "PatientWeight"
+PregnancyStatus: str = "PregnancyStatus"
+RequestedProcedure: str = "RequestedProcedure"
+SmokingStatus: str = "SmokingStatus"
+PhysicianName: str = "PhysicianName"
+AccessionNumber: str = "AccessionNumber"
+InstitutionName: str = "InstitutionName"
+InstitutionAddress: str = "InstitutionAddress"
+SOPClassUID: str = "SOPClassUID"
+SOPInstanceUID: str = "SOPInstanceUID"
+StudyInstanceUID: str = "StudyInstanceUID"
+SeriesInstanceUID: str = "SeriesInstanceUID"
+IrradiationEventUID: str = "IrradiationEventUID"
+AcquisitionDate: str = "AcquisitionDate"
+SeriesDate: str = "SeriesDate"
+Diagnosis: str = "Diagnosis"
+EthnicGroup: str = "EthnicGroup"
+AcquisitionTime: str = "AcquisitionTime"
+RangeName: str = "RangeName"
+
+# Sensitive fields
+SensitiveFields: set[str] = {
+    PregnancyStatus,
+    PatientID,
+    PatientWeight,
+    PatientAge,
+    PatientBirthDate,
+    PatientName,
+    PatientSex,
+    PatientSize,
+    RangeName,
+    SmokingStatus,
+    PhysicianName,
+    AccessionNumber,
+    InstitutionName,
+    InstitutionAddress,
+    StudyInstanceUID,
+    SeriesInstanceUID,
+    IrradiationEventUID,
+    AcquisitionDate,
+    AcquisitionTime,
+    SeriesDate,
+    Diagnosis,
+    EthnicGroup,
+    SOPInstanceUID,
+    Timestamp,
+}
+
+
+# Required reconstruction fields
+ReconFieldsRequired: set[str] = {
+    Rows,
+    Channels,
+    NumberOfProjections,
+    ProjectionsPerRotation,
+    CentralRow,
+    CentralChannel,
+    AcquisitionFOV,
+    RowWidth,
+    ChannelWidth,
+    DistanceSourceToIsocenter,
+    DistanceSourceToDetector,
+    TableSpeed,
+    RotationTime,
+    FlyingFocalSpotMode,
+    RayGeometry,
+}
+
+# Recommended reconstruction fields
+ReconFieldsRecommended: set[str] = {
+    TableFeedDirection,
+    TubeAngleDirection,
+    AnodeAngle,
+    HounsfieldUnitCalibration,
+    FanAngleIncrement,
+    Pitch,
+    ScanTime,
+    TableHeight,
+    Manufacturer,
+    PatientPosition,
+    ScannerModel,
+    SpectrumIndex,
+}
+
+
+# Optional reconstruction fields
+ReconFieldsOptional: set[str] = {
+    SourcePath,
+    LogarithmicEncoding,
+    NumberOfSpectra,
+    TubeVoltage,
+    PixelRepresentation,
+    HighBit,
+    BitsAllocated,
+    BitsStored,
+    SamplesPerPixel,
+    CentralChannelOffset,
+    StartTablePosition,
+    EndTablePosition,
+    StartTubeAngle,
+    EndTubeAngle,
+    Exposure,
+    ExposureNominal,
+    CTDIw,
+    CTDIvol,
+    CollimatedSliceWidth,
+    ConeAngle,
+    TableFeedPerRotation,
+    ProtocolName,
+    SOPClassUID,
+    SeriesDescription,
+    StudyDescription,
+    BodyPartExamined,
+    Modality,
+    DetectorShape,
+    PhotometricInterpretation,
+}

fctpd/fpb_reader.py

@@ -0,0 +1,102 @@
+from . import fields
+from .enums import AnonymizationLevel
+from .field_map import FieldMap
+from .fpb_writer import _MAGIC_WORD
+from .fph_reader import FPHReader
+from .unmarshaler import ProjectionUnmarshaler
+from json import loads
+from os.path import exists
+import os
+
+
+class FPBReader(FPHReader):
+    """
+    FPBReader parses an .fpb file.
+    """
+
+    def __init__(
+        self, input_path: str, anon_level: AnonymizationLevel = AnonymizationLevel.High
+    ) -> None:
+        """
+        Constructor for the FPBReader class.
+
+        Parameters
+        ----------
+        - input_path (str): Path to the .fpb file to read.
+        - anon_level (AnonymizationLevel): Degree of anonymization to apply to
+          reading operations [default: `AnonymizationLevel.High`].
+        """
+        self._projectionMaps: list[FieldMap] = []
+        self.initialize(input_path, anon_level)
+        self._unmarshaler: ProjectionUnmarshaler = ProjectionUnmarshaler(input_path)
+
+    def initialize(
+        self, path: str, anon_level: AnonymizationLevel | None = None
+    ) -> None:
+        """
+        Initializes the FPBReader for a new file at the specified path.
+
+        Parameters
+        ----------
+        - path (str): Path to the .fpb file to read.
+        - anon_level (AnonymizationLevel | None): Degree of anonymization to
+          apply to reading operations [default: `None`].
+        """
+        # Check the file exists
+        if not exists(path):
+            raise FileNotFoundError
+
+        # Open the fpb file
+        with open(path, "rb") as fileptr:
+            # Check the magic word
+            fileptr.seek(-8, os.SEEK_END)
+            magic_word: bytes = fileptr.read(8)
+            if magic_word != _MAGIC_WORD:
+                raise SyntaxError
+
+            # Jump to the FPH block
+            fileptr.seek(-16, os.SEEK_END)
+            footer_offset: int = int.from_bytes(fileptr.read(8), byteorder="little")
+            fileptr.seek(footer_offset, os.SEEK_SET)
+
+            # Read the FPH block
+            fph_bytes: bytes = fileptr.read(os.path.getsize(path) - footer_offset - 24)
+            fmap: FieldMap = loads(fph_bytes.decode())
+            fileptr.close()
+
+        # If the projections entry is missing, we panic
+        if "projections" not in fmap:
+            raise KeyError("required `projections` key not found in fph file")
+
+        # If the projections entry ISN'T a list, we panic
+        if not isinstance(fmap["projections"], list):
+            raise ValueError("required `projections` value is not an array")
+
+        # Set the maps
+        self._scanMap: FieldMap = (
+            FieldMap(fmap["scan"]) if "scan" in fmap else FieldMap()
+        )
+
+        self._sensitiveMap: FieldMap = (
+            FieldMap(fmap["sensitive"]) if "sensitive" in fmap else FieldMap()
+        )
+
+        self._projectionMaps: list[FieldMap] = fmap["projections"]
+        self._missingFields: set[str] = set()
+
+        try:
+            self._projectionMaps.sort(key=lambda x: x[fields.ReadingIndex])
+        except KeyError:
+            self._projectionMaps.sort(
+                key=lambda x: x[fields.View][fields.TablePosition]
+            )
+        except Exception as e:
+            raise e
+
+        # Set the anonymization level
+        if anon_level is not None:
+            self.anonymization = anon_level
+
+        # Set the number of rows and columns (necessary?)
+        self._rows: int = self._scanMap[fields.Rows]
+        self._channels: int = self._scanMap[fields.Channels]