0
# Search and Analysis
1

2
High-performance search and statistical analysis functions for large arrays. These functions provide optimized alternatives to numpy operations and specialized analytics for image processing and connectomics workflows.
3

4
## Capabilities
5

6
### Value Search
7

8
Search arrays for indices where values match a specified target value.
9

10
```python { .api }
11
def indices(
12
    arr: NDArray,
13
    value: Union[int, float]
14
) -> NDArray:
15
    """
16
    Search an array for indices where value matches the array value.
17
    
18
    Args:
19
        arr: Input array to search
20
        value: Value to search for
21
    
22
    Returns:
23
        Indices where value matches
24
    """
25
```
26

27
**Usage Example:**
28

29
```python
30
import fastremap
31
import numpy as np
32

33
# Sample array
34
arr = np.array([1, 2, 1, 3, 1, 4])
35

36
# Find all indices of value 1
37
indices = fastremap.indices(arr, 1)
38
# Result: [0, 2, 4]
39

40
# Works with multi-dimensional arrays
41
arr_2d = np.array([[1, 2], [3, 1], [1, 4]])
42
indices = fastremap.indices(arr_2d, 1)
43
# Result: [0, 3, 4] (flattened indices)
44
```
45

46
### Foreground Counting
47

48
Count the number of non-zero voxels in an array rapidly.
49

50
```python { .api }
51
def foreground(
52
    arr: NDArray[np.integer]
53
) -> int:
54
    """
55
    Returns the number of non-zero voxels in an array.
56
    
57
    Args:
58
        arr: Input array
59
    
60
    Returns:
61
        Count of non-zero voxels
62
    """
63
```
64

65
**Usage Example:**
66

67
```python
68
import fastremap
69
import numpy as np
70

71
# Sample labeled image
72
labels = np.array([0, 1, 0, 2, 0, 3, 4])
73

74
# Count non-zero elements
75
count = fastremap.foreground(labels)
76
# Result: 4
77

78
# Works with multi-dimensional arrays
79
labels_3d = np.zeros((100, 100, 100))
80
labels_3d[10:20, 10:20, 10:20] = 1
81
count = fastremap.foreground(labels_3d)
82
# Result: 1000 (10^3)
83
```
84

85
### Min-Max Computation
86

87
Compute minimum and maximum values in a single pass, faster than separate `np.min()` and `np.max()` calls.
88

89
```python { .api }
90
def minmax(
91
    arr: NDArray
92
) -> tuple[Union[int, float, None], Union[int, float, None]]:
93
    """
94
    Returns (min(arr), max(arr)) computed in a single pass.
95
    
96
    Args:
97
        arr: Input array
98
    
99
    Returns:
100
        Tuple of min and max values
101
    """
102
```
103

104
**Usage Example:**
105

106
```python
107
import fastremap
108
import numpy as np
109

110
# Sample array
111
arr = np.array([5, 2, 8, 1, 9, 3])
112

113
# Get min and max in one operation
114
min_val, max_val = fastremap.minmax(arr)
115
# Result: (1, 9)
116

117
# More efficient than separate calls
118
# min_val = np.min(arr)  # slower
119
# max_val = np.max(arr)  # slower
120
```
121

122
### Point Cloud Generation
123

124
Generate mapping from labels to their (x, y, z) coordinates in the image.
125

126
```python { .api }
127
def point_cloud(
128
    arr: NDArray
129
) -> dict[int, NDArray]:
130
    """
131
    Generate mapping from labels to their (x, y, z) position in the image.
132
    
133
    Args:
134
        arr: A 2D or 3D numpy array
135
    
136
    Returns:
137
        Mapping from label values to coordinate arrays
138
    """
139
```
140

141
**Usage Example:**
142

143
```python
144
import fastremap
145
import numpy as np
146

147
# 2D labeled image
148
labels_2d = np.array([[1, 0, 2],
149
                      [0, 1, 0],
150
                      [2, 0, 1]])
151

152
# Get coordinates for each label
153
coords = fastremap.point_cloud(labels_2d)
154
# Result: {1: array([[0, 0], [1, 1], [2, 2]]), 2: array([[0, 2], [2, 0]])}
155

156
# 3D example
157
labels_3d = np.zeros((5, 5, 5))
158
labels_3d[1, 2, 3] = 10
159
labels_3d[3, 1, 2] = 10
160
coords = fastremap.point_cloud(labels_3d)
161
# Result: {10: array([[1, 2, 3], [3, 1, 2]])}
162
```
163

164
### Pixel Adjacency Analysis
165

166
Compute the number of matching adjacent memory locations in an image, useful for analyzing image statistics and connectomics segmentation quality.
167

168
```python { .api }
169
def pixel_pairs(
170
    labels: NDArray
171
) -> int:
172
    """
173
    Computes the number of matching adjacent memory locations.
174
    
175
    Args:
176
        labels: Input labels array
177
    
178
    Returns:
179
        Number of matching adjacent pairs
180
    """
181
```
182

183
**Usage Example:**
184

185
```python
186
import fastremap
187
import numpy as np
188

189
# Sample labeled image with connected regions
190
labels = np.array([[1, 1, 2],
191
                   [1, 1, 2], 
192
                   [3, 3, 3]])
193

194
# Count adjacent matching pixels
195
pairs = fastremap.pixel_pairs(labels)
196
# Result: Number representing connectivity within segments
197

198
# Useful for assessing segmentation quality
199
# Higher values indicate more connected/coherent segments
200
```
201

202
## Types
203

204
```python { .api }
205
NDArray = np.ndarray
206
```