User Guide

This guide covers both basic and advanced usage of the py-distance-transforms library.

Getting Started

Installation

pip install py_distance_transforms

For GPU support, make sure you have PyTorch with CUDA installed:

pip install torch --extra-index-url https://download.pytorch.org/whl/cu118

Basic Usage

The primary function in py_distance_transforms is transform. This function takes a binary array (with 0s and 1s) and calculates the squared Euclidean distance from each 0 pixel to the nearest 1 pixel.

import numpy as np
import matplotlib.pyplot as plt
from py_distance_transforms import transform

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

# Apply distance transform
result = transform(arr)

# Visualize
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10, 5))
ax1.imshow(arr, cmap='gray')
ax1.set_title('Original')
ax2.imshow(result, cmap='gray')
ax2.set_title('Distance Transform')
plt.tight_layout()
plt.show()

Real-World Example

import numpy as np
import matplotlib.pyplot as plt
from py_distance_transforms import transform
from skimage import io, color, filters

# Load image and process
img = io.imread("sample.jpg")
img_gray = color.rgb2gray(img)
img_binary = img_gray > filters.threshold_otsu(img_gray)
img_dist = transform(img_binary.astype(np.float32))

# Visualize
fig, axes = plt.subplots(1, 3, figsize=(15, 5))
axes[0].imshow(img)
axes[0].set_title('Original Image')
axes[1].imshow(img_binary, cmap='gray')
axes[1].set_title('Binary Image')
axes[2].imshow(img_dist, cmap='viridis')
axes[2].set_title('Distance Transform')

Advanced Features

GPU Acceleration

py_distance_transforms supports GPU acceleration for NVIDIA GPUs using PyTorch tensors.

import torch
from py_distance_transforms import transform_cuda

# Create a tensor on GPU
x_gpu = torch.rand((100, 100), device='cuda')
x_gpu = (x_gpu > 0.5).float()

# Apply transform on GPU
result_gpu = transform_cuda(x_gpu)

Working with 3D Data

py_distance_transforms supports 3D arrays as well:

import numpy as np
from py_distance_transforms import transform

# Create a 3D binary array
arr_3d = np.zeros((20, 20, 20), dtype=np.float32)
arr_3d[5, 5, 5] = 1
arr_3d[15, 15, 15] = 1

# Apply distance transform
result_3d = transform(arr_3d)

Performance Comparison

py_distance_transforms generally outperforms other Python implementations, especially for large arrays and when using GPU acceleration:

Implementation	100×100	1000×1000	100×100×100
SciPy	2.5 ms	250 ms	1200 ms
py_distance_transforms (CPU)	1.2 ms	120 ms	500 ms
py_distance_transforms (GPU)	0.8 ms	25 ms	120 ms

Times are approximate and may vary based on hardware.

Integration with Deep Learning

py_distance_transforms can be used in deep learning workflows, particularly for tasks like computing Hausdorff distance loss:

import torch
from py_distance_transforms import transform_cuda

def hausdorff_loss(pred, target):
    # Convert predictions to binary
    pred_binary = (pred > 0.5).float()
    
    # Calculate distance transforms
    pred_dt = transform_cuda(pred_binary)
    target_dt = transform_cuda(target)
    
    # Compute Hausdorff distances
    d_pt = torch.mean(target * pred_dt)
    d_tp = torch.mean(pred_binary * target_dt)
    
    return d_pt + d_tp

Next Steps

For more advanced usage examples and detailed API information, refer to the API Reference.