Examples
========

This page contains comprehensive examples for common use cases.

Example 1: Basic 2D Image Processing
--------------------------------------

Complete workflow for processing 2D images::

    import torch
    from qlty import NCYXQuilt

    # Setup
    quilt = NCYXQuilt(
        Y=256, X=256,
        window=(64, 64),
        step=(32, 32),      # 50% overlap
        border=(8, 8),
        border_weight=0.1
    )

    # Load data
    images = torch.randn(20, 3, 256, 256)

    # Split into patches
    patches = quilt.unstitch(images)
    print(f"Created {patches.shape[0]} patches from {images.shape[0]} images")

    # Process patches
    processed_patches = your_model(patches)

    # Stitch back together
    reconstructed, weights = quilt.stitch(processed_patches)
    assert reconstructed.shape[0] == images.shape[0]

Example 2: Training with Input-Output Pairs
--------------------------------------------

Training a model on unstitched patches::

    from qlty import NCYXQuilt
    import torch

    quilt = NCYXQuilt(Y=128, X=128, window=(32, 32), step=(16, 16), border=(5, 5))

    # Training data
    input_images = torch.randn(100, 3, 128, 128)
    target_labels = torch.randn(100, 128, 128)

    # Unstitch pairs
    input_patches, target_patches = quilt.unstitch_data_pair(input_images, target_labels)

    # Training loop
    model.train()
    optimizer = torch.optim.Adam(model.parameters())

    for inp, tgt in zip(input_patches, target_patches):
        optimizer.zero_grad()
        output = model(inp.unsqueeze(0))
        loss = criterion(output, tgt.unsqueeze(0))
        loss.backward()
        optimizer.step()

Example 3: Large Dataset with Disk Caching
--------------------------------------------

Processing datasets too large for memory::

    from qlty import LargeNCYXQuilt
    import torch
    import tempfile
    import os

    # Setup
    temp_dir = tempfile.mkdtemp()
    filename = os.path.join(temp_dir, "large_dataset")

    quilt = LargeNCYXQuilt(
        filename=filename,
        N=1000,            # 1000 images
        Y=1024, X=1024,   # Large images
        window=(256, 256),
        step=(128, 128),
        border=(20, 20),
        border_weight=0.1
    )

    # Load data (or iterate through dataset)
    data = torch.randn(1000, 3, 1024, 1024)

    # Process all chunks
    print(f"Processing {quilt.N_chunks} chunks...")
    for i in range(quilt.N_chunks):
        if i % 100 == 0:
            print(f"Progress: {i}/{quilt.N_chunks}")

        index, patch = quilt.unstitch_next(data)

        # Process patch
        with torch.no_grad():
            processed = model(patch.unsqueeze(0))

        # Accumulate
        quilt.stitch(processed, index)

    # Get final results
    mean_result = quilt.return_mean()
    mean_result, std_result = quilt.return_mean(std=True)

    print(f"Final shape: {mean_result.shape}")

    # Cleanup
    for suffix in ["_mean_cache.zarr", "_std_cache.zarr", "_norma_cache.zarr",
                   "_mean.zarr", "_std.zarr"]:
        path = filename + suffix
        if os.path.exists(path):
            import shutil
            shutil.rmtree(path)

Example 4: Handling Sparse/Missing Data
----------------------------------------

Filtering out patches with no valid data::

    from qlty import NCYXQuilt, weed_sparse_classification_training_pairs_2D

    quilt = NCYXQuilt(Y=128, X=128, window=(32, 32), step=(16, 16), border=(5, 5))

    # Data with missing labels
    input_data = torch.randn(50, 3, 128, 128)
    labels = torch.ones(50, 128, 128) * (-1)  # All missing initially

    # Add some valid data
    labels[:, 30:98, 30:98] = torch.randint(0, 10, (50, 68, 68)).float()

    # Unstitch
    input_patches, label_patches = quilt.unstitch_data_pair(
        input_data, labels, missing_label=-1
    )

    print(f"Total patches: {input_patches.shape[0]}")

    # Filter valid patches
    border_tensor = quilt.border_tensor()
    valid_input, valid_labels, removed_mask = weed_sparse_classification_training_pairs_2D(
        input_patches, label_patches, missing_label=-1, border_tensor=border_tensor
    )

    print(f"Valid patches: {valid_input.shape[0]}")
    print(f"Removed patches: {removed_mask.sum().item()}")

Example 5: 3D Volume Processing
--------------------------------

Processing 3D medical imaging or microscopy data::

    from qlty import NCZYXQuilt
    import torch

    quilt = NCZYXQuilt(
        Z=128, Y=128, X=128,
        window=(64, 64, 64),
        step=(32, 32, 32),   # 50% overlap in each dimension
        border=(8, 8, 8),
        border_weight=0.1
    )

    # 3D volume data
    volumes = torch.randn(10, 1, 128, 128, 128)  # (N, C, Z, Y, X)

    # Process
    patches = quilt.unstitch(volumes)
    print(f"Created {patches.shape[0]} patches from {volumes.shape[0]} volumes")

    # Process with 3D model
    processed = your_3d_model(patches)

    # Stitch back
    reconstructed, weights = quilt.stitch(processed)
    assert reconstructed.shape == volumes.shape

Example 6: Inference with Softmax Handling
-------------------------------------------

Correct way to handle softmax when stitching::

    from qlty import NCYXQuilt
    import torch.nn.functional as F

    quilt = NCYXQuilt(Y=256, X=256, window=(64, 64), step=(32, 32), border=(8, 8))

    image = torch.randn(1, 3, 256, 256)
    patches = quilt.unstitch(image)

    # Process patches (get logits, NOT softmax)
    with torch.no_grad():
        logits = model(patches)  # Shape: (M, num_classes, 64, 64)

    # Stitch logits first
    stitched_logits, weights = quilt.stitch(logits)

    # THEN apply softmax
    probabilities = F.softmax(stitched_logits, dim=1)

    # This is correct! Averaging logits then softmaxing = softmax of averaged logits

Example 7: Custom Border Weighting
-----------------------------------

Experimenting with different border weights::

    from qlty import NCYXQuilt

    # Test different border weights
    for border_weight in [0.0, 0.1, 0.5, 1.0]:
        quilt = NCYXQuilt(
            Y=128, X=128,
            window=(32, 32),
            step=(16, 16),
            border=(5, 5),
            border_weight=border_weight
        )

        data = torch.randn(5, 3, 128, 128)
        patches = quilt.unstitch(data)
        reconstructed, weights = quilt.stitch(patches)

        # Evaluate reconstruction quality
        error = torch.mean(torch.abs(reconstructed - data))
        print(f"Border weight {border_weight}: Error = {error:.6f}")

Example 8: Batch Processing for Efficiency
-------------------------------------------

Processing patches in batches for better GPU utilization::

    from qlty import NCYXQuilt
    import torch

    quilt = NCYXQuilt(Y=512, X=512, window=(128, 128), step=(64, 64), border=(10, 10))

    image = torch.randn(1, 3, 512, 512)
    patches = quilt.unstitch(image)

    # Process in batches
    batch_size = 32
    processed_patches = []

    for i in range(0, len(patches), batch_size):
        batch = patches[i:i+batch_size]
        with torch.no_grad():
            output = model(batch)
        processed_patches.append(output)

    processed_patches = torch.cat(processed_patches, dim=0)
    result, weights = quilt.stitch(processed_patches)

Example 9: Combining with DataLoaders
--------------------------------------

Integrating with PyTorch DataLoaders::

    from torch.utils.data import Dataset, DataLoader
    from qlty import NCYXQuilt

    class PatchedDataset(Dataset):
        def __init__(self, images, labels, quilt):
            self.quilt = quilt
            self.input_patches, self.label_patches = quilt.unstitch_data_pair(
                images, labels
            )

        def __len__(self):
            return len(self.input_patches)

        def __getitem__(self, idx):
            return self.input_patches[idx], self.label_patches[idx]

    # Create dataset
    images = torch.randn(100, 3, 128, 128)
    labels = torch.randn(100, 128, 128)
    quilt = NCYXQuilt(Y=128, X=128, window=(32, 32), step=(16, 16), border=(5, 5))

    dataset = PatchedDataset(images, labels, quilt)
    dataloader = DataLoader(dataset, batch_size=64, shuffle=True)

    # Train
    for batch_input, batch_labels in dataloader:
        # Training code...
        pass

Example 10: Error Handling and Validation
------------------------------------------

Proper error handling::

    from qlty import NCYXQuilt
    import torch

    # Valid usage
    try:
        quilt = NCYXQuilt(
            Y=128, X=128,
            window=(32, 32),
            step=(16, 16),
            border=(5, 5),
            border_weight=0.1
        )
        print("✓ Quilt created successfully")
    except ValueError as e:
        print(f"✗ Error: {e}")

    # Invalid border_weight
    try:
        quilt = NCYXQuilt(Y=128, X=128, window=(32, 32), step=(16, 16),
                         border=(5, 5), border_weight=2.0)  # Invalid!
    except ValueError as e:
        print(f"✓ Caught error: {e}")

    # Invalid border dimensions
    try:
        quilt = NCYXQuilt(Y=128, X=128, window=(32, 32), step=(16, 16),
                         border=(1, 2, 3))  # Wrong size for 2D!
    except ValueError as e:
        print(f"✓ Caught error: {e}")