0
# Masking and Filtering
1

2
Operations for selectively hiding or preserving specific values in arrays. Essential for image segmentation, data cleaning workflows, and selective data processing where certain labels need to be excluded or isolated.
3

4
## Capabilities
5

6
### Label Masking
7

8
Zero out designated labels in an array with a specified mask value.
9

10
```python { .api }
11
def mask(
12
    arr: ArrayLike,
13
    labels: ArrayLike,
14
    in_place: bool = False,
15
    value: Union[int, float] = 0
16
) -> NDArray:
17
    """
18
    Mask out designated labels in an array with the given value.
19
    
20
    Args:
21
        arr: Input N-dimensional numpy array
22
        labels: Iterable list of integers to mask
23
        in_place: Modify input array to reduce memory consumption
24
        value: Mask value (default: 0)
25
    
26
    Returns:
27
        Array with specified labels masked out
28
    """
29
```
30

31
**Usage Example:**
32

33
```python
34
import fastremap
35
import numpy as np
36

37
# Sample labeled image
38
labels = np.array([0, 1, 2, 3, 4, 5, 1, 2, 3])
39

40
# Mask specific labels
41
masked = fastremap.mask(labels, [1, 3, 5])
42
# Result: [0, 0, 2, 0, 4, 0, 0, 2, 0]
43

44
# Mask with custom value
45
masked = fastremap.mask(labels, [2, 4], value=-1)
46
# Result: [0, 1, -1, 3, -1, 5, 1, -1, 3]
47

48
# In-place masking to save memory
49
fastremap.mask(labels, [1, 3], in_place=True)
50
```
51

52
### Inverse Masking
53

54
Zero out all labels except those in the provided list, effectively preserving only the specified labels.
55

56
```python { .api }
57
def mask_except(
58
    arr: NDArray,
59
    labels: ArrayLike,
60
    in_place: bool = False,
61
    value: Union[int, float] = 0
62
) -> NDArray:
63
    """
64
    Mask out all labels except the provided list.
65
    
66
    Args:
67
        arr: Input N-dimensional numpy array
68
        labels: Iterable list of integers to preserve
69
        in_place: Modify input array to reduce memory consumption
70
        value: Mask value (default: 0)
71
    
72
    Returns:
73
        Array with all labels except specified ones masked out
74
    """
75
```
76

77
**Usage Example:**
78

79
```python
80
import fastremap
81
import numpy as np
82

83
# Sample labeled image
84
labels = np.array([0, 1, 2, 3, 4, 5, 1, 2, 3])
85

86
# Keep only specific labels
87
preserved = fastremap.mask_except(labels, [1, 3])
88
# Result: [0, 1, 0, 3, 0, 0, 1, 0, 3]
89

90
# Keep labels with custom mask value
91
preserved = fastremap.mask_except(labels, [2, 4], value=-1)
92
# Result: [-1, -1, 2, -1, 4, -1, -1, 2, -1]
93

94
# In-place operation
95
fastremap.mask_except(labels, [1, 2], in_place=True)
96
```
97

98
## Types
99

100
```python { .api }
101
ArrayLike = Union[np.ndarray, list, tuple]
102
NDArray = np.ndarray
103
```