fastremap Library

1.18.0 · active · verified Fri Apr 17

fastremap is a highly optimized C++ library with a Python wrapper for high-performance image and point cloud processing. It provides extremely fast functions for remapping, masking, renumbering, finding unique elements, and in-place transposition of 3D labeled images. The current version is 1.18.0, and it maintains an active release cadence with frequent updates.

Common errors

```
TypeError: Expected array to be C-contiguous.
```
cause The underlying C++ routines in fastremap expect NumPy arrays to be C-contiguous for optimal performance and sometimes correctness. If an array is created or sliced in a way that makes it non-contiguous, this error can occur or performance will suffer.

fix Convert the array to C-contiguous form before passing it to fastremap: `arr = np.ascontiguousarray(arr)`.
```
KeyError: <label_value> when using fastremap.remap or remap_inplace with a dictionary.
```
cause The mapping dictionary provided to `remap` or `remap_inplace` does not contain an entry for one or more non-zero label values present in the input array.

fix Ensure your mapping dictionary is comprehensive for all labels you intend to remap. If some labels should remain unchanged, either include them in the map `label: label` or filter the input array before remapping. For labels that should be mapped to zero, include `label: 0`.
```
ValueError: Cannot convert object to scalar type or TypeError: Argument 'mapping' has incorrect type (expected numpy.ndarray, got dict)
```
cause Incorrectly passing a dictionary to a function that expects a NumPy array for mapping, or vice-versa, or using an incompatible data type for keys/values in the mapping.

fix Check the function signature for `remap` or `remap_inplace`. `remap` can take a dict, while `remap_lut` (or similar) takes a lookup table (array). Ensure the mapping structure and data types (e.g., keys/values in dictionary or elements in lookup table) match the function's expectations. For integer maps, ensure keys and values are integers.

Warnings

gotcha Many core functions like `remap_inplace` and `transpose_inplace` modify the input NumPy array directly (in-place). If you intend to preserve the original array, use their non-`_inplace` counterparts or create a copy before calling the in-place function.
Fix: Use `arr.copy()` before passing to an `_inplace` function, or use functions like `fastremap.remap` which return a new array.
gotcha The `fastremap.renumber` function returns a tuple containing two items: the new renumbered array and a dictionary mapping old labels to new labels. Forgetting to unpack both can lead to errors or misunderstanding the output.
Fix: Always unpack the return value like `new_array, old_to_new_map = fastremap.renumber(arr)` to access both components.
gotcha Functions expecting labels (e.g., `remap`, `renumber`, `mask`) often perform best or explicitly expect unsigned integer data types (like `np.uint32`). Using other types, especially floating-point, may lead to performance degradation, unexpected behavior, or errors due to casting or unsupported operations in the underlying C++.
Fix: Ensure input arrays for label processing are explicitly cast to appropriate unsigned integer types (e.g., `arr.astype(np.uint32)`).

Install

pip install fastremap Install fastremap

Imports

remap
```
from fastremap import remap
```
remap_inplace
```
from fastremap import remap_inplace
```
renumber
```
from fastremap import renumber
```
mask
```
from fastremap import mask
```

Quickstart

This quickstart demonstrates basic usage of `fastremap` for remapping labels in a NumPy array. It shows both non-in-place (`remap`) and in-place (`remap_inplace`) operations, as well as the `renumber` function for making labels contiguous and obtaining the mapping.

import numpy as np
import fastremap

# Example 1: Remap an array using a dictionary
arr1 = np.array([1, 2, 1, 3, 0], dtype=np.uint32)
mapping = {1: 10, 2: 20, 3: 30}
remapped_arr = fastremap.remap(arr1, mapping)
print(f"Original array: {arr1}")
print(f"Remapped array: {remapped_arr}")
# Expected: Remapped array: [10 20 10 30  0]

# Example 2: In-place remapping
arr2 = np.array([10, 20, 10, 30, 0], dtype=np.uint32)
reverse_mapping = {10: 1, 20: 2, 30: 3}
fastremap.remap_inplace(arr2, reverse_mapping)
print(f"Array after in-place remapping: {arr2}")
# Expected: Array after in-place remapping: [1 2 1 3 0]

# Example 3: Renumber contiguous labels
arr3 = np.array([0, 5, 2, 0, 5, 10], dtype=np.uint32)
new_array, old_to_new_map = fastremap.renumber(arr3)
print(f"Original array for renumber: {arr3}")
print(f"Renumbered array: {new_array}")
print(f"Old to new map: {old_to_new_map}")
# Expected: Renumbered array: [0 2 1 0 2 3], Old to new map: {0: 0, 5: 2, 2: 1, 10: 3}

view raw JSON →