scopexr 1.3.1__py3-none-any.whl

scopexr/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.3.1"

scopexr/arg_parser_fs.py

@@ -0,0 +1,221 @@
+# SCOPE-XR (Single-image Characterization Of PErformance in X-Ray systems)
+# Copyright (C) 2026  Jacopo Altieri
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import argparse
+import sys
+import yaml
+
+
+def get_merged_config() -> dict:
+    """
+    Parse command-line arguments and YAML configuration file,
+    merging them with the following priority:
+
+    1. Code defaults (lowest priority)
+    2. YAML config file
+    3. Command-line arguments (highest priority)
+
+    Returns
+    -------
+    dict
+        Merged configuration dictionary
+    """
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument(
+        "--config", type=str, default=r".\fs_args.yaml", help="Path to YAML config file"
+    )
+
+    # CLI arguments (short flags)
+    parser.add_argument("--f", type=str, help="Path to the image file (.raw/.png/.tif)")
+    parser.add_argument("--o", type=str, help="Output directory")
+    parser.add_argument("--p", type=float, help="Pixel size in mm")
+    parser.add_argument("--d", type=float, help="Circle diameter in mm")
+    parser.add_argument(
+        "--no_hough",
+        action="store_true",
+        default=None,
+        help="Skip Hough transform detection",
+    )
+    parser.add_argument("--m", type=float, help="Magnification")
+    parser.add_argument("--n", type=int, help="Minimum pixel count")
+    parser.add_argument("--nangles", type=int, help="Number of angles")
+    parser.add_argument("--hl", type=int, help="Half profile length")
+    parser.add_argument("--ds", type=int, help="Derivative step size")
+    parser.add_argument("--axis_shifts", type=int, help="Number of axis shift steps")
+    parser.add_argument("--filter", type=str, help="Reconstruction filter name")
+    parser.add_argument(
+        "--sym", action="store_true", default=None, help="Symmetrize the sinogram"
+    )
+    parser.add_argument("--show", action="store_true", default=None, help="Show plots")
+
+    shift_group = parser.add_mutually_exclusive_group()
+    shift_group.add_argument(
+        "--auto_shift",
+        action="store_true",
+        default=None,
+        help="Enable automatic sinogram centering.",
+    )
+    shift_group.add_argument(
+        "--manual_shift",
+        type=int,
+        default=None,
+        help="Provide a specific manual shift value (in pixels).",
+    )
+    shift_group.add_argument(
+        "--no_shift",
+        action="store_true",
+        default=None,
+        help="Disable all sinogram shifting.",
+    )
+
+    args, unknown = parser.parse_known_args()
+
+    # 1. Set code defaults (lowest priority)
+    config = {
+        "img_path": None,
+        "out_dir": "./output_fs",
+        "pixel_size": None,
+        "circle_diameter": None,
+        "magnification": None,  # Will be auto-calculated if None or 0
+        "min_n": 6,
+        "n_angles": 360,
+        "profile_half_length": 50,
+        "derivative_step": 1,
+        "axis_shifts": 10,
+        "filter_name": "ramp",
+        "auto_shift": True,
+        "manual_shift": None,
+        "no_shift": False,
+        "no_hough": False,
+        "symmetrize": False,
+        "show_plots": False,
+        "hough_params": {
+            "dp": 1,
+            "min_dist": 100,
+            "param1": 100,
+            "param2": 30,
+            "min_radius": 10,
+            "max_radius": 500,
+            "debug": False,
+        },
+    }
+
+    # 2. Load YAML config (overwrites code defaults)
+    try:
+        with open(args.config, "r") as f:
+            yaml_config = yaml.safe_load(f)
+            if yaml_config:
+                config.update(yaml_config)
+    except FileNotFoundError:
+        print(
+            f"Warning: Config file not found at {args.config}. Using defaults.",
+            file=sys.stderr,
+        )
+    except Exception as e:
+        print(f"Error loading YAML config: {e}", file=sys.stderr)
+
+    # 3. Load CLI arguments (highest priority)
+    cli_to_config_keys = {
+        "f": "img_path",
+        "o": "out_dir",
+        "p": "pixel_size",
+        "d": "circle_diameter",
+        "no_hough": "no_hough",
+        "m": "magnification",
+        "n": "min_n",
+        "nangles": "n_angles",
+        "hl": "profile_half_length",
+        "ds": "derivative_step",
+        "axis_shifts": "axis_shifts",
+        "filter": "filter_name",
+        "sym": "symmetrize",
+        "show": "show_plots",
+        "auto_shift": "auto_shift",
+        "manual_shift": "manual_shift",
+        "no_shift": "no_shift",
+    }
+
+    cli_dict = vars(args)
+
+    for cli_key, config_key in cli_to_config_keys.items():
+        cli_value = cli_dict.get(cli_key)
+        # Only update if the CLI argument was *actually* given
+        if cli_value is not None:
+            config[config_key] = cli_value
+
+    # ---
+    # Check which CLI flag was *actually passed* (from cli_dict)
+    # and enforce priority.
+    # ---
+    if cli_dict.get("manual_shift") is not None:
+        # CLI --manual_shift was used
+        config["auto_shift"] = False
+        config["no_shift"] = False
+        config["manual_shift"] = cli_dict.get("manual_shift")
+    elif cli_dict.get("auto_shift") is True:
+        # CLI --auto_shift was used
+        config["auto_shift"] = True
+        config["no_shift"] = False
+        config["manual_shift"] = None
+    elif cli_dict.get("no_shift") is True:
+        # CLI --no_shift was used
+        config["auto_shift"] = False
+        config["no_shift"] = True
+        config["manual_shift"] = None
+    # If no CLI shift flag was passed, the config (from YAML or default) is used as-is.
+
+    return config
+
+
+def validate_args(args: dict) -> None:
+    """
+    Validate the merged configuration arguments.
+    Parameters
+    ----------
+    args
+        Merged configuration dictionary
+
+    Raises
+    ------
+    ValueError
+        If any argument is invalid
+    """
+    if not args.get("img_path"):
+        raise ValueError("Image path is required. Use --f to specify the image file.")
+    if args.get("pixel_size") is None or args["pixel_size"] <= 0:
+        raise ValueError("Pixel size must be a positive number.")
+    if args.get("circle_diameter") is None or args["circle_diameter"] <= 0:
+        raise ValueError("Circle diameter must be a positive number.")
+    if args.get("magnification") is not None and args["magnification"] < 0:
+        raise ValueError(
+            "Magnification must be a positive number or 0 for automatic calculation."
+        )
+    if args.get("min_n") is None or args["min_n"] <= 0:
+        raise ValueError("Minimum pixel count must be a positive integer.")
+    if args.get("n_angles") is None or args["n_angles"] <= 0:
+        raise ValueError("Number of angles must be a positive integer.")
+    if args.get("profile_half_length") is None or args["profile_half_length"] <= 0:
+        raise ValueError("Half profile length must be a positive integer.")
+    if args.get("derivative_step") is None or args["derivative_step"] <= 0:
+        raise ValueError("Derivative step size must be a positive integer.")
+    if args.get("axis_shifts") is None or args["axis_shifts"] < 0:
+        raise ValueError("Axis shifts must be a non-negative integer.")
+
+    if args.get("manual_shift") is not None and not isinstance(
+        args["manual_shift"], int
+    ):
+        raise ValueError("Manual shift must be an integer.")

scopexr/arg_parser_psf.py

@@ -0,0 +1,276 @@
+# SCOPE-XR (Single-image Characterization Of PErformance in X-Ray systems)
+# Copyright (C) 2026  Jacopo Altieri
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import argparse
+import sys
+import yaml
+
+
+def get_merged_config() -> dict:
+    """
+    Parse command-line arguments and YAML configuration file,
+    merging them with the following priority:
+
+    1. Code defaults (lowest priority)
+    2. YAML config file
+    3. Command-line arguments (highest priority)
+
+    Returns
+    -------
+    dict
+        Merged configuration dictionary
+    """
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=r".\psf_args.yaml",
+        help="Path to YAML config file",
+    )
+
+    # CLI arguments
+    parser.add_argument("--f", type=str, help="Path to the image file (.raw/.png/.tif)")
+    parser.add_argument("--o", type=str, help="Output directory")
+    parser.add_argument("--p", type=float, help="Pixel size in mm")
+    parser.add_argument("--d", type=float, help="Circle diameter in mm")
+    parser.add_argument(
+        "--no_hough",
+        action="store_true",
+        default=None,
+        help="Skip Hough transform detection",
+    )
+    parser.add_argument("--nangles", type=int, help="Number of angles")
+    parser.add_argument("--hl", type=int, help="Half profile length")
+    parser.add_argument("--ds", type=int, help="Derivative step size")
+    parser.add_argument("--axis_shifts", type=int, help="Number of axis shift steps")
+    parser.add_argument("--filter", type=str, help="Reconstruction filter name")
+    parser.add_argument(
+        "--sym", action="store_true", default=None, help="Symmetrize the sinogram"
+    )
+    parser.add_argument(
+        "--dtheta",
+        type=float,
+        help="Angle of circular sector for oversampling in degrees",
+    )
+    parser.add_argument(
+        "--oversampling_factor",
+        type=float,
+        help="Resample factor for oversampling (final grid spacing).",
+    )
+    parser.add_argument(
+        "--gaussian_sigma",
+        type=float,
+        help="Standard deviation of the Gaussian blur for oversampling. Set to 0 for traditional binned statistics (no blur), >0 for 3-step with Gaussian smoothing.",
+    )
+    parser.add_argument("--show", action="store_true", default=None, help="Show plots")
+
+    shift_group = parser.add_mutually_exclusive_group()
+    shift_group.add_argument(
+        "--auto_shift",
+        action="store_true",
+        default=None,
+        help="Enable automatic sinogram centering.",
+    )
+    shift_group.add_argument(
+        "--manual_shift",
+        type=int,
+        default=None,
+        help="Provide a specific manual shift value (in pixels).",
+    )
+    shift_group.add_argument(
+        "--no_shift",
+        action="store_true",
+        default=None,
+        help="Disable all sinogram shifting.",
+    )
+
+    oversample_group = parser.add_mutually_exclusive_group()
+    oversample_group.add_argument(
+        "--oversample",
+        dest="oversample",
+        action="store_true",
+        default=None,
+        help="Enable oversampling",
+    )
+    oversample_group.add_argument(
+        "--no_oversample",
+        dest="oversample",
+        action="store_false",
+        default=None,
+        help="Disable oversampling",
+    )
+
+    args, unknown = parser.parse_known_args()
+
+    # 1. Set code defaults (lowest priority)
+    config = {
+        "img_path": None,
+        "out_dir": "./output_psf",
+        "pixel_size": 0.1,
+        "circle_diameter": 100,
+        "no_hough": False,
+        "n_angles": 360,
+        "profile_half_length": 50,
+        "derivative_step": 1,
+        "axis_shifts": 10,
+        "manual_shift": None,
+        "filter_name": "ramp",
+        "symmetrize": False,
+        "auto_shift": True,
+        "no_shift": False,
+        "oversample": False,
+        "dtheta": 2,
+        "oversampling_factor": 4,
+        "gaussian_sigma": 0.0,
+        "show_plots": False,
+        "hough_params": {
+            "dp": 1,
+            "min_dist": 100,
+            "param1": 100,
+            "param2": 40,
+            "min_radius": 100,
+            "max_radius": 0,
+            "debug": False,
+        },
+    }
+
+    # 2. Load YAML config (overwrites code defaults)
+    try:
+        with open(args.config, "r") as f:
+            yaml_config = yaml.safe_load(f)
+            if yaml_config:
+                config.update(yaml_config)
+                
+            # === BACKWARDS COMPATIBILITY FOR RESAMPLE2 ===
+            if "resample2" in yaml_config:
+                print(
+                    f"Notice: Config file '{args.config}' uses the deprecated key 'resample2'.\n"
+                    f"        Please update it to 'oversampling_factor' when possible.\n",
+                    file=sys.stderr,
+                )
+                # If they didn't explicitly provide the new key, map the old key's value to it
+                if "oversampling_factor" not in yaml_config:
+                    yaml_config["oversampling_factor"] = yaml_config["resample2"]
+
+            config.update(yaml_config)
+            
+    except FileNotFoundError:
+        print(
+            f"Warning: Config file not found at {args.config}. Using defaults.",
+            file=sys.stderr,
+        )
+    except Exception as e:
+        print(f"Error loading YAML config: {e}", file=sys.stderr)
+
+    # 3. Load CLI arguments (highest priority)
+    cli_to_config_keys = {
+        "f": "img_path",
+        "o": "out_dir",
+        "p": "pixel_size",
+        "d": "circle_diameter",
+        "no_hough": "no_hough",
+        "nangles": "n_angles",
+        "hl": "profile_half_length",
+        "ds": "derivative_step",
+        "axis_shifts": "axis_shifts",
+        "filter": "filter_name",
+        "sym": "symmetrize",
+        "show": "show_plots",
+        "oversample": "oversample",
+        "dtheta": "dtheta",
+        "oversampling_factor": "oversampling_factor",
+        "gaussian_sigma": "gaussian_sigma",
+        "auto_shift": "auto_shift",
+        "manual_shift": "manual_shift",
+        "no_shift": "no_shift",
+    }
+
+    cli_dict = vars(args)
+
+    for cli_key, config_key in cli_to_config_keys.items():
+        cli_value = cli_dict.get(cli_key)
+        # Only update if the CLI argument was *actually* given
+        if cli_value is not None:
+            config[config_key] = cli_value
+
+    # Check which CLI flags were *actually passed*
+    cli_manual_shift = cli_dict.get("manual_shift")
+    cli_auto_shift = cli_dict.get("auto_shift")
+    cli_no_shift = cli_dict.get("no_shift")
+
+    if cli_manual_shift is not None:
+        # CLI --manual_shift was used
+        config["auto_shift"] = False
+        config["no_shift"] = False
+        config["manual_shift"] = cli_manual_shift
+    elif cli_auto_shift is True:
+        # CLI --auto_shift was used
+        config["auto_shift"] = True
+        config["no_shift"] = False
+        config["manual_shift"] = None
+    elif cli_no_shift is True:
+        # CLI --no_shift was used
+        config["auto_shift"] = False
+        config["no_shift"] = True
+        config["manual_shift"] = None
+    # If no CLI shift flag was passed, the config (from YAML or default) is used as-is.
+
+    return config
+
+
+def validate_args(args: dict) -> None:
+    """
+    Validate the merged configuration arguments.
+    Parameters
+    ----------
+    args
+        Merged configuration dictionary
+
+    Raises
+    ------
+    ValueError
+        If any argument is invalid
+    """
+    if not args.get("img_path"):
+        raise ValueError("Image path is required. Use --f to specify the image file.")
+    if args.get("pixel_size") is None or args["pixel_size"] <= 0:
+        raise ValueError("Pixel size must be a positive number.")
+    if args.get("circle_diameter") is None or args["circle_diameter"] <= 0:
+        raise ValueError("Circle diameter must be a positive number.")
+    if args.get("n_angles") is None or args["n_angles"] <= 0:
+        raise ValueError("Number of angles must be a positive integer.")
+    if args.get("profile_half_length") is None or args["profile_half_length"] <= 0:
+        raise ValueError("Half profile length must be a positive integer.")
+    if args.get("derivative_step") is None or args["derivative_step"] <= 0:
+        raise ValueError("Derivative step size must be a positive integer.")
+
+    if args.get("manual_shift") is not None and not isinstance(
+        args["manual_shift"], int
+    ):
+        raise ValueError("Manual shift must be an integer.")
+
+    # Validation for oversampling args
+    if args.get("oversample"):
+        if args.get("dtheta") is None or args["dtheta"] <= 0:
+            raise ValueError("dtheta must be a positive number for oversampling.")
+        if args.get("oversampling_factor") is None or args["oversampling_factor"] <= 0:
+            raise ValueError(
+                "oversampling_factor must be a positive number for oversampling."
+            )
+        # gaussian_sigma can be None (treated as 0) or any non-negative number
+        if args.get("gaussian_sigma") is not None and args["gaussian_sigma"] < 0:
+            raise ValueError("gaussian_sigma must be non-negative for oversampling.")

scopexr/circle_detection.py

@@ -0,0 +1,178 @@
+# SCOPE-XR (Single-image Characterization Of PErformance in X-Ray systems)
+# Copyright (C) 2026  Jacopo Altieri
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import cv2
+import numpy as np
+from scipy.ndimage import center_of_mass
+
+
+def detect_circle_hough(
+    img: np.ndarray,
+    dp: float,
+    min_dist: float,
+    param1: int,
+    param2: int,
+    min_radius: int,
+    max_radius: int,
+    output_path: str = None,
+    debug: bool = False,
+) -> tuple[float, float, float] | None:
+    """
+    Detect a single circle in a grayscale image using the Hough Circle Transform.
+
+    Parameters
+    ----------
+    img
+        2D array representing the input grayscale image.
+    dp
+        Inverse ratio of the accumulator resolution to the image resolution.
+        For example, dp=1 means the accumulator has the same resolution as the image.
+    min_dist
+        Minimum distance between the centers of detected circles (in pixels).
+    param1
+        Higher threshold for the internal Canny edge detector (lower is half).
+    param2
+        Accumulator threshold for the circle centers at the detection stage.
+        Smaller values will detect more circles (including false ones).
+    min_radius
+        Minimum circle radius (in pixels) to search for.
+    max_radius
+        Maximum circle radius (in pixels) to search for. If <= 0, no upper limit is applied.
+    debug
+        If True, display the detected circle overlaid on the image in a pop-up window.
+        Defaults to False.
+
+    Returns
+    -------
+    x: float
+        x coordinate of the detected circle center.
+    y: float
+        y coordinate of the detected circle center.
+    r: float
+        radius of the detected circle.
+    None
+        If no circle is found.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the input `img` is None.
+    """
+    if img is None:
+        raise FileNotFoundError(f"Could not open '{img}'")
+    p1 = np.percentile(img, 1)
+    p99 = np.percentile(img, 99)
+    img_clipped = np.clip(img, p1, p99)
+
+    # Normalize to 0-255
+    img_8bit = ((img_clipped - p1) / (p99 - p1) * 255).astype(np.uint8)
+    blurred = cv2.medianBlur(img_8bit, 5)
+
+    # Perform Hough Circle Transform
+    circles = cv2.HoughCircles(
+        blurred,
+        cv2.HOUGH_GRADIENT,
+        dp=dp,
+        minDist=min_dist,
+        param1=param1,
+        param2=param2,
+        minRadius=min_radius,
+        maxRadius=max_radius if max_radius > 0 else None,
+    )
+
+    if circles is None:
+        print("No circles found")
+        return None
+
+    # Round and pick the strongest circle (first one)
+    circles = np.uint16(np.around(circles))
+    x, y, r = circles[0][0]
+
+    output = cv2.cvtColor(img_8bit, cv2.COLOR_GRAY2BGR)
+    cv2.circle(output, (x, y), r, (0, 255, 0), 2)
+    cv2.circle(output, (x, y), 2, (0, 0, 255), 3)
+    cv2.imwrite(f"{output_path}/detected_circle.png", output)
+
+    if debug:
+        display_scale = 0.5
+        output_resized = cv2.resize(output, (0, 0), fx=display_scale, fy=display_scale)
+        cv2.imshow("Detected Circle", output_resized)
+        cv2.waitKey(0)
+        cv2.destroyAllWindows()
+
+    return x, y, r
+
+
+def estimate_circle(cropped: np.ndarray) -> tuple[float, float, float]:
+    """
+    Estimate circle parameters using Center of Mass and Equivalent Area.
+
+    Methods:
+    - Center (cx, cy): Calculated via center_of_mass on the binary mask.
+    - Radius: Calculated from the area (Area = pi * r^2).
+    """
+    h, w = cropped.shape
+
+    # 1. Thresholding to create a binary mask
+    # We use a float cast to avoid overflow during min/max calc
+    img_float = cropped.astype(np.float32)
+    threshold = (np.min(img_float) + np.max(img_float)) / 2.0
+
+    mask = img_float >= threshold
+
+    # Handle empty image case
+    if not np.any(mask):
+        return w / 2.0, h / 2.0, 0.0
+
+    # 2. Calculate Center (y, x)
+    # This uses all pixels in the mask to find the geometric centroid
+    cy, cx = center_of_mass(mask)
+
+    # 3. Calculate Radius from Area (i.e., number of pixels in the mask)
+    # Area = pi * r^2  ->  r = sqrt(Area / pi)
+    area = np.sum(mask)
+    radius_estimate = np.sqrt(area / np.pi)
+
+    return float(cx), float(cy), float(radius_estimate)
+
+
+def is_circle_centered(
+    cropped: np.ndarray, cx: float, cy: float, margin: float = 0.1
+) -> bool:
+    """
+    Check if the estimated circle center is within `margin` of the cropped image center
+    in both the x- and y-directions. Returns True if it is, False otherwise.
+
+    Parameters
+    ----------
+    cropped
+        cropped image containing the circle
+    cx
+        x coordinate of the estimated circle center
+    cy
+        y coordinate of the estimated circle center
+    margin
+        allowable fraction of width/height (default 0.1)
+
+    Returns
+    -------
+    bool
+        True if the circle center is within the margin from the image center
+    """
+    h, w = cropped.shape[:2]
+    center_x, center_y = w / 2, h / 2
+
+    return (abs(cx - center_x) < margin * w) and (abs(cy - center_y) < margin * h)