imops 0.8.8__cp38-cp38-manylinux_2_17_i686.manylinux2014_i686.whl

imops/numeric.py

@@ -0,0 +1,384 @@
+from typing import Callable, Sequence, Union
+
+import numpy as np
+
+from .backend import BackendLike, resolve_backend
+from .src._fast_numeric import (
+    _copy_3d as cython_fast_copy_3d,
+    _copy_3d_fp16 as cython_fast_copy_3d_fp16,
+    _copy_4d as cython_fast_copy_4d,
+    _copy_4d_fp16 as cython_fast_copy_4d_fp16,
+    _fill_3d as cython_fast_fill_3d,
+    _fill_4d as cython_fast_fill_4d,
+    _pointwise_add_array_3d as cython_fast_pointwise_add_array_3d,
+    _pointwise_add_array_3d_fp16 as cython_fast_pointwise_add_array_3d_fp16,
+    _pointwise_add_array_4d as cython_fast_pointwise_add_array_4d,
+    _pointwise_add_array_4d_fp16 as cython_fast_pointwise_add_array_4d_fp16,
+    _pointwise_add_value_3d as cython_fast_pointwise_add_value_3d,
+    _pointwise_add_value_3d_fp16 as cython_fast_pointwise_add_value_3d_fp16,
+    _pointwise_add_value_4d as cython_fast_pointwise_add_value_4d,
+    _pointwise_add_value_4d_fp16 as cython_fast_pointwise_add_value_4d_fp16,
+)
+from .src._numeric import (
+    _copy_3d as cython_copy_3d,
+    _copy_3d_fp16 as cython_copy_3d_fp16,
+    _copy_4d as cython_copy_4d,
+    _copy_4d_fp16 as cython_copy_4d_fp16,
+    _fill_3d as cython_fill_3d,
+    _fill_4d as cython_fill_4d,
+    _pointwise_add_array_3d as cython_pointwise_add_array_3d,
+    _pointwise_add_array_3d_fp16 as cython_pointwise_add_array_3d_fp16,
+    _pointwise_add_array_4d as cython_pointwise_add_array_4d,
+    _pointwise_add_array_4d_fp16 as cython_pointwise_add_array_4d_fp16,
+    _pointwise_add_value_3d as cython_pointwise_add_value_3d,
+    _pointwise_add_value_3d_fp16 as cython_pointwise_add_value_3d_fp16,
+    _pointwise_add_value_4d as cython_pointwise_add_value_4d,
+    _pointwise_add_value_4d_fp16 as cython_pointwise_add_value_4d_fp16,
+)
+from .utils import normalize_num_threads
+
+
+_TYPES = (np.int16, np.int32, np.int64, np.float16, np.float32, np.float64)
+_STR_TYPES = ('int16', 'int32', 'int64', 'float16', 'float32', 'float64')
+# TODO: Decide which value to use. Functions below are quite fast and simple, so parallelization overhead is noticeable.
+_NUMERIC_DEFAULT_NUM_THREADS = 4
+
+
+# TODO: Maybe dict is better?
+def _choose_cython_pointwise_add(ndim: int, summand_is_array: bool, is_fp16: bool, fast: bool) -> Callable:
+    assert ndim <= 4, ndim
+
+    if ndim <= 3:
+        if summand_is_array:
+            if is_fp16:
+                return cython_fast_pointwise_add_array_3d_fp16 if fast else cython_pointwise_add_array_3d_fp16
+
+            return cython_fast_pointwise_add_array_3d if fast else cython_pointwise_add_array_3d
+
+        if is_fp16:
+            return cython_fast_pointwise_add_value_3d_fp16 if fast else cython_pointwise_add_value_3d_fp16
+
+        return cython_fast_pointwise_add_value_3d if fast else cython_pointwise_add_value_3d
+
+    if summand_is_array:
+        if is_fp16:
+            return cython_fast_pointwise_add_array_4d_fp16 if fast else cython_pointwise_add_array_4d_fp16
+
+        return cython_fast_pointwise_add_array_4d if fast else cython_pointwise_add_array_4d
+
+    if is_fp16:
+        return cython_fast_pointwise_add_value_4d_fp16 if fast else cython_pointwise_add_value_4d_fp16
+
+    return cython_fast_pointwise_add_value_4d if fast else cython_pointwise_add_value_4d
+
+
+def _choose_cython_fill_(ndim: int, fast: bool) -> Callable:
+    assert ndim <= 4, ndim
+
+    if ndim <= 3:
+        return cython_fast_fill_3d if fast else cython_fill_3d
+
+    return cython_fast_fill_4d if fast else cython_fill_4d
+
+
+def _choose_cython_copy(ndim: int, is_fp16: bool, fast: bool) -> Callable:
+    assert ndim <= 4, ndim
+
+    if ndim <= 3:
+        if is_fp16:
+            return cython_fast_copy_3d_fp16 if fast else cython_copy_3d_fp16
+
+        return cython_fast_copy_3d if fast else cython_copy_3d
+
+    if is_fp16:
+        return cython_fast_copy_4d_fp16 if fast else cython_copy_4d_fp16
+
+    return cython_fast_copy_4d if fast else cython_copy_4d
+
+
+def pointwise_add(
+    nums: np.ndarray,
+    summand: Union[np.array, int, float],
+    output: np.ndarray = None,
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Perform pointwise addition between array and array or scalar.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    nums: np.ndarray
+        n-dimensional array
+    summand: np.ndarray | int | float
+        array of the same shape or scalar
+    output: np.ndarray
+        array of the same shape as input, into which the output is placed. By default, a new
+        array is created
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    sum: np.ndarray
+        result of summation
+
+    Examples
+    --------
+    ```python
+    sum = pointwise_add(x, 1, x)  # inplace addition
+    sum = pointwise_add(x, 1, backend='Scipy')  # just `np.add`
+    sum = pointwise_add(x.astype('float32'), x.astype('float16'))  # will fail because of different dtypes
+    ```
+    """
+    backend = resolve_backend(backend, warn_stacklevel=3)
+    if backend.name not in ('Scipy', 'Cython'):
+        raise ValueError(f'Unsupported backend "{backend.name}".')
+
+    dtype = nums.dtype
+
+    if dtype not in _TYPES:
+        raise ValueError(f'Input array dtype must be one of {", ".join(_STR_TYPES)}, got {dtype}.')
+
+    if output is None:
+        output = np.empty_like(nums, dtype=dtype)
+    elif output.shape != nums.shape:
+        raise ValueError(f'Input array and output array shapes must be the same, got {nums.shape} vs {output.shape}.')
+    elif dtype != output.dtype:
+        raise ValueError(f'Input array and output array dtypes must be the same, got {dtype} vs {output.dtype}.')
+
+    summand_is_array = isinstance(summand, np.ndarray)
+    if summand_is_array:
+        if dtype != summand.dtype:
+            raise ValueError(f'Input and summand arrays must have same dtypes, got {dtype} vs {summand.dtype}.')
+    elif not isinstance(summand, (*_TYPES, *(int, float))):
+        raise ValueError(f'Summand dtype must be one of {", ".join(_STR_TYPES)}, got {type(summand)}.')
+    else:
+        summand = dtype.type(summand)
+
+    ndim = nums.ndim
+    num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=3)
+
+    if backend.name == 'Scipy' or ndim > 4:
+        np.add(nums, summand, out=output)
+        return output
+
+    is_fp16 = dtype == np.float16
+    src_pointwise_add = _choose_cython_pointwise_add(ndim, summand_is_array, is_fp16, backend.fast)
+
+    n_dummy = 3 - ndim if ndim <= 3 else 0
+
+    if n_dummy:
+        nums = nums[(None,) * n_dummy]
+        output = output[(None,) * n_dummy]
+        if summand_is_array:
+            summand = summand[(None,) * n_dummy]
+
+    if is_fp16:
+        output = src_pointwise_add(
+            nums.view(np.uint16), summand.view(np.uint16), output.view(np.uint16), num_threads
+        ).view(np.float16)
+    else:
+        output = src_pointwise_add(nums, summand, output, num_threads)
+
+    if n_dummy:
+        output = output[(0,) * n_dummy]
+
+    return output
+
+
+def fill_(
+    nums: np.ndarray,
+    value: Union[np.number, int, float],
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> None:
+    """
+    Fill the array with a scalar value.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    nums: np.ndarray
+        n-dimensional array
+    value: np.number | int | float
+        scalar
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Examples
+    --------
+    ```python
+    fill_(x, 1)
+    fill_(np.empty((2, 3, 4)), 42)
+    fill_(x.astype('uint16'), 3)  # will fail because of unsupported uint16 dtype
+    ```
+    """
+    backend = resolve_backend(backend, warn_stacklevel=3)
+    if backend.name not in ('Scipy', 'Cython'):
+        raise ValueError(f'Unsupported backend "{backend.name}".')
+
+    ndim = nums.ndim
+    dtype = nums.dtype
+
+    if dtype not in _TYPES or backend.name == 'Scipy' or ndim > 4:
+        nums.fill(value)
+        return
+
+    is_fp16 = dtype == np.float16
+    num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=3)
+    src_fill_ = _choose_cython_fill_(ndim, backend.fast)
+    value = dtype.type(value)
+
+    n_dummy = 3 - ndim if ndim <= 3 else 0
+
+    if n_dummy:
+        nums = nums[(None,) * n_dummy]
+
+    if is_fp16:
+        src_fill_(nums.view(np.uint16), value.view(np.uint16), num_threads)
+    else:
+        src_fill_(nums, value, num_threads)
+
+    if n_dummy:
+        nums = nums[(0,) * n_dummy]
+
+
+def full(
+    shape: Union[int, Sequence[int]],
+    fill_value: Union[np.number, int, float],
+    dtype: Union[type, str] = None,
+    order: str = 'C',
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Return a new array of given shape and dtype, filled with `fill_value`.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    shape: int | Sequence[int]
+        desired shape
+    fill_value: np.number | int | float
+        scalar to fill array with
+    dtype: type | str
+        desired dtype to which `fill_value` will be casted. If not specified, `np.array(fill_value).dtype` will be used
+    order: str
+        whether to store multidimensional data in C or F contiguous order in memory
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Examples
+    --------
+    ```python
+    x = full((2, 3, 4), 1.0)  # same as `np.ones((2, 3, 4))`
+    x = full((2, 3, 4), 1.5, dtype=int)  # same as np.ones((2, 3, 4), dtype=int)
+    x = full((2, 3, 4), 1, dtype='uint16')  # will fail because of unsupported uint16 dtype
+    ```
+    """
+    dtype = dtype or np.array(fill_value).dtype
+
+    nums = np.empty(shape, dtype=dtype, order=order)
+    fill_value = nums.dtype.type(fill_value)
+
+    fill_(nums, fill_value, num_threads, backend)
+
+    return nums
+
+
+def copy(
+    nums: np.ndarray,
+    output: np.ndarray = None,
+    order: str = 'K',
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Return copy of the given array.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    nums: np.ndarray
+        n-dimensional array
+    output: np.ndarray
+        array of the same shape and dtype as input, into which the copy is placed. By default, a new
+        array is created
+    order: str
+        controls the memory layout of the copy. `C` means C-order, `F` means F-order, `A` means `F` if a is Fortran
+        contiguous, `C` otherwise. `K` means match the layout of a as closely as possible
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    copy: np.ndarray
+        copy of array
+
+    Examples
+    --------
+    ```python
+    copied = copy(x)
+    copied = copy(x, backend='Scipy')  # same as `np.copy`
+    copy(x, output=y)  # copied into `y`
+    ```
+    """
+    backend = resolve_backend(backend, warn_stacklevel=3)
+    if backend.name not in ('Scipy', 'Cython'):
+        raise ValueError(f'Unsupported backend "{backend.name}".')
+
+    ndim = nums.ndim
+    dtype = nums.dtype
+    num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=3)
+
+    if output is None:
+        output = np.empty_like(nums, dtype=dtype, order=order)
+    elif output.shape != nums.shape:
+        raise ValueError(f'Input array and output array shapes must be the same, got {nums.shape} vs {output.shape}.')
+    elif dtype != output.dtype:
+        raise ValueError(f'Input array and output array dtypes must be the same, got {dtype} vs {output.dtype}.')
+
+    if dtype not in _TYPES or backend.name == 'Scipy' or ndim > 4:
+        output = np.copy(nums, order=order)
+        return output
+
+    is_fp16 = dtype == np.float16
+    src_copy = _choose_cython_copy(ndim, is_fp16, backend.fast)
+
+    n_dummy = 3 - ndim if ndim <= 3 else 0
+
+    if n_dummy:
+        nums = nums[(None,) * n_dummy]
+        output = output[(None,) * n_dummy]
+
+    if is_fp16:
+        src_copy(nums.view(np.uint16), output.view(np.uint16), num_threads)
+    else:
+        src_copy(nums, output, num_threads)
+
+    if n_dummy:
+        nums = nums[(0,) * n_dummy]
+        output = output[(0,) * n_dummy]
+
+    return output
+
+
+# TODO: add parallel astype?

imops/pad.py

@@ -0,0 +1,253 @@
+from typing import Callable, Sequence, Union
+
+import numpy as np
+
+from .backend import BackendLike
+from .numeric import _NUMERIC_DEFAULT_NUM_THREADS, copy
+from .utils import AxesLike, AxesParams, axis_from_dim, broadcast_axis, broadcast_to_axis, fill_by_indices
+
+
+def pad(
+    x: np.ndarray,
+    padding: Union[AxesLike, Sequence[Sequence[int]]],
+    axis: AxesLike = None,
+    padding_values: Union[AxesParams, Callable] = 0,
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Pad `x` according to `padding` along the `axis`.
+
+    Parameters
+    ----------
+    x: np.ndarray
+        n-dimensional array to pad
+    padding: Union[AxesLike, Sequence[Sequence[int]]]
+        if 2D array [[start_1, stop_1], ..., [start_n, stop_n]] - specifies individual padding
+        for each axis from `axis`. The length of the array must either be equal to 1 or match the length of `axis`.
+        If 1D array [val_1, ..., val_n] - same as [[val_1, val_1], ..., [val_n, val_n]].
+        If scalar (val) - same as [[val, val]]
+    axis: AxesLike
+        axis along which `x` will be padded
+    padding_values: Union[AxesParams, Callable]
+        values to pad with, must be broadcastable to the resulting array.
+        If Callable (e.g. `numpy.min`) - `padding_values(x)` will be used
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    padded: np.ndarray
+        padded array
+
+    Examples
+    --------
+    ```python
+    padded = pad(x, 2)  # pad 2 zeros on each side of each axes
+    padded = pad(x, [1, 1], axis=(-1, -2))  # pad 1 zero on each side of last 2 axes
+    ```
+    """
+    x = np.asarray(x)
+    padding = np.asarray(padding)
+    if padding.ndim < 2:
+        padding = padding.reshape(-1, 1)
+    axis = axis_from_dim(axis, x.ndim)
+    padding = np.asarray(fill_by_indices(np.zeros((x.ndim, 2), dtype=int), np.atleast_2d(padding), axis))
+    if (padding < 0).any():
+        raise ValueError(f'Padding must be non-negative: {padding.tolist()}.')
+    if callable(padding_values):
+        padding_values = padding_values(x)
+
+    new_shape = np.array(x.shape) + np.sum(padding, axis=1)
+    new_x = np.array(padding_values, dtype=x.dtype)
+    new_x = copy(np.broadcast_to(new_x, new_shape), order='C', num_threads=num_threads, backend=backend)
+
+    start = padding[:, 0]
+    end = np.where(padding[:, 1] != 0, -padding[:, 1], None)
+    # TODO: how to parallelize this?
+    new_x[tuple(map(slice, start, end))] = x
+
+    return new_x
+
+
+def pad_to_shape(
+    x: np.ndarray,
+    shape: AxesLike,
+    axis: AxesLike = None,
+    padding_values: Union[AxesParams, Callable] = 0,
+    ratio: AxesParams = 0.5,
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Pad `x` to match `shape` along the `axis`.
+
+    Parameters
+    ----------
+    x: np.ndarray
+        n-dimensional array to pad
+    shape: AxesLike
+        final shape
+    axis: AxesLike
+        axis along which `x` will be padded
+    padding_values: Union[AxesParams, Callable]
+        values to pad with, must be broadcastable to the resulting array.
+        If Callable (e.g. `numpy.min`) - `padding_values(x)` will be used
+    ratio: AxesParams
+        float or sequence of floats describing what proportion of padding to apply on the left sides of padding axes.
+        Remaining ratio of padding will be applied on the right sides
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    padded: np.ndarray
+        padded array
+
+    Examples
+    --------
+    ```python
+    padded = pad_to_shape(x, [4, 5, 6])  # pad 3d array
+    padded = pad_to_shape(x, [4, 5], axis=[0, 1], ratio=0)  # pad first 2 axes on the right
+    ```
+    """
+    x = np.asarray(x)
+    axis, shape, ratio = broadcast_axis(axis, x.ndim, shape, ratio)
+
+    old_shape = np.array(x.shape)[list(axis)]
+    if (old_shape > shape).any():
+        shape = fill_by_indices(x.shape, shape, axis)
+        raise ValueError(f'The resulting shape cannot be smaller than the original: {x.shape} vs {shape}.')
+
+    delta = shape - old_shape
+    start = (delta * ratio).astype(int)
+    padding = np.array((start, delta - start)).T.astype(int)
+
+    return pad(x, padding, axis, padding_values=padding_values, num_threads=num_threads, backend=backend)
+
+
+def pad_to_divisible(
+    x: np.ndarray,
+    divisor: AxesLike,
+    axis: AxesLike = None,
+    padding_values: Union[AxesParams, Callable] = 0,
+    ratio: AxesParams = 0.5,
+    remainder: AxesLike = 0,
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Pad `x` to be divisible by `divisor` along the `axis`.
+
+    Parameters
+    ----------
+    x: np.ndarray
+        n-dimensional array to pad
+    divisor: AxesLike
+        float or sequence of floats an incoming array shape will be divisible by
+    axis: AxesLike
+        axis along which the array will be padded. If None - the last `len(divisor)` axes are used
+    padding_values: Union[AxesParams, Callable]
+        values to pad with. If Callable (e.g. `numpy.min`) - `padding_values(x)` will be used
+    ratio: AxesParams
+        float or sequence of floats describing what proportion of padding to apply on the left sides of padding axes.
+        Remaining ratio of padding will be applied on the right sides
+    remainder: AxesLike
+        `x` will be padded such that its shape gives the remainder `remainder` when divided by `divisor`
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    padded: np.ndarray
+        padded array
+
+    Examples
+    --------
+    ```python
+    x  # array of shape [2, 3, 4]
+    padded = pad_to_divisible(x, 6)  # pad to shape [6, 6, 6]
+    padded = pad_to_divisible(x, [4, 3], axis=[0, 1], ratio=1)  # pad first 2 axes on the left, shape - [4, 3, 4]
+    padded = pad_to_divisible(x, 3, remainder=1)  # pad to shape [4, 4, 4]
+    ```
+    """
+    x = np.asarray(x)
+    axis = axis_from_dim(axis, x.ndim)
+    divisor, remainder, ratio = broadcast_to_axis(axis, divisor, remainder, ratio)
+
+    assert np.all(remainder >= 0)
+    shape = np.maximum(np.array(x.shape)[list(axis)], remainder)
+
+    return pad_to_shape(
+        x, shape + (remainder - shape) % divisor, axis, padding_values, ratio, num_threads=num_threads, backend=backend
+    )
+
+
+def restore_crop(
+    x: np.ndarray,
+    box: np.ndarray,
+    shape: AxesLike,
+    padding_values: Union[AxesParams, Callable] = 0,
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Pad `x` to match `shape`. The left padding is taken equal to `box`'s start.
+
+    Parameters
+    ----------
+    x: np.ndarray
+        n-dimensional array to pad
+    box: np.ndarray
+        array of shape (2, x.ndim) describing crop boundaries
+    shape: AxesLike
+        shape to restore crop to
+    padding_values: Union[AxesParams, Callable]
+        values to pad with. If Callable (e.g. `numpy.min`) - `padding_values(x)` will be used
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    padded: np.ndarray
+        padded array
+
+    Examples
+    --------
+    ```python
+    x  # array of shape [2, 3, 4]
+    padded = restore_crop(x, np.array([[0, 0, 0], [2, 3, 4]]), [4, 4, 4])  # pad to shape [4, 4, 4]
+    padded = restore_crop(x, np.array([[0, 0, 0], [1, 1, 1]]), [4, 4, 4])  # fail, box is inconsistent with an array
+    padded = restore_crop(x, np.array([[1, 2, 3], [3, 5, 7]]), [3, 5, 7])  # pad to shape [3, 5, 7]
+    ```
+    """
+    start, stop = np.asarray(box)
+
+    assert len(shape) == x.ndim
+    assert len(start) == len(stop) == x.ndim
+
+    x = np.asarray(x)
+
+    if (stop > shape).any() or (stop - start != x.shape).any():
+        raise ValueError(
+            f'The input array (of shape {x.shape}) was not obtained by cropping a '
+            f'box {start, stop} from the shape {shape}.'
+        )
+
+    padding = np.array([start, shape - stop], dtype=int).T
+    x = pad(x, padding, padding_values=padding_values, num_threads=num_threads, backend=backend)
+    assert all(np.array(x.shape) == shape)
+
+    return x