Overview

distance_transforms is a high-performance Python package for computing distance transforms. It offers significant performance improvements over traditional implementations, especially for large arrays.

Example distance transform visualization

Installation

Install distance_transforms using pip:

pip install distance_transforms

Quick Example

import numpy as np
import matplotlib.pyplot as plt
import distance_transforms as dts

# Create a random binary array
arr = np.random.choice([0, 1], size=(10, 10)).astype(np.float32)

# Apply distance transform
result = dts.transform(arr)

What is a Distance Transform?

A distance transform converts a binary image into a grayscale image where the value of each pixel is the distance to the nearest foreground pixel (typically marked as 1 in the binary image). This transformation is useful in various applications including:

  • Path planning and navigation
  • Morphological operations
  • Feature extraction
  • Medical image analysis
  • Computer vision algorithms

Key Features

  • High Performance: Optimized algorithms for CPU and GPU
  • Julia Integration: Powered by DistanceTransforms.jl for maximum efficiency
  • GPU Acceleration: Support for NVIDIA GPUs through PyTorch and CUDA
  • Simple API: Clean, intuitive Python interface
  • NumPy Integration: Works seamlessly with NumPy arrays
  • PyTorch Support: Native support for PyTorch CUDA tensors
  • Multi-Dimensional: Works with 1D, 2D, and 3D arrays

Performance Comparison

distance_transforms significantly outperforms traditional implementations:

import numpy as np
import torch
import time
import distance_transforms as dts
from scipy.ndimage import distance_transform_edt

# Create a large 3D array
size = (100, 100, 100)
arr = np.random.choice([0, 1], size=size).astype(np.float32)

# Benchmark SciPy
start = time.time()
scipy_result = distance_transform_edt(arr == 0) ** 2
print(f"SciPy time: {time.time() - start:.3f}s")

# Benchmark distance_transforms (CPU)
start = time.time()
dts_result = dts.transform(arr)
print(f"distance_transforms CPU time: {time.time() - start:.3f}s")

# Benchmark distance_transforms (GPU)
if torch.cuda.is_available():
    tensor = torch.tensor(arr, device='cuda')
    start = time.time()
    dts_gpu_result = dts.transform_cuda(tensor)
    print(f"distance_transforms GPU time: {time.time() - start:.3f}s")

Typical results on modern hardware: - SciPy: ~1.200s - distance_transforms (CPU): ~0.500s - distance_transforms (GPU): ~0.120s

API Preview

# CPU transform with NumPy
import numpy as np
import distance_transforms as dts
arr = np.random.choice([0, 1], size=(100, 100)).astype(np.float32)
result = dts.transform(arr)

# GPU transform with PyTorch
import torch
import distance_transforms as dts
tensor = torch.rand((100, 100), device='cuda')
tensor = (tensor > 0.5).float()
result = dts.transform_cuda(tensor)

When to Use Distance Transforms

Distance transforms are particularly useful in:

  1. Medical Image Analysis: Segment organs, measure distances between anatomical structures
  2. Computer Vision: Object recognition, shape analysis, skeletonization
  3. Path Planning: Navigation algorithms in robotics
  4. Deep Learning: Custom loss functions like Hausdorff distance for segmentation tasks

Next Steps