isocenter 0.7.0__py3-none-any.whl

isocenter/__init__.py

@@ -0,0 +1,63 @@
+import warnings
+# Suppress all pydicom warnings (e.g. strict UID validation)
+warnings.filterwarnings("ignore", module="pydicom.*")
+
+try:
+    from .session import DicomSession as Session
+
+    # Expose the Builder for power users
+    from .builders import DicomBuilder as Builder
+
+    # Expose Equipment for type hinting
+    from .entities import Equipment
+
+    # Expose handler for direct import check
+    from . import imagecodecs_handler
+
+except ImportError as e:
+    # Catch broken pylibjpeg installations that typically occur on Python 3.14t
+    if "_openjpeg" in str(e):
+        raise RuntimeError(
+            "\n"
+            "CRITICAL ERROR: Broken 'pylibjpeg' installation detected.\n"
+            "----------------------------------------------------------\n"
+            "This environment contains corrupt 'pylibjpeg' packages from a failed build attempt.\n"
+            "Isocenter cannot start because 'pydicom' is attempting to load these broken plugins.\n\n"
+            "TO FIX: Run this command to clean your environment:\n"
+            "    pip uninstall -y pylibjpeg pylibjpeg-openjpeg pylibjpeg-libjpeg pylibjpeg-rle\n"
+            "----------------------------------------------------------\n"
+        ) from e
+    raise
+
+# Configure pydicom handlers
+# We prioritize pylibjpeg (if installed) and pillow.
+# GDCM is often problematic to install via pip, so pylibjpeg is preferred for JPEG/JPEG-LS/RLE.
+try:
+    from pydicom import config as pydicom_config
+    import pydicom.pixel_data_handlers.gdcm_handler as gdcm_handler
+    import pydicom.pixel_data_handlers.pillow_handler as pillow_handler
+    import pydicom.pixel_data_handlers.numpy_handler as numpy_handler
+    from . import imagecodecs_handler
+
+    # We explicitly define the priority list using module objects
+    pydicom_config.pixel_data_handlers = [
+        gdcm_handler,
+        imagecodecs_handler,
+        pillow_handler,
+        numpy_handler
+    ]
+except ImportError:
+    pass
+
+try:
+    from importlib.metadata import version, PackageNotFoundError
+except ImportError:
+    # Backport for older Pythons if needed, though Isocenter requires 3.9+ where this is standard
+    from importlib_metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("isocenter")
+except PackageNotFoundError:
+    # Package is not installed
+    __version__ = "0.0.0"
+__all__ = ["Session", "Builder", "Equipment"]

isocenter/automation.py

@@ -0,0 +1,143 @@
+"""
+Module for analyzing OCR findings and suggesting configuration updates.
+"""
+from typing import List, Dict, Any
+from collections import defaultdict
+from isocenter.privacy import PhiReport
+from isocenter.configuration import IsocenterConfiguration
+
+class ConfigAutomator:
+    """
+    Analyzes OCR findings and generates suggestions to update the redaction configuration.
+    """
+
+    @staticmethod
+    def suggest_config_updates(report: PhiReport, _current_config: IsocenterConfiguration) -> List[Dict[str, Any]]:
+        """
+        Generates a list of suggested configuration changes.
+
+        Returns:
+            List[Dict]: A list of 'suggestion' objects:
+            {
+                "serial": str,
+                "action": "ADD_ZONE" | "EXPAND_ZONE",
+                "zone": [x, y, w, h],
+                "reason": str
+            }
+        """
+        suggestions = []
+
+        # Group findings by machine serial
+        findings_by_serial = defaultdict(list)
+
+        for finding in report:
+            meta = finding.metadata
+            if not meta:
+                continue
+
+            serial = meta.get("rule_serial")
+            if serial:
+                findings_by_serial[serial].append(finding)
+            else:
+                # Todo: Handle findings with no matching rule (Unknown Serial or No config entry)
+                pass
+
+        for serial, findings in findings_by_serial.items():
+            # In a real system we might merge zones here.
+            for f in findings:
+                meta = f.metadata
+                l_type = meta.get("leak_type")
+                text_box = meta.get("text_box") # x,y,w,h
+
+                if not text_box:
+                    continue
+
+                if l_type == "PARTIAL_LEAK":
+                    # Suggest expanding the best_zone to cover text_box
+                    best_zone = meta.get("best_zone")
+                    if best_zone:
+                        # Calculate union box
+                        tx, ty, tw, th = text_box
+                        zx, zy, zw, zh = best_zone
+
+                        ux = min(tx, zx)
+                        uy = min(ty, zy)
+                        ur = max(tx+tw, zx+zw)
+                        ub = max(ty+th, zy+zh)
+
+                        union_zone = [int(ux), int(uy), int(ur-ux), int(ub-uy)]
+
+                        suggestions.append({
+                            "serial": serial,
+                            "action": "EXPAND_ZONE",
+                            "original_zone": best_zone,
+                            "new_zone": union_zone,
+                            "reason": f"Partial leak detected ({f.value}). Expanded to cover."
+                        })
+
+                elif l_type == "NEW_LEAK":
+                    # Suggest adding the text box as a new zone
+                    # Add some padding?
+                    # Ensure ints
+                    zone = [int(x) for x in text_box]
+
+                    suggestions.append({
+                        "serial": serial,
+                        "action": "ADD_ZONE",
+                        "zone": list(zone),
+                        "reason": f"New leak detected ({f.value}). Added new zone."
+                    })
+
+        return suggestions
+
+    @staticmethod
+    def apply_suggestions(session: 'DicomSession', suggestions: List[Dict[str, Any]]) -> int:
+        """
+        Applies the suggestions to the session's in-memory configuration.
+        Returns: Number of changes applied.
+        """
+        count = 0
+        rules = session.configuration.rules
+
+        for sug in suggestions:
+            serial = sug["serial"]
+            action = sug["action"]
+
+            # Find the rule object
+            target_rule = None
+            for r in rules:
+                if r.get("serial_number") == serial:
+                    target_rule = r
+                    break
+
+            if not target_rule:
+                continue
+
+            if action == "ADD_ZONE":
+                zone = sug["zone"]
+                # Check duplicates?
+                if zone not in target_rule["redaction_zones"]:
+                    target_rule["redaction_zones"].append(zone)
+                    count += 1
+
+            elif action == "EXPAND_ZONE":
+                old_zone = sug["original_zone"]
+                new_zone = sug["new_zone"]
+
+                # Find index of old_zone
+                zones = target_rule["redaction_zones"]
+                try:
+                    # Convert to list for comparison just in case
+                    idx = -1
+                    for i, z in enumerate(zones):
+                        if list(z) == list(old_zone):
+                            idx = i
+                            break
+
+                    if idx >= 0:
+                        zones[idx] = new_zone
+                        count += 1
+                except ValueError:
+                    pass
+
+        return count

isocenter/builders.py

@@ -0,0 +1,96 @@
+"""
+Builder pattern implementation for constructing DICOM entity hierarchies.
+
+This module provides a fluent interface for creating Patient, Study, Series,
+and Instance objects in a structured way.
+"""
+from .entities import Patient, Study, Series, Instance, Equipment
+
+
+class DicomBuilder:
+    """
+    Factory for creating fluent Dicom hierarchy builders.
+
+    Usage:
+       patient = DicomBuilder.start_patient("P123", "Doe^John")
+           .add_study("1.2.3", "20240101")
+           .add_series("1.2.3.1", "CT", "1")
+           .end_study().build()
+    """
+    @staticmethod
+    def start_patient(id, name):
+        """Begin building a Patient."""
+        return PatientBuilder(id, name)
+
+
+class PatientBuilder:
+    """Fluent Builder for Patient entities."""
+
+    def __init__(self, id, name): self.patient = Patient(id, name)
+
+    def add_study(self, uid, date):
+        """Adds a child Study to this Patient."""
+        s = Study(uid, date)
+        self.patient.studies.append(s)
+        return StudyBuilder(self, s)
+
+    def build(self):
+        """Returns the fully constructed Patient object."""
+        return self.patient
+
+
+class StudyBuilder:
+    """Fluent Builder for Study entities."""
+
+    def __init__(self, parent, study): self.parent, self.study = parent, study
+
+    def add_series(self, uid, mod, num):
+        """Adds a child Series to this Study."""
+        s = Series(uid, mod, num)
+        self.study.series.append(s)
+        return SeriesBuilder(self, s)
+
+    def end_study(self):
+        """Finishes the Study configuration and returns the parent PatientBuilder."""
+        return self.parent
+
+
+class SeriesBuilder:
+    """Fluent Builder for Series entities."""
+
+    def __init__(self, parent, series): self.parent, self.series = parent, series
+
+    def set_equipment(self, man, mod, sn=""):
+        """Sets the Equipment metadata for this Series."""
+        self.series.equipment = Equipment(man, mod, sn)
+        return self
+
+    def add_instance(self, uid, cls, num):
+        """Adds a child Instance to this Series."""
+        inst = Instance(uid, cls, num)
+        self.series.instances.append(inst)
+        return InstanceContextBuilder(self, inst)
+
+    def end_series(self):
+        """Finishes the Series configuration and returns the parent StudyBuilder."""
+        return self.parent
+
+
+class InstanceContextBuilder:
+    """Fluent context for configuring a single Instance."""
+
+    def __init__(self, parent, instance): self.parent, self.instance = parent, instance
+
+    def set_attribute(self, tag, val):
+        """Sets a generic DICOM attribute."""
+        self.instance.set_attr(tag, val)
+        return self
+
+    def set_pixel_data(self, arr):
+        """Injects pixel data (numpy array)."""
+        self.instance.set_pixel_data(arr)
+        return self
+
+    def end_instance(self):
+        """Finishes the Instance and returns the parent SeriesBuilder."""
+        return self.parent

isocenter/config_manager.py

@@ -0,0 +1,277 @@
+"""
+Configuration manager for handling Isocenter system settings.
+
+This module provides functionality to load, validate, and manage configuration
+files for the Isocenter application. It supports unified YAML configurations,
+legacy formats, and privacy profile management.
+"""
+
+import os
+import logging
+import copy
+from typing import Dict, Any, List, Optional
+import json
+import re
+import yaml
+
+from dotenv import load_dotenv
+
+from .profiles import PRIVACY_PROFILES
+
+CONFIG_VERSION = "2.0"
+
+# Load environment variables
+load_dotenv()
+
+
+def get_logger() -> logging.Logger:
+    """
+    Retrieves the configured logger for the Isocenter application.
+
+    Returns:
+        logging.Logger: The 'isocenter' logger instance.
+    """
+    return logging.getLogger("isocenter")
+
+
+def load_unified_config(path: str) -> Dict[str, Any]:
+    """
+    Loads the unified configuration file (YAML).
+
+    Supports legacy list-based config (machine rules only) and new dict-based config.
+    Merges 'privacy_profile' if specified (Built-in or External).
+
+    Args:
+        path (str): Path to the YAML configuration file.
+
+    Returns:
+        Dict[str, Any]: The loaded configuration dictionary.
+
+    Raises:
+        ValueError: If file is not YAML.
+    """
+    if not (path.endswith('.yaml') or path.endswith('.yml')):
+        raise ValueError("Configuration file must be a YAML file (.yaml or .yml)")
+
+    with open(path, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    # Handle Standard Config
+    config = data
+
+    # Merge Privacy Profile
+    if "privacy_profile" in config:
+        profile_name = config["privacy_profile"]
+
+        profile_rules = {}
+
+        # 1. Check Built-in Profiles
+        if profile_name in PRIVACY_PROFILES:
+            profile_rules = copy.deepcopy(PRIVACY_PROFILES[profile_name])
+            get_logger().info("Loaded built-in privacy profile '%s' with %d rules.", profile_name, len(profile_rules))
+
+        # 2. Check External File (Custom Profile)
+        elif os.path.exists(profile_name):
+            try:
+                # We reuse load_phi_config logic to parse just the tags
+                profile_rules = ConfigLoader.load_phi_config(profile_name)
+                get_logger().info("Loaded custom privacy profile from '%s' with %d rules.", profile_name, len(profile_rules))
+            except (ValueError, OSError) as e:
+                get_logger().error("Failed to load custom profile '%s': %s", profile_name, e)
+
+        else:
+            get_logger().warning("Unknown privacy profile reference '%s' (not a built-in or file). Ignoring.", profile_name)
+
+        if not profile_rules:
+            # Ignoring it means ignoring it everywhere. Leaving the name in
+            # the config would let the compliance report name a profile that
+            # contributed no rules -- protection that never ran.
+            config.pop("privacy_profile", None)
+
+        if profile_rules:
+            # User rules override profile rules
+            user_rules = config.get("phi_tags", {})
+            profile_rules.update(user_rules)
+            config["phi_tags"] = profile_rules
+
+    return config
+
+
+class ConfigLoader:
+    """
+    Loads and validates configuration files for the Isocenter system.
+
+    This class provides static methods to parse unified YAML configuration files (v2.0),
+    legacy configuration formats, and PHI tag definitions. It handles configuration
+    validation, normalization, and file I/O operations.
+
+    Supports multiple configuration formats:
+    - Unified v2.0 YAML configs with PHI tags, machine rules, and date jitter settings
+    - Legacy machine rule configurations
+    - PHI tag definitions (from files or internal defaults)
+
+    The class also provides utility methods for filename sanitization and YAML parsing.
+    """
+
+    @staticmethod
+    def load_unified_config(
+            filepath: str) -> tuple[Dict[str, Any], List[Dict[str, Any]],
+                                    Dict[str, Any], bool, Optional[str]]:
+        """
+        Parses the unified YAML config (v2.0).
+
+        Extracts the core configuration components: PHI tags, machine rules,
+        date jitter settings, and global flags.
+
+        Args:
+            filepath (str): Path to the config file.
+
+        Returns:
+            tuple: (phi_tags, machine_rules, date_jitter_config,
+            remove_private_tags, privacy_profile). The last element is the
+            name of the profile whose rules were merged, or None -- an
+            unknown reference resolves to None rather than to its own name,
+            because it contributed nothing.
+        """
+        # Call the top-level loader which handles YAML, Legacy List, and Privacy Profiles
+        data = load_unified_config(filepath)
+
+        phi_tags = data.get("phi_tags", {})
+        # Support 'machines' (v2) or 'machine_rules' (legacy internal)
+        machine_rules = data.get("machines", data.get("machine_rules", []))
+
+        # Date Jitter Normalization
+        dj = data.get("date_jitter", {"min_days": -365, "max_days": -1})
+        if isinstance(dj, int):
+            # Legacy support or user provided int. Convert to fixed shift.
+            date_jitter_config = {"min_days": dj, "max_days": dj}
+        else:
+            date_jitter_config = dj
+
+        remove_private_tags = data.get("remove_private_tags", True)
+
+        # Validate machines
+        for i, rule in enumerate(machine_rules):
+            ConfigLoader._validate_rule(rule, i)
+
+        return (phi_tags, machine_rules, date_jitter_config,
+                remove_private_tags, data.get("privacy_profile"))
+
+    @staticmethod
+    def load_redaction_rules(filepath: str) -> List[Dict[str, Any]]:
+        """
+        Legacy/Convenience support for loading only Machine Rules.
+
+        Use this if you only need the 'machines' list from a unified config,
+        or an old-style legacy config file.
+
+        Args:
+            filepath (str): Path to the config file.
+
+        Returns:
+            List[Dict[str, Any]]: List of validated machine rule dictionaries.
+        """
+        data = ConfigLoader._load_yaml(filepath)
+
+        rules = []
+
+        if "machines" in data:
+            rules = data["machines"]  # v1 or v2
+        else:
+            get_logger().warning("Config Warning: Could not find 'machines' list.")
+
+        for i, rule in enumerate(rules):
+            ConfigLoader._validate_rule(rule, i)
+
+        return rules
+
+    @staticmethod
+    def load_phi_config(filepath: str = None) -> Dict[str, str]:
+        """
+        Legacy/Convenience support for loading only PHI Tags.
+
+        Arg:
+            filepath (str, optional): Path to config file. If None, loads internal defaults.
+
+        Returns:
+            Dict: Mapping of tags to configuration (action/name).
+        """
+        if filepath:
+            data = ConfigLoader._load_yaml(filepath)
+
+            # Support v2 unified file used as simple PHI config
+            if "phi_tags" in data:
+                return data["phi_tags"]
+            return data.get("phi_tags", data)  # Fallback to assumes root dict is tags if no key
+        else:
+            # Load default from package resources
+            base = os.path.dirname(os.path.abspath(__file__))
+            filepath = os.path.join(base, "resources", "phi_tags.json")
+            if os.path.exists(filepath):
+                # Resource is likely still JSON for internal defaults unless we change it too.
+                # But sticking to JSON for internal resources is fine, OR we change helper to handle both?
+                # User asked to drop JSON support for *config files*.
+                # Let's support JSON just for internal resources via simple json load if yaml fails or extension check?
+                # Actually, clearer to migrate the resource to YAML too?
+                # Or just use json.load here explicitly since it's internal.
+                # import json  <-- Removed
+
+                with open(filepath, 'r', encoding="utf-8") as f:
+                    return json.load(f).get("phi_tags", {})
+            return {}
+
+    @staticmethod
+    def clean_filename(filename: str) -> str:
+        """
+        Sanitizes a string to be safe for use as a filename.
+
+        Replaces spaces with underscores and removes non-alphanumeric characters
+        (except key delimiters like dash/dot).
+        """
+        # import re  <-- Removed
+
+        s = str(filename).strip().replace(" ", "_")
+        return re.sub(r'(?u)[^-\w.]', '', s)
+
+    @staticmethod
+    def _load_yaml(filepath: str) -> Dict[str, Any]:
+        if not os.path.exists(filepath):
+            raise FileNotFoundError(f"Configuration file not found: {filepath}")
+
+        try:
+            with open(filepath, 'r', encoding="utf-8") as f:
+                return yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML format in {filepath}: {e}") from e
+
+    @staticmethod
+    def _validate_rule(rule: Dict[str, Any], index: int):
+        sn = rule.get("serial_number")
+        if not sn:
+            raise ValueError(f"Rule #{index}: Missing 'serial_number'.")
+
+        zones = rule.get("redaction_zones", [])
+        if not isinstance(zones, list):
+            raise ValueError(f"Rule #{index} ({sn}): 'redaction_zones' must be a list.")
+
+        for z_idx, zone in enumerate(zones):
+            if isinstance(zone, list):
+                roi = zone
+            elif isinstance(zone, dict):
+                roi = zone.get("roi")
+            else:
+                raise ValueError(
+                    f"Rule #{index} ({sn}), Zone #{z_idx}: Invalid zone format (must be list or dict).")
+
+            if not roi or not isinstance(roi, list) or len(roi) != 4:
+                raise ValueError(
+                    f"Rule #{index} ({sn}), Zone #{z_idx}: ROI must be a list of 4 integers.")
+
+            r1, r2, c1, c2 = roi
+            if any(x < 0 for x in roi):
+                raise ValueError(
+                    f"Rule #{index} ({sn}), Zone #{z_idx}: ROI values must be non-negative.")
+
+            if r1 > r2 or c1 > c2:
+                raise ValueError(
+                    f"Rule #{index} ({sn}), Zone #{z_idx}: Invalid ROI logic (Start > End).")