sigima 0.0.1.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

sigima/io/common/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Common I/O features
+"""

sigima/io/common/basename.py

@@ -0,0 +1,164 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""Common functions for file name handling."""
+
+from __future__ import annotations
+
+import re
+import string
+import sys
+import unicodedata
+from typing import Any, Iterable
+
+from sigima.objects.image import ImageObj
+from sigima.objects.signal import SignalObj
+
+
+class CustomFormatter(string.Formatter):
+    """Custom string formatter to handle uppercase and lowercase strings."""
+
+    def format_field(self, value, format_spec):
+        """Format the given `value` according to the specified `format_spec`.
+
+        If the value is a string and the format_spec ends with 'upper' or 'lower',
+        convert the value to uppercase or lowercase, respectively, and remove the
+        suffix from `format_spec` before formatting.
+
+        Args:
+            value: Value to format.
+            format_spec: Format specification, may end with 'upper' or 'lower'.
+
+        Returns:
+            The formatted value.
+
+        Raises:
+            ValueError: If `format_spec` is invalid.
+        """
+        # Ignore dict objects silently (metadata should only be accessed via keys)
+        if isinstance(value, dict):
+            return ""
+        if isinstance(value, str):
+            if format_spec.endswith("upper"):
+                value = value.upper()
+                format_spec = format_spec[:-5]
+            elif format_spec.endswith("lower"):
+                value = value.lower()
+                format_spec = format_spec[:-5]
+        return super().format_field(value, format_spec)
+
+
+def format_basenames(
+    objects: Iterable[SignalObj | ImageObj],
+    fmt: str,
+    replacement: str = "_",
+) -> list[str]:
+    """Generate sanitized filenames for SignalObj or ImageObj instances.
+
+    Format each object's name using the provided Python format string, then sanitize
+    the result for safe use as a filename. The format string may reference any of:
+        - {title}: object title
+        - {index}: 1-based index
+        - {count}: total number of objects
+        - {xlabel}, {xunit}, {ylabel}, {yunit}: axis labels/units (if present)
+        - {metadata[key]}: specific metadata value
+          (direct {metadata} use is silently ignored)
+
+    Args:
+        objects: Objects to name.
+        fmt: Python format string for naming.
+        replacement: Replacement for invalid filename characters.
+
+    Returns:
+        Sanitized filenames for each object.
+
+    Raises:
+        KeyError: If the format string references an unknown placeholder.
+    """
+    result: list[str] = []
+    formatter = CustomFormatter()
+    for i, obj in enumerate(objects):
+        # Note: We provide metadata dict only for {metadata[key]} access,
+        # not for direct {metadata} use (which would create overly long filenames)
+        metadata = getattr(obj, "metadata", {})
+        context: dict[str, Any] = {
+            "title": getattr(obj, "title", ""),
+            "index": i + 1,
+            "count": len(list(objects)),
+            # Attributes may not exist on all objects.
+            "xlabel": getattr(obj, "xlabel", ""),
+            "xunit": getattr(obj, "xunit", ""),
+            "ylabel": getattr(obj, "ylabel", ""),
+            "yunit": getattr(obj, "yunit", ""),
+            "metadata": metadata,
+        }
+        try:
+            formatted = formatter.format(fmt, **context)
+        except KeyError as exc:
+            missing = str(exc.args[0]) if exc.args else str(exc)
+            raise KeyError(f"Unknown format key in fmt: {missing!r}") from exc
+        except ValueError as exc:
+            # Re-raise with more context about which object failed
+            raise ValueError(
+                f"Invalid format string '{fmt}' for object '{context['title']}': {exc}"
+            ) from exc
+        # Sanitize final result to ensure it's a safe basename.
+        result.append(sanitize_basename(formatted, replacement=replacement))
+    return result
+
+
+def sanitize_basename(basename: str, replacement: str = "_") -> str:
+    """Sanitize a string to create a valid basename for the current operating system.
+
+    This function removes or replaces characters that are invalid in basenames,
+    depending on the underlying OS (Windows, macOS, Linux). It also strips trailing dots
+    and spaces on Windows and normalizes unicode characters.
+
+    Args:
+        basename: Input string.
+        replacement: Replacement string for invalid characters (default: "_").
+
+    Returns:
+        A sanitized string that can safely be used as a basename.
+    """
+    # Normalize unicode characters (NFKD form for decomposing accents and the like).
+    basename = unicodedata.normalize("NFKD", basename)
+    basename = basename.encode("ascii", "ignore").decode("ascii")
+
+    # Characters not allowed in filenames (platform-dependent).
+    if sys.platform.startswith("win"):
+        # Reserved characters on Windows.
+        invalid_chars = r'[<>:"/\\|?*\x00-\x1F]'
+        reserved_names = {
+            "CON",
+            "PRN",
+            "AUX",
+            "NUL",
+            *(f"COM{i}" for i in range(1, 10)),
+            *(f"LPT{i}" for i in range(1, 10)),
+        }
+    else:
+        # Only '/' is disallowed on Unix-based systems.
+        invalid_chars = r"/"
+        reserved_names = set()
+
+    # Replace invalid characters.
+    sanitized = re.sub(invalid_chars, replacement, basename)
+
+    # Strip leading/trailing whitespace.
+    sanitized = sanitized.strip()
+    # On Windows, also strip trailing dots and spaces.
+    if sys.platform.startswith("win"):
+        sanitized = sanitized.rstrip(" .")
+
+    # Truncate to a reasonable length to avoid OS path issues.
+    sanitized = sanitized[:255]
+
+    # Avoid reserved basenames.
+    if sanitized.upper() in reserved_names:
+        sanitized += "_"
+
+    # If result is empty, fallback to a default name.
+    if not sanitized:
+        sanitized = "unnamed"
+
+    return sanitized

sigima/io/common/converters.py

@@ -0,0 +1,189 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+I/O conversion functions
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+import numpy as np
+import skimage
+
+
+def dtypes_to_sorted_short_codes(
+    dtypes: Sequence[Any], kind_filter: str | None = None
+) -> list[str]:
+    """Return sorted short dtype codes for numeric dtypes.
+
+    Convert each input to a numpy dtype and ignore non-numeric types.
+    Order:
+      - Integer types first, unsigned (and boolean) before signed,
+        sorted by itemsize ascending.
+      - floats numeric types, sorted by itemsize ascending.
+      - complex numeric types, sorted by itemsize ascending.
+
+    Short codes use numpy kind letter plus itemsize in bytes, e.g. "u1", "i2",
+    "f8".
+
+    Args:
+        dtypes: Sequence of objects acceptable by numpy.dtype (dtype, str, etc.)
+        kind_filter: String of dtype kind letters to keep, e.g. "iu" for
+         unsigned/signed integers. If empty or None, keep all numeric types
+
+    Returns:
+        List of unique short dtype codes in the requested order.
+    """
+    dtypes = [np.dtype(d).str[1:] for d in dtypes]
+    ordered: list[np.dtype] = []
+
+    if kind_filter is None:
+        kind_filter = "iubfc"  # all numeric types
+    assert kind_filter != "", "kind_filter cannot be empty string"
+
+    # Standard dtype codes in desired order
+    bool_codes = ("b1",)
+    int_codes = ("u1", "i1", "u2", "i2", "u4", "i4", "u8", "i8")
+    float_codes = ("f2", "f4", "f8")
+    complex_codes = ("c8", "c16")
+
+    ordered = [
+        code
+        for code in bool_codes + int_codes + float_codes + complex_codes
+        if code in dtypes and code[0] in kind_filter
+    ]
+    return ordered
+
+
+def _convert_bool_array(array: np.ndarray) -> np.ndarray:
+    """Convert boolean array to uint8."""
+    return skimage.util.img_as_ubyte(array)
+
+
+def _convert_int_array(
+    array: np.ndarray, supported_data_types: tuple[np.dtype]
+) -> np.ndarray:
+    """Convert an integer array to a standard type.
+
+    Select the smallest supported integer dtype that can represent all values in the
+    array. If no suitable integer dtype is found, convert the array to a supported
+    float type.
+
+    Args:
+        array: Input numpy array of integer type.
+        supported_data_types: Tuple of supported numpy dtypes for destination object.
+
+    Returns:
+        Converted numpy array with the selected dtype.
+
+    Raises:
+        ValueError: If no supported dtype can represent the data.
+    """
+    ordered_codes = dtypes_to_sorted_short_codes(supported_data_types, kind_filter="iu")
+
+    amin = np.min(array) if array.size > 0 else 0
+    amax = np.max(array) if array.size > 0 else 0
+    for code in ordered_codes:
+        info = np.iinfo(code)
+        if amin >= info.min and amax <= info.max:
+            new_type = np.dtype(code).newbyteorder("=")
+            break
+    else:
+        new_type = _convert_float_array(array, supported_data_types).dtype
+
+    return array.astype(new_type, copy=False)
+
+
+def _convert_float_array(
+    array: np.ndarray, supported_data_types: tuple[np.dtype]
+) -> np.ndarray:
+    """Convert float/complex array to smallest allowed type at least large as current.
+
+    Choose the smallest supported dtype of the same kind ("f" for floats,
+    "c" for complex) whose itemsize is greater than or equal to the array's
+    itemsize. If no such type exists, fall back to the largest supported
+    dtype for that kind.
+
+    Args:
+        array: Array to convert.
+        supported_data_types: Sequence of allowed dtypes for the destination
+            object type.
+
+    Returns:
+        Converted array with the selected dtype. If no supported dtype of the
+        same kind exists, return the original array.
+    """
+    kind = array.dtype.kind
+    if kind in ["i", "u", "b"]:
+        kind = "f"  # convert integers to floats
+
+    itemsize = array.dtype.itemsize
+
+    ordered_codes = dtypes_to_sorted_short_codes(supported_data_types, kind_filter=kind)
+
+    # Filter out any codes that don't match the requested kind (defensive).
+    valid_codes: list[str] = []
+    for code in ordered_codes:
+        try:
+            dt = np.dtype(code)
+        except TypeError:
+            continue
+        if dt.kind == kind:
+            valid_codes.append(code)
+
+    if not valid_codes:
+        # No supported dtype for this kind, return original array.
+        raise ValueError("Unsupported data type")
+
+    # Find smallest supported type with itemsize >= current itemsize.
+    selected_code: str | None = None
+    for code in valid_codes:
+        dt = np.dtype(code)
+        if dt.itemsize >= itemsize:
+            selected_code = code
+            break
+    else:
+        # Fallback to the largest supported type for this kind.
+        selected_code = valid_codes[-1]
+
+    new_type = np.dtype(selected_code).newbyteorder("=")
+    return array.astype(new_type, copy=False)
+
+
+def convert_array_to_valid_dtype(
+    array: np.ndarray, valid_dtypes: tuple[np.dtype, ...]
+) -> np.ndarray:
+    """Convert array to the most appropriate valid dtype.
+
+    Converts arrays to one of the valid dtypes, choosing the most appropriate type
+    based on the input array's characteristics.
+
+    Args:
+        array: array to convert
+        valid_dtypes: tuple of valid dtypes
+
+    Returns:
+        Converted array with the most appropriate valid dtype.
+
+    Raises:
+        TypeError: if input is not a numpy ndarray
+        ValueError: if array dtype cannot be converted to any valid type
+    """
+    if not isinstance(array, np.ndarray):
+        raise TypeError("Input must be a numpy ndarray.")
+
+    if array.dtype in valid_dtypes:
+        return array
+
+    kind: str = array.dtype.kind
+    if kind in ["f", "c"]:
+        return _convert_float_array(array, valid_dtypes)
+    if kind == "b":
+        return _convert_bool_array(array)
+    if kind in ["i", "u"]:
+        return _convert_int_array(array, valid_dtypes)
+
+    raise ValueError("Unsupported data type")

sigima/io/common/objmeta.py

@@ -0,0 +1,181 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""Sigima I/O module for handling object metadata and ROIs."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from guidata.io import JSONHandler, JSONReader, JSONWriter
+
+from sigima.objects import ImageROI, SignalROI
+
+if TYPE_CHECKING:
+    from sigima.params import ROIGridParam
+
+FORMAT_TAG = "sigima"
+FORMAT_VERSION = "1.0"
+ROI_TYPE_FIELD = "roi_type"
+
+
+def _check_tag(data: dict, expected_format: str) -> None:
+    """Validate the presence and type of sigima tag.
+
+    Args:
+        data: The data dictionary to check.
+        expected_format: The expected format string for the tag.
+
+    Raises:
+        ValueError: If the tag is missing or does not match the expected format.
+    """
+    tag: dict = data.get(FORMAT_TAG, {})
+    if tag.get("format") != expected_format:
+        raise ValueError(f"Unexpected or missing format: {tag}")
+
+
+def write_dict(filepath: str, data: dict) -> None:
+    """Write a dictionary to a file in JSON format.
+
+    Args:
+        filepath: The file path to write the data to.
+        data: The dictionary to serialize.
+
+    Raises:
+        ValueError: If the data is not a dictionary.
+    """
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected a dictionary, got {type(data)}")
+    handler = JSONHandler(filepath)
+    handler.set_json_dict(data)
+    handler.save()
+
+
+def read_dict(filepath: str) -> dict:
+    """Read a dictionary from a file and return it.
+
+    Args:
+        filepath: The file path to read the data from.
+
+    Returns:
+        The dictionary read from the file.
+    """
+    handler = JSONHandler(filepath)
+    handler.load()
+    data = handler.get_json_dict()
+    return data
+
+
+def write_roi(filepath: str, roi: SignalROI | ImageROI) -> None:
+    """Write a signal or image ROI to a file in JSON format.
+
+    Args:
+        filepath: The file path to write the ROI data to.
+        roi: The signal or image ROI object to serialize.
+
+    Raises:
+        ValueError: If the ROI object is not of type SignalROI or ImageROI.
+    """
+    if isinstance(roi, SignalROI):
+        roi_type: Literal["signal", "image"] = "signal"
+    elif isinstance(roi, ImageROI):
+        roi_type = "image"
+    else:
+        raise ValueError(
+            f"Unsupported ROI type: {type(roi)}. Expected SignalROI or ImageROI."
+        )
+    roi_dict = roi.to_dict()
+    roi_dict[ROI_TYPE_FIELD] = roi_type
+    data = {
+        FORMAT_TAG: {"format": "roi", "version": FORMAT_VERSION},
+        "roi": roi_dict,
+    }
+    write_dict(filepath, data)
+
+
+def read_roi(filepath: str) -> SignalROI | ImageROI:
+    """Read ROI data from a file and return the corresponding ROI object.
+
+    Args:
+        filepath: The file path to read the ROI data from.
+
+    Returns:
+        The corresponding ROI object (SignalROI or ImageROI).
+
+    Raises:
+        ValueError: If the file does not contain the expected format.
+    """
+    json_dict = read_dict(filepath)
+    _check_tag(json_dict, expected_format="roi")
+    roi_dict = json_dict["roi"]
+    assert isinstance(roi_dict, dict), "ROI data must be a dictionary"
+    roi_type = roi_dict.pop(ROI_TYPE_FIELD, None)
+    if roi_type == "signal":
+        return SignalROI.from_dict(roi_dict)
+    if roi_type == "image":
+        return ImageROI.from_dict(roi_dict)
+    raise ValueError(f"Unsupported or missing ROI type: {roi_type}")
+
+
+def write_roi_grid(filepath: str, param: ROIGridParam) -> None:
+    """Write ROI grid parameters to a file in JSON format.
+
+    Args:
+        filepath: The file path to write the ROI grid parameters to.
+        param: The ROI grid parameters to serialize.
+    """
+    writer = JSONWriter(filepath)
+    param.serialize(writer)
+    print(writer.jsondata)
+    writer.save()
+
+
+def read_roi_grid(filepath: str) -> ROIGridParam:
+    """Read ROI grid parameters from a file in JSON format.
+
+    Args:
+        filepath: The file path to read the ROI grid parameters from.
+
+    Returns:
+        The ROI grid parameters read from the file.
+    """
+    from sigima.params import ROIGridParam  # pylint: disable=import-outside-toplevel
+
+    handler = JSONReader(filepath)
+    handler.load()
+    param = ROIGridParam()
+    param.deserialize(handler)
+    return param
+
+
+def write_metadata(filepath: str, metadata: dict[str, Any]) -> None:
+    """Write metadata to a file in JSON format.
+
+    Args:
+        filepath: The file path to write the metadata to.
+        metadata: The metadata dictionary to serialize.
+
+    Raises:
+        ValueError: If the object does not have a metadata attribute.
+    """
+    data = {
+        FORMAT_TAG: {"format": "metadata", "version": FORMAT_VERSION},
+        "metadata": metadata.copy(),
+    }
+    write_dict(filepath, data)
+
+
+def read_metadata(filepath: str) -> dict[str, Any]:
+    """Read metadata from a file and return the metadata dictionary.
+
+    Args:
+        filepath: The file path to read the metadata from.
+
+    Returns:
+        The metadata dictionary.
+
+    Raises:
+        ValueError: If the file does not contain the expected format.
+    """
+    json_dict = read_dict(filepath)
+    _check_tag(json_dict, expected_format="metadata")
+    return json_dict["metadata"]

sigima/io/common/textreader.py

@@ -0,0 +1,58 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""I/O utility functions."""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y...
+
+from __future__ import annotations
+
+import os
+from itertools import islice
+
+from sigima.io.enums import FileEncoding
+
+
+def count_lines(filename: str | os.PathLike[str]) -> int:
+    """Count the number of lines in a file.
+
+    Args:
+        filename: File name or path.
+
+    Returns:
+        The number of lines in the file.
+
+    Raises:
+        IOError: If the file cannot be read.
+    """
+    for encoding in FileEncoding:
+        try:
+            with open(filename, "r", encoding=encoding) as file:
+                line_count = sum(1 for _ in file)
+            return line_count
+        except UnicodeDecodeError:
+            # Try next encoding.
+            pass
+    raise IOError(f"Cannot read file {filename}.")
+
+
+def read_first_n_lines(filename: str | os.PathLike[str], n: int = 100000) -> str:
+    """Read the first `n` lines of a file.
+
+    Args:
+        filename: File name or path.
+        n: Number of lines to read.
+
+    Returns:
+        The first `n` lines of the file.
+
+    Raises:
+        IOError: If the file cannot be read.
+    """
+    for encoding in FileEncoding:
+        try:
+            with open(filename, "r", encoding=encoding) as file:
+                return "".join(islice(file, n))
+        except UnicodeDecodeError:
+            # Try next encoding.
+            pass
+    raise IOError(f"Cannot read file {filename}.")