Fastremap

High-performance array manipulation functions for remapping, masking, renumbering, and transposing 3D labeled images and point clouds. Fastremap provides C++ speed implementations for common operations that would be too slow with pure Python loops, optimized for scientific computing, computer vision, and image processing applications involving hundreds of megabytes to gigabytes of numerical data.

Package Information

• Package Name: fastremap
• Language: Python
• Installation: pip install fastremap

Core Imports

import fastremap

All functions are available directly from the main module:

from fastremap import unique, remap, renumber, mask, transpose

Basic Usage

import fastremap
import numpy as np

# Create sample labeled image data
labels = np.array([0, 1, 3, 5, 5, 10], dtype=np.uint32)

# Find unique labels faster than np.unique
uniq, counts = fastremap.unique(labels, return_counts=True)
print(f"Unique labels: {uniq}, Counts: {counts}")

# Renumber labels starting from 1 and optimize data type
renumbered, mapping = fastremap.renumber(labels, preserve_zero=True)
print(f"Renumbered: {renumbered}, Mapping: {mapping}")

# Remap specific values using a dictionary
remapped = fastremap.remap(labels, {1: 100, 5: 200}, preserve_missing_labels=True)
print(f"Remapped: {remapped}")

# Mask out specific labels
masked = fastremap.mask(labels, [1, 5], value=0)
print(f"Masked: {masked}")

# Optimize data type to fit the actual range of values
refitted = fastremap.refit(labels)
print(f"Original dtype: {labels.dtype}, Refitted dtype: {refitted.dtype}")

Architecture

Fastremap uses Cython to bridge Python and C++ code, enabling efficient processing of large multi-dimensional arrays. The library is designed around several key principles:

• In-place operations: Most functions support in_place=True to minimize memory usage
• Automatic dtype optimization: Functions like refit and renumber automatically select the smallest suitable data type
• Memory layout awareness: Transposition functions detect contiguous memory and perform optimized in-place operations when possible
• Type flexibility: Supports various numpy dtypes (int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64)

Capabilities

Core Array Operations

Essential array manipulation functions including unique value detection, remapping, renumbering, and data type optimization. These form the foundation of fastremap's high-performance array processing.

def unique(labels, return_index=False, return_inverse=False, return_counts=False, axis=None): ...
def remap(arr, table, preserve_missing_labels=False, in_place=False): ...
def renumber(arr, start=1, preserve_zero=True, in_place=False): ...
def refit(arr, value=None, increase_only=False, exotics=False): ...

Core Array Operations

Data Type Management

Functions for manipulating and optimizing numpy data types to balance memory usage and value range requirements.

def fit_dtype(dtype, value, exotics=False): ...
def narrow_dtype(dtype, exotics=False): ...
def widen_dtype(dtype, exotics=False): ...

Data Type Management

Masking and Filtering

Operations for selectively hiding or preserving specific values in arrays, essential for image segmentation and data cleaning workflows.

def mask(arr, labels, in_place=False, value=0): ...
def mask_except(arr, labels, in_place=False, value=0): ...

Masking and Filtering

Search and Analysis

High-performance search and statistical analysis functions for large arrays, including coordinate extraction and adjacency analysis.

def indices(arr, value): ...
def foreground(arr): ...
def minmax(arr): ...
def point_cloud(arr): ...
def pixel_pairs(labels): ...

Search and Analysis

Memory Layout and Transposition

In-place transposition functions that minimize memory spikes during array layout conversion, critical for GPU transfers and disk I/O.

def transpose(arr): ...
def asfortranarray(arr): ...
def ascontiguousarray(arr): ...

Memory Layout

Advanced Remapping

Specialized remapping functions using arrays instead of dictionaries, and component mapping for hierarchical label relationships.

def remap_from_array(arr, vals, in_place=True): ...
def remap_from_array_kv(arr, keys, vals, preserve_missing_labels=True, in_place=True): ...
def component_map(component_labels, parent_labels): ...
def inverse_component_map(parent_labels, component_labels): ...

Advanced Remapping

Serialization

Efficient binary serialization of chunked arrays for storage and network transfer.

def tobytes(image, chunk_size, order="C"): ...

Serialization

Types

# Type aliases used throughout the API
ArrayLike = Union[np.ndarray, list, tuple]
NDArray = np.ndarray
DTypeLike = Union[np.dtype, type, str]