0
# Fastremap
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: fastremap
7
- **Language**: Python
8
- **Installation**: `pip install fastremap`
9

10
## Core Imports
11

12
```python
13
import fastremap
14
```
15

16
All functions are available directly from the main module:
17

18
```python
19
from fastremap import unique, remap, renumber, mask, transpose
20
```
21

22
## Basic Usage
23

24
```python
25
import fastremap
26
import numpy as np
27

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

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

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

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

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

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

52
## Architecture
53

54
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:
55

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

61
## Capabilities
62

63
### Core Array Operations
64

65
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.
66

67
```python { .api }
68
def unique(labels, return_index=False, return_inverse=False, return_counts=False, axis=None): ...
69
def remap(arr, table, preserve_missing_labels=False, in_place=False): ...
70
def renumber(arr, start=1, preserve_zero=True, in_place=False): ...
71
def refit(arr, value=None, increase_only=False, exotics=False): ...
72
```
73

74
[Core Array Operations](./core-operations.md)
75

76
### Data Type Management
77

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

80
```python { .api }
81
def fit_dtype(dtype, value, exotics=False): ...
82
def narrow_dtype(dtype, exotics=False): ...
83
def widen_dtype(dtype, exotics=False): ...
84
```
85

86
[Data Type Management](./dtype-management.md)
87

88
### Masking and Filtering
89

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

92
```python { .api }
93
def mask(arr, labels, in_place=False, value=0): ...
94
def mask_except(arr, labels, in_place=False, value=0): ...
95
```
96

97
[Masking and Filtering](./masking.md)
98

99
### Search and Analysis
100

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

103
```python { .api }
104
def indices(arr, value): ...
105
def foreground(arr): ...
106
def minmax(arr): ...
107
def point_cloud(arr): ...
108
def pixel_pairs(labels): ...
109
```
110

111
[Search and Analysis](./search-analysis.md)
112

113
### Memory Layout and Transposition
114

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

117
```python { .api }
118
def transpose(arr): ...
119
def asfortranarray(arr): ...
120
def ascontiguousarray(arr): ...
121
```
122

123
[Memory Layout](./memory-layout.md)
124

125
### Advanced Remapping
126

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

129
```python { .api }
130
def remap_from_array(arr, vals, in_place=True): ...
131
def remap_from_array_kv(arr, keys, vals, preserve_missing_labels=True, in_place=True): ...
132
def component_map(component_labels, parent_labels): ...
133
def inverse_component_map(parent_labels, component_labels): ...
134
```
135

136
[Advanced Remapping](./advanced-remapping.md)
137

138
### Serialization
139

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

142
```python { .api }
143
def tobytes(image, chunk_size, order="C"): ...
144
```
145

146
[Serialization](./serialization.md)
147

148
## Types
149

150
```python { .api }
151
# Type aliases used throughout the API
152
ArrayLike = Union[np.ndarray, list, tuple]
153
NDArray = np.ndarray
154
DTypeLike = Union[np.dtype, type, str]
155
```