Axes

def validate_axes(axes: str) -> str:
    """Validate a 3-character axis string.

    Args:
        axes: Axis string to validate.

    Returns:
        The validated string (unchanged).

    Raises:
        ValueError: If the string is not a valid axis specification.
    """
    if len(axes) != 3:
        msg = f"Axis string must be 3 characters, got {len(axes)}: {axes!r}"
        raise ValueError(msg)
    if _is_voxel(axes) or _is_anatomical(axes):
        return axes
    msg = (
        f"Invalid axis string {axes!r}. Must be a permutation of 'IJK'"
        " (voxel) or one letter from each anatomical pair"
        " {R,L}, {A,P}, {S,I}."
    )
    raise ValueError(msg)

def axes_type(axes: str) -> AxesType:
    """Return whether *axes* is a voxel or anatomical axis string.

    The string must already be valid (call
    [`validate_axes`][torchio.data.axes.validate_axes] first).
    """
    if _is_voxel(axes):
        return AxesType.VOXEL
    return AxesType.ANATOMICAL

def get_axis_mapping(
    src: str,
    tgt: str,
) -> tuple[tuple[int, int, int], tuple[bool, bool, bool]]:
    """Compute the column permutation and flips to go from *src* to *tgt*.

    Both strings must be the same type (both voxel or both anatomical).

    Args:
        src: Source axis string.
        tgt: Target axis string.

    Returns:
        A tuple `(permutation, flips)` where *permutation* gives the
        source column index for each target column and *flips* indicates
        whether each target column should be negated.

    Raises:
        ValueError: If the two strings are not the same type.
    """
    src_type = axes_type(src)
    tgt_type = axes_type(tgt)
    if src_type != tgt_type:
        msg = (
            f"Cannot compute axis mapping between different types:"
            f" {src!r} ({src_type.value}) and {tgt!r} ({tgt_type.value})."
            " Use the affine to convert between voxel and anatomical."
            " Both must be the same type."
        )
        raise ValueError(msg)

    if src_type == AxesType.VOXEL:
        return _voxel_mapping(src, tgt)
    return _anatomical_mapping(src, tgt)