Module: micpy.geo¶

def build(
    filename: str, shape: Tuple[int, int, int], spacing: Tuple[float, float, float]
) -> Tuple[str, dict, Type]:
    """Create a basic geometry.

    Args:
        filename (str): Filename of a binary file.
        shape (tuple): Shape of the geometry (z, y, x).
        spacing (tuple): Spacing of the geometry (dz, dy, dx) in μm.
    """
    geo_filename = _get_basename(Path(filename)).with_suffix(".geoF")
    geo_data = {
        "basic_header": 24,
        "shape": shape,
        "spacing": spacing,
        "basic_footer": 24,
    }
    return geo_filename, geo_data

def find(filename: str) -> Path:
    """Find the geometry file for a given binary file.

    This method assumes that (a) both files share a common basename and (b) the
    file extension of the geometry file starts with either `.geoF` or `_geoF`.

    Args:
        filename (str): Filename of a binary file.

    Returns:
        Path to the geometry file.
    """
    basename = _get_basename(Path(filename))
    matches = list(basename.parent.glob(f"{basename.name}[._]geoF*"))

    if not matches:
        raise GeometryFileNotFoundError("Geometry file not found")

    first_match, *other_matches = matches
    if other_matches:
        raise MultipleGeometryFilesError("Multiple geometry files found")

    return Path(first_match)

def read(filename: str, type: Type = Type.EXTENDED, compressed: bool = True) -> dict:
    """Read a geometry file.

    Args:
        filename (str): Filename of a geometry file.
        type (Type, optional): Data type to be read. Defaults to `Type.EXTENDED`.
        compressed (bool, optional): True if file is compressed, False otherwise.
            Defaults to `True`.

    Returns:
        Dictionary representation of the geometry file.
    """
    array_data = read_ndarray(filename, type, compressed)
    return _ndarray_to_dict(array_data)

def read_ndarray(
    filename: str, type: Type = Type.EXTENDED, compressed: bool = True
) -> ndarray:
    """Read a geometry file.

    Args:
        filename (str): Filename of a geometry file.
        type (Type, optional): Data type to be read. Defaults to `Type.EXTENDED`.
        compressed (bool, optional): `True` if file is compressed, `False` otherwise.
            Defaults to `True`.

    Returns:
        NumPy array representation of the geometry file.
    """
    opener = gzip.open if compressed else open
    with opener(filename, "rb") as f:
        return np.frombuffer(f.read(type.value.itemsize), dtype=type.value)

def write(
    filename: str,
    data: dict,
    type: Type = Type.EXTENDED,
    compressed: bool = True,
):
    """Write a geometry file.

    Args:
        filename (str): Filename of a geometry file.
        data (dict): Dictionary representation of a geometry file.
        type (Type, optional): Data type to be written. Defaults to `Type.EXTENDED`.
        compressed (bool, optional): `True` if file should be compressed, `False`
            otherwise. Defaults to `True`.
    """
    array_data = _dict_to_ndarray(data, type)
    write_ndarray(filename, array_data, compressed)

def write_ndarray(filename: str, data: ndarray, compressed: bool = True):
    """Write a geometry file.

    Args:
        filename (str): Filename of a geometry file.
        data (ndarray): NumPy array representation of a geometry file.
        compressed (bool, optional): `True` if file should be compressed, `False`
            otherwise. Defaults to `True`.
    """
    if not _validate_data_type(data):
        raise ValueError("Invalid data type")
    if not _validate_header_footer(data):
        raise ValueError("Mismatched header and footer sizes")

    opener = gzip.open if compressed else open
    with opener(filename, mode="wb") as f:
        f.write(data.tobytes())