tessl/pypi-fastremap

High-performance array manipulation functions for remapping, masking, renumbering, and transposing 3D labeled images and point clouds.

—

Pending

Overview

Eval results

Files

Search and Analysis

Name: tessl/pypi-fastremap
Author: tessl

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.

Capabilities

Value Search

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

def indices(
    arr: NDArray,
    value: Union[int, float]
) -> NDArray:
    """
    Search an array for indices where value matches the array value.
    
    Args:
        arr: Input array to search
        value: Value to search for
    
    Returns:
        Indices where value matches
    """

Usage Example:

import fastremap
import numpy as np

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

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

# Works with multi-dimensional arrays
arr_2d = np.array([[1, 2], [3, 1], [1, 4]])
indices = fastremap.indices(arr_2d, 1)
# Result: [0, 3, 4] (flattened indices)

Foreground Counting

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

def foreground(
    arr: NDArray[np.integer]
) -> int:
    """
    Returns the number of non-zero voxels in an array.
    
    Args:
        arr: Input array
    
    Returns:
        Count of non-zero voxels
    """

Usage Example:

import fastremap
import numpy as np

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

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

# Works with multi-dimensional arrays
labels_3d = np.zeros((100, 100, 100))
labels_3d[10:20, 10:20, 10:20] = 1
count = fastremap.foreground(labels_3d)
# Result: 1000 (10^3)

Min-Max Computation

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

def minmax(
    arr: NDArray
) -> tuple[Union[int, float, None], Union[int, float, None]]:
    """
    Returns (min(arr), max(arr)) computed in a single pass.
    
    Args:
        arr: Input array
    
    Returns:
        Tuple of min and max values
    """

Usage Example:

import fastremap
import numpy as np

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

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

# More efficient than separate calls
# min_val = np.min(arr)  # slower
# max_val = np.max(arr)  # slower

Point Cloud Generation

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

def point_cloud(
    arr: NDArray
) -> dict[int, NDArray]:
    """
    Generate mapping from labels to their (x, y, z) position in the image.
    
    Args:
        arr: A 2D or 3D numpy array
    
    Returns:
        Mapping from label values to coordinate arrays
    """

Usage Example:

import fastremap
import numpy as np

# 2D labeled image
labels_2d = np.array([[1, 0, 2],
                      [0, 1, 0],
                      [2, 0, 1]])

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

# 3D example
labels_3d = np.zeros((5, 5, 5))
labels_3d[1, 2, 3] = 10
labels_3d[3, 1, 2] = 10
coords = fastremap.point_cloud(labels_3d)
# Result: {10: array([[1, 2, 3], [3, 1, 2]])}

Pixel Adjacency Analysis

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

def pixel_pairs(
    labels: NDArray
) -> int:
    """
    Computes the number of matching adjacent memory locations.
    
    Args:
        labels: Input labels array
    
    Returns:
        Number of matching adjacent pairs
    """

Usage Example:

import fastremap
import numpy as np

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

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

# Useful for assessing segmentation quality
# Higher values indicate more connected/coherent segments