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

Memory Layout and Transposition

Name: tessl/pypi-fastremap
Author: tessl

In-place transposition functions that minimize memory spikes during array layout conversion. Critical for efficient GPU transfers, disk I/O, and interfacing between different computing environments that expect specific memory layouts.

Capabilities

In-Place Matrix Transposition

Perform in-place transposition for up to 4D matrices, avoiding memory spikes associated with out-of-place operations.

def transpose(
    arr: NDArray
) -> NDArray:
    """
    Perform in-place transposition for up to 4D matrices.
    
    Args:
        arr: Input numpy array to transpose
    
    Returns:
        The transposed numpy array
    """

Usage Example:

import fastremap
import numpy as np

# 2D matrix transposition
arr = np.array([[1, 2, 3],
                [4, 5, 6]], dtype=np.float32)

# In-place transpose (memory efficient)
transposed = fastremap.transpose(arr)
# Result: [[1, 4], [2, 5], [3, 6]]

# 3D array transposition
arr_3d = np.random.random((100, 200, 300)).astype(np.float32)
transposed_3d = fastremap.transpose(arr_3d)
# Result: (300, 200, 100) shaped array, transposed in-place

Fortran Order Conversion

Convert array to Fortran (column-major) order, performing in-place transposition when possible for memory efficiency.

def asfortranarray(
    arr: NDArray
) -> NDArray:
    """
    Convert array to Fortran order, performing in-place transposition when possible.
    
    Args:
        arr: Input numpy array to convert
    
    Returns:
        Array in Fortran order
    """

Usage Example:

import fastremap
import numpy as np

# C-order array
arr = np.ones((512, 512, 512), dtype=np.float32, order='C')
print(f"Original order: {arr.flags['C_CONTIGUOUS']}, {arr.flags['F_CONTIGUOUS']}")

# Convert to Fortran order efficiently
fortran_arr = fastremap.asfortranarray(arr)
print(f"Fortran order: {fortran_arr.flags['F_CONTIGUOUS']}")

# More memory efficient than np.asfortranarray for large arrays
# np.asfortranarray(arr)  # would create a copy, using more memory

C Order Conversion

Convert array to C (row-major) order, performing in-place transposition when possible for memory efficiency.

def ascontiguousarray(
    arr: NDArray
) -> NDArray:
    """
    Convert array to C order, performing in-place transposition when possible.
    
    Args:
        arr: Input numpy array to convert
    
    Returns:
        Array in C order
    """

Usage Example:

import fastremap
import numpy as np

# Fortran-order array
arr = np.ones((512, 512, 512), dtype=np.float32, order='F')
print(f"Original order: {arr.flags['C_CONTIGUOUS']}, {arr.flags['F_CONTIGUOUS']}")

# Convert to C order efficiently
c_arr = fastremap.ascontiguousarray(arr)
print(f"C order: {c_arr.flags['C_CONTIGUOUS']}")

# More memory efficient than np.ascontiguousarray for large arrays
# Benefits are most pronounced with square or cubic arrays

Memory Layout Considerations

When In-Place Operations Are Used

Fastremap's memory layout functions automatically detect when in-place transposition is possible:

Contiguous memory: Array must have contiguous memory layout
Rectangular arrays: Works with 1D, 2D, 3D, and 4D arrays
Square/cubic optimization: Square (2D) and cubic (3D) arrays benefit most from in-place operations

Performance Benefits

import fastremap
import numpy as np
import time

# Large array example
large_arr = np.random.random((1000, 1000, 100)).astype(np.float32, order='C')

# fastremap approach (in-place when possible)
start = time.time()
fast_result = fastremap.asfortranarray(large_arr)
fast_time = time.time() - start

# numpy approach (always creates copy)
start = time.time()
numpy_result = np.asfortranarray(large_arr)
numpy_time = time.time() - start

print(f"fastremap time: {fast_time:.3f}s")
print(f"numpy time: {numpy_time:.3f}s")
print(f"Memory usage advantage: {numpy_time/fast_time:.1f}x faster")