### Install celldetection from GitHub

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Installs the latest development version of celldetection directly from its GitHub repository.

```bash
pip install git+https://github.com/FZJ-INM1-BDA/celldetection.git
```

--------------------------------

### Data Loader and Example Visualization

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-binary.ipynb

Sets up training and testing data loaders and visualizes an example output from the training dataset.

```python
transforms = cd.conf2augmentation(conf.augmentation)
train_data = Dataset(conf.samples, conf.order, *conf.bg_fg_dists, transforms=transforms, items=conf.steps_per_epoch)
test_data = Dataset(conf.samples, conf.order, *conf.bg_fg_dists, items=2)
train_loader = DataLoader(train_data, batch_size=conf.batch_size, num_workers=conf.num_workers,
                          collate_fn=cd.universal_dict_collate_fn, shuffle=conf.shuffle)
test_loader = DataLoader(test_data, batch_size=2, num_workers=0, collate_fn=cd.universal_dict_collate_fn)

# Plot example
example = train_data[0]
contours = example['sampled_contours'][0]
image = Dataset.unmap(example['inputs'])
cd.vis.show_detection(image, contours=contours, contour_line_width=5, figsize=(11, 11))
```

--------------------------------

### CPN Model and Optimizer Setup

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-multiclass.ipynb

Initializes a CPN model, applies configuration tweaks, moves it to the specified device, and sets up the optimizer, scheduler, and gradient scaler for mixed-precision training.

```python
model = getattr(models, conf.cpn)(in_channels=conf.in_channels, order=conf.order, samples=conf.samples,
                                  refinement_iterations=conf.refinement_iterations, nms_thresh=conf.nms_thresh,
                                  contour_head_stride=conf.contour_head_stride, classes=conf.classes,
                                  refinement_buckets=conf.refinement_buckets,
                                  backbone_kwargs=dict(inputs_mean=conf.inputs_mean, inputs_std=conf.inputs_std))
cd.conf2tweaks_(conf.tweaks, model)
model.to(conf.device)
optimizer = cd.conf2optimizer(conf.optimizer, model.parameters())
scheduler = cd.conf2scheduler(conf.scheduler, optimizer)
scaler = GradScaler() if conf.amp else None  # set None to disable
```

--------------------------------

### Install Napari Plugin

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Install the celldetection Napari plugin using pip. This command fetches the latest version directly from the GitHub repository.

```bash
pip install git+https://github.com/FZJ-INM1-BDA/celldetection-napari.git
```

--------------------------------

### Data Loaders and Example Plotting

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-multiclass.ipynb

Sets up training and testing data loaders using the custom Dataset and DataLoader. Includes plotting an example detection from the training data.

```python
transforms = cd.conf2augmentation(conf.augmentation)
train_data = Dataset(conf.samples, conf.order, *conf.bg_fg_dists, transforms=transforms, items=conf.steps_per_epoch)
test_data = Dataset(conf.samples, conf.order, *conf.bg_fg_dists, items=2)
train_loader = DataLoader(train_data, batch_size=conf.batch_size, num_workers=conf.num_workers,
                          collate_fn=cd.universal_dict_collate_fn, shuffle=conf.shuffle)
test_loader = DataLoader(test_data, batch_size=2, num_workers=0, collate_fn=cd.universal_dict_collate_fn)

# Plot example
example = train_data[0]
class_d = cd.toydata.CLASS_NAMES_GEOMETRIC
cd.vis.show_detection(image=Dataset.unmap(example['inputs']), contours=example['sampled_contours'][0],
                      class_name=[class_d[i] for i in example['classes'][0]], scores=np.ones(len(example['classes'][0])),
                      contour_line_width=5, figsize=(11, 11))
```

--------------------------------

### Install celldetection from PyPI

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Installs or upgrades the latest stable release of celldetection from the Python Package Index (PyPI).

```bash
pip install -U celldetection
```

--------------------------------

### Visualize Training Data Example

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Calls the plot_example function to display a sample from the training data loader. This is a direct usage example for the plot_example function.

```python
plot_example(train_loader)
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Runs a Docker container to verify the celldetection installation by checking its version. Remove --gpus="device=0" if no GPUs are available.

```bash
docker run --rm --gpus="device=0" ericup/celldetection:latest python -c "import celldetection; print(celldetection.__version__)"
```

--------------------------------

### Setup Optimizer, Scheduler, and Gradient Scaler

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Initializes the optimizer and learning rate scheduler based on the configuration. A gradient scaler is created only if automatic mixed precision (AMP) is enabled for training.

```python
optimizer = cd.conf2optimizer(conf.optimizer, model.parameters())
scheduler = cd.conf2scheduler(conf.scheduler, optimizer)
scaler = GradScaler() if conf.amp else None
```

--------------------------------

### Verify Apptainer Installation

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Executes a command within an Apptainer container to verify the celldetection installation. Remove --nv if no GPUs are available.

```bash
apptainer exec --nv celldetection_latest.sif python -c "import celldetection; print(celldetection.__version__)"
```

--------------------------------

### Plot Example Data for Cell Detection

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Visualizes a single data example, including the image and its corresponding contours. Useful for verifying data loading and preprocessing steps.

```python
def plot_example(data_loader, figsize=(8, 4.5)):
    # Pick example
    example = cd.asnumpy(next(iter(data_loader)))
    contours = example['sampled_contours'][0]
    image = cd.data.channels_first2channels_last(example['inputs'][0])
    # Plot example
    cd.vis.show_detection(image, contours=contours, figsize=figsize, contour_linestyle='-',
                          cmap='gray' if image.shape[2] == 1 else ...)
    plt.colorbar()
    plt.ylim([0, image.shape[0]])
    plt.xlim([0, image.shape[1]])
```

--------------------------------

### Run a demo with a pretrained model

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Loads a pretrained model, processes an input image, and displays the detection results. Ensure PyTorch is installed and a CUDA-enabled GPU is available for optimal performance. The input image is converted to a tensor and normalized before being passed to the model.

```python
import torch, cv2, celldetection as cd
from skimage.data import coins
from matplotlib import pyplot as plt

# Load pretrained model
device = 'cuda' if torch.cuda.is_available() else 'cpu'
model = cd.fetch_model('ginoro_CpnResNeXt101UNet-fbe875f1a3e5ce2c', check_hash=True).to(device)
model.eval()

# Load input
img = coins()
img = cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
print(img.dtype, img.shape, (img.min(), img.max()))

# Run model
with torch.no_grad():
    x = cd.to_tensor(img, transpose=True, device=device, dtype=torch.float32)
    x = x / 255  # ensure 0..1 range
    x = x[None]  # add batch dimension: Tensor[3, h, w] -> Tensor[1, 3, h, w]
    y = model(x)

# Show results for each batch item
contours = y['contours']
for n in range(len(x)):
    cd.imshow_row(x[n], x[n], figsize=(16, 9), titles=('input', 'contours'))
    cd.plot_contours(contours[n])
    plt.show()
```

--------------------------------

### Display Cell Detection Version

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Retrieves and prints the installed version of the `celldetection` library. Useful for verifying the installation and compatibility.

```python
cd.__version__
```

--------------------------------

### Pull Docker Image

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Pulls the latest celldetection Docker image. This is the first step for Docker-based installations.

```bash
docker pull ericup/celldetection:latest
```

--------------------------------

### Hugging Face API - Python Client

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Perform CPN inference using the Hugging Face Spaces API with Python. This example demonstrates how to use the `gradio_client` to send an image and receive segmentation results.

```APIDOC
## Hugging Face API - Python Client

### Description
Perform CPN inference using the Hugging Face Spaces API with Python. This example demonstrates how to use the `gradio_client` to send an image and receive segmentation results.

### Method
```python
from gradio_client import Client

# Define inputs (local filename or URL)
inputs = 'https://raw.githubusercontent.com/scikit-image/scikit-image/main/skimage/data/coins.png'

# Set up client
client = Client("ericup/celldetection")

# Predict
overlay_filename, img_filename, h5_filename, csv_filename = client.predict(
    inputs,  # str: Local filepath or URL of your input image
    
    # Model name
    'ginoro_CpnResNeXt101UNet-fbe875f1a3e5ce2c',
    
    # Custom Score Threshold (numeric value between 0 and 1)
    False, .9,  # bool: Whether to use custom setting; float: Custom setting
    
    # Custom NMS Threshold
    False, .3142,  # bool: Whether to use custom setting; float: Custom setting
    
    # Custom Number of Sample Points
    False, 128,  # bool: Whether to use custom setting; int: Custom setting
    
    # Overlapping objects
    True,  # bool: Whether to allow overlapping objects
    
    # API name (keep as is)
    api_name="/predict"
)


# Example usage: Code below only shows how to use the results
from matplotlib import pyplot as plt
import celldetection as cd
import pandas as pd

# Read results from local temporary files
img = imread(img_filename)
overlay = imread(overlay_filename)  # random colors per instance; transparent overlap
properties = pd.read_csv(csv_filename)
contours, scores, label_image = cd.from_h5(h5_filename, 'contours', 'scores', 'labels')

# Optionally display overlay
cd.imshow_row(img, img, figsize=(16, 9))
cd.imshow(overlay)
plt.show()

# Optionally display contours with text
cd.imshow_row(img, img, figsize=(16, 9))
cd.plot_contours(contours, texts=['score: %d%%\narea: %d' % s for s in zip((scores * 100).round(), properties.area)])
plt.show()
```
```

--------------------------------

### Hugging Face API - Javascript Client

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Perform CPN inference using the Hugging Face Spaces API with JavaScript. This example demonstrates how to use the `@gradio/client` library to send an image and receive segmentation results.

```APIDOC
## Hugging Face API - Javascript Client

### Description
Perform CPN inference using the Hugging Face Spaces API with JavaScript. This example demonstrates how to use the `@gradio/client` library to send an image and receive segmentation results.

### Method
```javascript
import { client } from "@gradio/client";

const response_0 = await fetch("https://raw.githubusercontent.com/scikit-image/scikit-image/main/skimage/data/coins.png");
const exampleImage = await response_0.blob();
					
const app = await client("ericup/celldetection");
const result = await app.predict("/predict", [
    exampleImage,  // blob: Your input image
    
    // Model name (hosted model or URL)
    "ginoro_CpnResNeXt101UNet-fbe875f1a3e5ce2c",
    
    // Custom Score Threshold (numeric value between 0 and 1)
    false, .9,  // bool: Whether to use custom setting; float: Custom setting
    
    // Custom NMS Threshold
    false, .3142,  // bool: Whether to use custom setting; float: Custom setting
    
    // Custom Number of Sample Points
    false, 128,  // bool: Whether to use custom setting; int: Custom setting
    
    // Overlapping objects
    true,  // bool: Whether to allow overlapping objects
    
    // API name (keep as is)
    api_name="/predict"
]);
```
```

--------------------------------

### Hugging Face API Inference with Javascript

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Performs cell detection inference using the Hugging Face API with JavaScript. This example demonstrates fetching an image, initializing the client, and making a prediction with various parameters.

```javascript
import { client } from "@gradio/client";

const response_0 = await fetch("https://raw.githubusercontent.com/scikit-image/scikit-image/main/skimage/data/coins.png");
const exampleImage = await response_0.blob();
						
const app = await client("ericup/celldetection");
const result = await app.predict("/predict", [
    exampleImage,  // blob: Your input image
    
    // Model name (hosted model or URL)
    "ginoro_CpnResNeXt101UNet-fbe875f1a3e5ce2c",
    
    // Custom Score Threshold (numeric value between 0 and 1)
    false, .9,  // bool: Whether to use custom setting; float: Custom setting
    
    // Custom NMS Threshold
    false, .3142,  // bool: Whether to use custom setting; float: Custom setting
    
    // Custom Number of Sample Points
    false, 128,  // bool: Whether to use custom setting; int: Custom setting
    
    // Overlapping objects
    true,  // bool: Whether to allow overlapping objects
    
    // API name (keep as is)
    api_name="/predict"
]);
```

--------------------------------

### Hugging Face API Inference with Python

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Performs cell detection inference using the Hugging Face API with Python. Requires the gradio_client library. This example demonstrates setting various prediction parameters and processing the results.

```python
from gradio_client import Client

# Define inputs (local filename or URL)
inputs = 'https://raw.githubusercontent.com/scikit-image/scikit-image/main/skimage/data/coins.png'

# Set up client
client = Client("ericup/celldetection")

# Predict
overlay_filename, img_filename, h5_filename, csv_filename = client.predict(
    inputs,  # str: Local filepath or URL of your input image
    
    # Model name
    'ginoro_CpnResNeXt101UNet-fbe875f1a3e5ce2c',
    
    # Custom Score Threshold (numeric value between 0 and 1)
    False, .9,  # bool: Whether to use custom setting; float: Custom setting
    
    # Custom NMS Threshold
    False, .3142,  # bool: Whether to use custom setting; float: Custom setting
    
    # Custom Number of Sample Points
    False, 128,  # bool: Whether to use custom setting; int: Custom setting
    
    # Overlapping objects
    True,  # bool: Whether to allow overlapping objects
    
    # API name (keep as is)
    api_name="/predict"
)


# Example usage: Code below only shows how to use the results
from matplotlib import pyplot as plt
import celldetection as cd
import pandas as pd

# Read results from local temporary files
img = imread(img_filename)
overlay = imread(overlay_filename)  # random colors per instance; transparent overlap
properties = pd.read_csv(csv_filename)
contours, scores, label_image = cd.from_h5(h5_filename, 'contours', 'scores', 'labels')

# Optionally display overlay
cd.imshow_row(img, img, figsize=(16, 9))
cd.imshow(overlay)
plt.show()

# Optionally display contours with text
cd.imshow_row(img, img, figsize=(16, 9))
cd.plot_contours(contours, texts=['score: %d%%
area: %d' % s for s in zip((scores * 100).round(), properties.area)])
plt.show()
```

--------------------------------

### Albumentations Compose for Image Augmentation

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Defines a data augmentation pipeline using Albumentations. This setup includes various transformations like rotation, blurring, and optical distortion to improve model robustness.

```python
transforms = A.Compose([
    A.RandomRotate90(),
    A.Transpose(),
    A.RandomGamma((42, 100)),
    A.OneOf([
        A.MotionBlur(p=.2),
        A.MedianBlur(blur_limit=3, p=0.1),
        A.Blur(blur_limit=3, p=0.1),
    ], p=0.2),
    A.OpticalDistortion(shift_limit=0.01, p=0.3, interpolation=0, border_mode=0),
])
```

--------------------------------

### Model and Optimizer Initialization

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-binary.ipynb

Initializes the CPN model, applies configuration tweaks, moves the model to the specified device, and sets up the optimizer and learning rate scheduler.

```python
model = getattr(models, conf.cpn)(in_channels=conf.in_channels, order=conf.order, samples=conf.samples,
                                  refinement_iterations=conf.refinement_iterations, nms_thresh=conf.nms_thresh,
                                  score_thresh=conf.score_thresh, contour_head_stride=conf.contour_head_stride,
                                  classes=conf.classes, refinement_buckets=conf.refinement_buckets,
                                  backbone_kwargs=dict(inputs_mean=conf.inputs_mean, inputs_std=conf.inputs_std))
cd.conf2tweaks_(conf.tweaks, model)
model.to(conf.device)
optimizer = cd.conf2optimizer(conf.optimizer, model.parameters())
scheduler = cd.conf2scheduler(conf.scheduler, optimizer)
scaler = GradScaler() if conf.amp else None  # set None to disable
```

--------------------------------

### Build Docker Image

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docker/README.md

Builds a Docker image from the current directory with a specified Dockerfile and tag. Ensure the Dockerfile and build context are correctly specified.

```bash
docker build --tag "celldetection:latest" -f docker/Dockerfile .
```

--------------------------------

### Build Docker Image with Multi-Platform Support

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docker/README.md

Creates a Docker buildx builder and then builds an image supporting multiple platforms (linux/amd64 and linux/arm64). This is useful for distributing images compatible with various architectures.

```bash
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 --tag "celldetection:latest" -f docker/Dockerfile 
```

--------------------------------

### Instantiate 3D ResNeXt50UNet Model

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Initialize a 3D U-Net model with a ResNeXt50 backbone. Specify the input and output channels, and the dimensionality of the model.

```python
# U-Nets are available in 2D and 3D
import celldetection as cd

model = cd.models.ResNeXt50UNet(in_channels=3, out_channels=1, nd=3)
```

--------------------------------

### Plot Contour Proposal Network Order Hyperparameter

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Generates plots to visualize the effect of the 'order' hyperparameter on contour generation. This function iterates through different 'order' settings and plots an example for each.

```python
def order_plot(data, data_loader):
    # Plot example data for different `order` settings
    gen = data.gen
    s = int(np.ceil(np.sqrt(conf.order)))
    plt.figure(None, (s * 12, s * 6.75))
    for gen.order in range(1, conf.order + 1):
        plt.subplot(s, s, gen.order)
        plot_example(data_loader, figsize=None)
        plt.title(f'{"Chosen o" if gen.order == conf.order else "O"}rder: {gen.order}')
    plt.show()
    assert gen.order == conf.order
```

--------------------------------

### Import Cell Detection Library

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Import the main celldetection library for use in your project.

```python
import celldetection as cd
```

--------------------------------

### Initialize Data Loaders

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Creates `Data` objects for training, validation, and testing datasets, and then initializes corresponding PyTorch `DataLoader` instances. This prepares the data for model training and evaluation.

```python
train_data = Data(train_bbbc039, conf, transforms, items=conf.steps_per_epoch * conf.batch_size,
                  size=conf.crop_size)
val_data = Data(val_bbbc039, conf)
test_data = Data(test_bbbc039, conf)
```

```python
train_loader = DataLoader(train_data, batch_size=conf.batch_size, num_workers=conf.num_workers,
                          collate_fn=cd.universal_dict_collate_fn, shuffle=conf.shuffle)
val_loader = DataLoader(val_data, batch_size=conf.test_batch_size, collate_fn=cd.universal_dict_collate_fn)
test_loader = DataLoader(test_data, batch_size=1, collate_fn=cd.universal_dict_collate_fn)
```

--------------------------------

### CPN inference via Docker with CPU

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Run CPN inference using Docker with CPU. Mounts local directories for inputs, outputs, and models. Explicitly sets accelerator to CPU.

```APIDOC
## CPN inference via Docker with CPU

### Description
Run CPN inference using Docker with CPU. Mounts local directories for inputs, outputs, and models. Explicitly sets accelerator to CPU.

### Command
```bash
docker run --rm \
  -v $PWD/docker/outputs:/outputs/ \
  -v $PWD/docker/inputs/:/inputs/ \
  -v $PWD/docker/models/:/models/ \
  celldetection:latest /bin/bash -c \
  "python cpn_inference.py --tile_size=1024 --stride=768 --precision=32-true --accelerator=cpu"
```
```

--------------------------------

### Instantiate ConvNeXt Small Model

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Use this snippet to instantiate a ConvNeXt Small model for 3D data. Ensure the celldetection library is imported.

```python
import celldetection as cd

model = cd.models.ConvNeXtSmall(in_channels=3, nd=3)
```

--------------------------------

### Run Docker Inference with CPU

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Runs CPN inference using Docker with CPU acceleration. Mounts local directories for inputs, outputs, and models. Specify '--accelerator=cpu' for CPU usage.

```bash
docker run --rm \
  -v $PWD/docker/outputs:/outputs/ \
  -v $PWD/docker/inputs/:/inputs/ \
  -v $PWD/docker/models/:/models/ \
  celldetection:latest /bin/bash -c \
  "python cpn_inference.py --tile_size=1024 --stride=768 --precision=32-true --accelerator=cpu"
```

--------------------------------

### Initialize PyTorch CUDA Backend

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Ensures that PyTorch uses CUDA if available and optimizes cuDNN for performance. This should be run once at the beginning of your script.

```python
import torch
if torch.cuda.is_available():
    torch.backends.cudnn.benchmark = True
```

--------------------------------

### Configure Cell Detection Parameters

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Initializes and prints a `Config` object for cell detection. This object holds all essential parameters for data handling, CPN architecture, optimizer, training, and testing. It supports saving and loading configurations to JSON.

```python
conf = cd.Config(
    # data
    directory='./data',
    download_data=True,
    in_channels=1,
    classes=2,
    shuffle=True,
    bg_fg_dists=(0.8, 0.85),
    crop_size=(256, 256),
    
    # cpn
    cpn='CpnU22',  # see https://git.io/JOnWX for alternatives
    score_thresh=.9,
    val_score_threshs=(.6, .8, .9),
    nms_thresh=.5,
    val_nms_threshs=(.3, .5, .8),
    contour_head_stride=2,
    order=6,  # the higher, the more complex shapes can be detected
    samples=64,  # number of coordinates per contour
    refinement_iterations=3,
    refinement_buckets=6,
    inputs_mean=.5,
    inputs_std=.5,
    tweaks={
        'BatchNorm2d': {'momentum': 0.05}
    },
    
    # optimizer
    optimizer={'Adam': {'lr': 0.0008, 'betas': (0.9, 0.999)}},
    scheduler={'StepLR': {'step_size': 5, 'gamma': .99}},
    
    # training
    epochs=100,
    steps_per_epoch=512,
    batch_size=8,
    amp=torch.cuda.is_available(),  # Automatic Mixed Precision (https://pytorch.org/docs/stable/amp.html)
    
    # testing
    test_batch_size=4,
    
    # misc
    num_workers=0,  #8 * int(os.name != 'nt'),
    device = 'cuda' if torch.cuda.is_available() else 'cpu'
)
print(conf)
```

--------------------------------

### Basic Inference

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/inference.md

Run inference on a batch of images using a specified model. Ensure the model is accessible via the 'cd://' URI or a local path.

```bash
python cpn_inference.py -i 'images/*.tif' -m 'cd://model_name'
```

--------------------------------

### Configure Contour Proposal Network (CPN)

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-multiclass.ipynb

Sets up a detailed configuration object for a CPN model. This includes data properties, augmentation strategies, CPN-specific parameters, optimizer and scheduler choices, and training settings. Configurations can be saved to JSON.

```python
conf = cd.Config(
    # data
    in_channels=3,
    classes=4,
    shuffle=True,
    bg_fg_dists=(0.8, 0.85),
    
    # augmentation (schema: <class_name>:<kwargs>)
    augmentation=OrderedDict({
        'Transpose': {'p': 0.5},  # see: https://albumentations.ai/docs/
        'RandomRotate90': {'p': 0.5},
    }),
    
    # cpn
    cpn='CpnU22',  # see https://git.io/JOnWX for alternatives
    nms_thresh=.5,
    contour_head_stride=8,
    order=7,  # the higher, the more complex shapes can be detected
    samples=128,  # number of coordinates per contour
    refinement_iterations=3,
    refinement_buckets=6,
    inputs_mean=.5,
    inputs_std=.5,
    tweaks={
        'BatchNorm2d': {'momentum': 0.05}
    },
    
    # optimizer
    optimizer={'Adadelta': {'lr': 1., 'rho': 0.9}},
    scheduler={'StepLR': {'step_size': 5, 'gamma': .99}},
    
    # training
    epochs=100,
    steps_per_epoch=8 * 512,
    batch_size=8,
    amp=torch.cuda.is_available(),
    
    # misc
    num_workers=0,
    device = 'cuda' if torch.cuda.is_available() else 'cpu'
)
print(conf)
```

--------------------------------

### Build Docker Image for Mac Silicon

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docker/README.md

Builds a Docker image specifically for Mac Silicon architecture (linux/arm64). This command ensures compatibility with ARM-based M1/M2 chips.

```bash
docker build --platform linux/arm64 --tag "celldetection:latest" -f docker/Dockerfile 
```

--------------------------------

### Import Core PyTorch AMP and Utilities

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Imports necessary components for Automatic Mixed Precision (AMP), data loading, functional operations, and neural network modules from PyTorch.

```python
from torch.cuda.amp import GradScaler, autocast
from torch.utils.data import DataLoader
import torch.nn.functional as F
import torch.nn as nn
```

--------------------------------

### Basic Command Line Execution

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/inference.md

Execute the cpn_inference.py script directly from the command line. Replace '[arguments]' with the desired script parameters.

```bash
python cpn_inference.py [arguments]
```

--------------------------------

### Run Docker Inference with GPU

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Runs CPN inference using Docker with GPU acceleration. Mounts local directories for inputs, outputs, and models. Ensure the specified GPU device is available.

```bash
docker run --rm \
  -v $PWD/docker/outputs:/outputs/ \
  -v $PWD/docker/inputs/:/inputs/ \
  -v $PWD/docker/models/:/models/ \
  --gpus="device=0" \
  celldetection:latest /bin/bash -c \
  "python cpn_inference.py --tile_size=1024 --stride=768 --precision=32-true"
```

--------------------------------

### Create Python Virtual Environment (venv)

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Creates a new virtual environment named 'celldetection_env' using the venv module.

```bash
python -m venv celldetection_env
```

--------------------------------

### Activate Python Virtual Environment (venv - Windows)

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Activates the 'celldetection_env' virtual environment on Windows systems.

```bash
celldetection_env\Scripts\activate
```

--------------------------------

### Run Docker Container

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docker/README.md

Runs a Docker container from the 'celldetection:latest' image and executes a simple Python command within it. This demonstrates basic container execution.

```bash
docker container run celldetection:latest /bin/bash -c "python -c 'print(2)'"
```

--------------------------------

### Instantiate ResNet50 Model

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Use this snippet to instantiate a ResNet50 model for 3D data. Ensure the celldetection library is imported.

```python
import celldetection as cd

model = cd.models.ResNet50(in_channels=3, nd=3)
```

--------------------------------

### CPN inference via Docker with GPU

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Run CPN inference using Docker with GPU acceleration. Mounts local directories for inputs, outputs, and models. Specifies GPU device 0.

```APIDOC
## CPN inference via Docker with GPU

### Description
Run CPN inference using Docker with GPU acceleration. Mounts local directories for inputs, outputs, and models. Specifies GPU device 0.

### Command
```bash
docker run --rm \
  -v $PWD/docker/outputs:/outputs/ \
  -v $PWD/docker/inputs/:/inputs/ \
  -v $PWD/docker/models/:/models/ \
  --gpus="device=0" \
  celldetection:latest /bin/bash -c \
  "python cpn_inference.py --tile_size=1024 --stride=768 --precision=32-true"
```
```

--------------------------------

### Using Apptainer and Slurm for Inference

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/inference.md

Execute the cpn_inference.py script using Apptainer and Slurm for distributed computing. Ensure the 'celldetection_latest.sif' image is available and pass arguments to the script.

```bash
srun [srun-arguments] apptainer exec --nv celldetection_latest.sif python cpn_inference.py [arguments]
```

--------------------------------

### Batch Inference with Multiple Inputs and Models

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/inference.md

Process multiple input images, each potentially using a different model. Configure batch size, tile size, and stride for optimized processing.

```bash
python cpn_inference.py -i image1.tif image2.tif -m model1 model2 --batch_size 2 --tile_size 1024 2048 --stride 512
```

--------------------------------

### Activate Python Virtual Environment (venv - macOS/Linux)

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Activates the 'celldetection_env' virtual environment on macOS and Linux systems.

```bash
source celldetection_env/bin/activate
```

--------------------------------

### Using Docker for Inference

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/inference.md

Run the cpn_inference.py script within a Docker container. Mount the current directory to '/data' inside the container and pass arguments to the script.

```bash
docker run -v $(pwd):/data ericup/celldetection:latest cpn_inference.py [arguments]
```

--------------------------------

### Load BBBC039 Dataset

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Loads the training, validation, and testing sets of the BBBC039 dataset. Ensure the configuration specifies the correct directory and download preference.

```python
train_bbbc039 = cd.data.BBBC039Train(conf.directory, download=conf.download_data)
val_bbbc039 = cd.data.BBBC039Val(conf.directory)
test_bbbc039 = cd.data.BBBC039Test(conf.directory)
```

--------------------------------

### Define and print CPN configuration

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-binary.ipynb

Sets up a detailed configuration object for Contour Proposal Networks (CPN). This includes data properties, augmentation strategies, CPN-specific parameters, optimizer and scheduler settings, and training hyperparameters. Use `conf.to_json(filename)` to save and `cd.Config.from_json(filename)` to load configurations.

```python
conf = cd.Config(
    # data
    in_channels=3,
    classes=2,
    shuffle=True,
    bg_fg_dists=(0.8, 0.85),
    
    # augmentation (schema: <class_name>:<kwargs>)
    augmentation=OrderedDict({
        'Transpose': {'p': 0.5},  # see: https://albumentations.ai/docs/
        'RandomRotate90': {'p': 0.5},
    }),
    
    # cpn
    cpn='CpnU22',  # see https://git.io/JOnWX for alternatives
    score_thresh=.9,
    nms_thresh=.5,
    contour_head_stride=8,
    order=7,  # the higher, the more complex shapes can be detected
    samples=128,  # number of coordinates per contour
    refinement_iterations=3,
    refinement_buckets=6,
    inputs_mean=.5,
    inputs_std=.5,
    tweaks={
        'BatchNorm2d': {'momentum': 0.05}
    },
    
    # optimizer
    optimizer={'Adadelta': {'lr': 1., 'rho': 0.9}},
    scheduler={'StepLR': {'step_size': 5, 'gamma': .99}},
    
    # training
    epochs=100,
    steps_per_epoch=8 * 512,
    batch_size=8,
    amp=torch.cuda.is_available(),
    
    # misc
    num_workers=0,
    device = 'cuda' if torch.cuda.is_available() else 'cpu'
)
print(conf)
```

--------------------------------

### Run Validation

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Executes the validation process using the provided model, data loader, device, and AMP settings.

```python
validate_(model, val_loader, conf.device, conf.amp)
```

--------------------------------

### Apply Transformations to a Sample Image

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Applies the defined `demo_transforms` function to the first sample from the training dataset to visualize the augmentation effects.

```python
name, img, _, lbl = train_bbbc039[0]
demo_transforms(img, lbl, name)
```

--------------------------------

### List Available Timm Models

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Explore the various models available through the PyTorch Image Models (timm) library. This is useful for selecting a pre-trained backbone for your cell detection model.

```python
import timm

timm.list_models(filter='*')  # explore available models
```

--------------------------------

### Activate Python Conda Environment

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Activates the 'celldetection_env' Conda environment.

```bash
conda activate celldetection_env
```

--------------------------------

### Import necessary libraries for celldetection

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-binary.ipynb

Imports core libraries including PyTorch, celldetection modules, NumPy, and plotting tools. Sets PyTorch CUDA benchmark if available.

```python
import torch
if torch.cuda.is_available():
    torch.backends.cudnn.benchmark = True
import celldetection as cd
from celldetection import models, toydata
import numpy as np
import os
from collections import OrderedDict
import torch.nn as nn
import torch.nn.functional as F
from torch.utils.data import Dataset, DataLoader
from tqdm import tqdm
from matplotlib import pyplot as plt
from torch.cuda.amp import GradScaler, autocast
```

--------------------------------

### Load Docker Image

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docker/README.md

Loads a Docker image from a gzipped tar archive. This command is the counterpart to `docker save` and is used to import images.

```bash
docker load -i celldetection.tar.gz
```

--------------------------------

### Instantiate SmpEncoder for Cell Detection

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Create an SmpEncoder instance, specifying the encoder name and pre-trained weights. This encoder can be used as a backbone for various segmentation models.

```python
encoder = cd.models.SmpEncoder(encoder_name='mit_b5', pretrained='imagenet')
```

--------------------------------

### Run Inference Script with Apptainer and Slurm

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/inference.md

Execute the cpn_inference.py script within an Apptainer container on an HPC system using Slurm. Adjust Slurm options and paths to match your environment.

```bash
srun --mpi=pspmix --cpu_bind=v --accel-bind=gn --cpus-per-task=64 apptainer exec --nv /path/to/celldetection_latest.sif \
  python /path/to/cpn_inference.py -i 'images/*.tif' -o 'outputs' -m 'cd://model_name' --tile_size=1024 --stride=768
```

--------------------------------

### Instantiate MA-Net with ConvNeXtSmall Encoder

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Build an MA-Net model using a ConvNeXtSmall encoder. This configuration is suitable for 3D cell detection tasks, specifying input channels and dimensionality.

```python
# Many MA-Nets are available in 2D and 3D
import celldetection as cd

encoder = cd.models.ConvNeXtSmall(in_channels=3, nd=3)
model = cd.models.MaNet(encoder, out_channels=1, nd=3)
```

--------------------------------

### Import Data Science and Cell Detection Libraries

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Imports libraries for plotting, data structures, image augmentation, the `celldetection` package, progress bars, numerical operations, and operating system interactions.

```python
from matplotlib import pyplot as plt
from collections import OrderedDict
import albumentations as A
import celldetection as cd
from tqdm import tqdm
import numpy as np
import os
```

--------------------------------

### Create Python Conda Environment

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Creates a new Conda environment named 'celldetection_env' with a specified Python version.

```bash
conda create -n celldetection_env python=3.x
```

--------------------------------

### Fetch a pretrained model

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/README.md

Fetches a pretrained model by its name. It is recommended to check the hash for integrity.

```python
model = cd.fetch_model(model_name, check_hash=True)
```

--------------------------------

### Basic Training Loop

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Iterates through the specified number of epochs, calling the `train_epoch` function for each. It also calls `show_results` periodically to visualize predictions on the test set.

```python
for epoch in range(1, conf.epochs + 1):
    train_epoch(model, train_loader, conf.device, optimizer, f'Epoch {epoch}/{conf.epochs}', scaler, scheduler)
    if epoch % 10 == 0:
        show_results(model, test_loader, conf.device)
```

--------------------------------

### Demonstrate Albumentations Transformations

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Visualizes the effect of the defined Albumentations transformations on an image and its corresponding labels. This function helps in understanding how augmentations alter the data.

```python
def demo_transforms(img, lbl, name=None):
    img = cd.data.normalize_percentile(img.copy().squeeze(), percentile=99.8)
    lbl = lbl.copy()
    
    # Show original
    cd.vis.show_detection(img, contours=cd.data.labels2contours(lbl), contour_linestyle='-')
    if name is not None:
        plt.title(name)
    plt.show()
    
    # Show transformed
    s = 3
    plt.figure(None, (s * 9, s * 9))
    for i in range(1, s * s + 1):
        plt.subplot(s, s, i)
        trans = transforms(image=img, mask=lbl.astype('int32'))
        t_img, t_lbl = trans['image'], trans['mask']
        cd.data.relabel_(t_lbl[..., None])
        plt.title(f'transformed {t_img.dtype.name, t_img.shape, t_lbl.dtype.name, t_lbl.shape}')
        cd.vis.show_detection(t_img, contours=cd.data.labels2contours(t_lbl), contour_linestyle='-')
    plt.show()
```

--------------------------------

### Define Contour Proposal Network Model

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Instantiates the Contour Proposal Network model based on configuration. It supports loading from class names, local files, or pretrained checkpoints. Model tweaks can be applied if specified.

```python
if conf.cpn in dir(cd.models):
    model = getattr(cd.models, conf.cpn)(
        in_channels=conf.in_channels, order=conf.order, samples=conf.samples,
        refinement_iterations=conf.refinement_iterations, nms_thresh=conf.nms_thresh,
        score_thresh=conf.score_thresh, contour_head_stride=conf.contour_head_stride,
        classes=conf.classes, refinement_buckets=conf.refinement_buckets,
        backbone_kwargs=dict(inputs_mean=conf.inputs_mean, inputs_std=conf.inputs_std)
    ).to(conf.device)
elif os.path.isfile(conf.cpn):
    model = torch.load(conf.cpn, map_location=conf.device)
else:
    model = cd.fetch_model(conf.cpn, map_location=conf.device)
if conf.tweaks is not None:
    cd.conf2tweaks_(conf.tweaks, model)
```

--------------------------------

### Inference with Masks and Property Adjustments

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/inference.md

Perform inference while applying masks and adjusting image properties like gamma and contrast. This is useful for fine-tuning the detection process.

```bash
python cpn_inference.py -i 'images/*.tif' --masks 'masks/*.tif' -m 'model_file' --gamma 1.2 --contrast 1.1
```

--------------------------------

### Visualize detection results

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-binary.ipynb

Evaluates the model on a test batch and visualizes the detection results, including contours and scores, for each detected object.

```python
def show_results(model, test_loader, device):
    model.eval()
    batch = cd.to_device(next(iter(test_loader)), device)
    with torch.no_grad():
        outputs = model(batch['inputs'])
    o = cd.asnumpy(outputs)
    num = len(o['contours'])
    plt.figure(None, (13 * num, 13))
    for idx in range(num):
        image = cd.asnumpy(batch['inputs'][idx])
        plt.subplot(1, num, idx + 1)
        cd.vis.show_detection(Dataset.unmap(image.transpose(1, 2, 0)), contours=o['contours'][idx],
                              contour_line_width=5, scores=o['scores'][idx])
    plt.show()
```

--------------------------------

### Training loop

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-binary.ipynb

Iterates through the specified number of epochs, calling the train_epoch function for each epoch and periodically showing results using show_results.

```python
for epoch in range(1, conf.epochs):
    train_epoch(model, train_loader, conf.device, optimizer, epoch, scaler, scheduler)
    if epoch % 1 == 0:
        show_results(model, test_loader, conf.device)
```

--------------------------------

### Evaluate on Test Dataset

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Evaluates the model on the test dataset, capturing timing information for FPS calculation.

```python
test_results = evaluate(model, test_loader, conf.device, conf.amp, timing=True)
```

--------------------------------

### Custom Data Loader Class for Cell Detection

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/Cell Detection with Contour Proposal Networks.ipynb

Implements a custom `Data` class for loading and preprocessing cell detection data. It handles normalization, optional cropping, and applies specified transformations.

```python
class Data:
    def __init__(self, data, config, transforms=None, items=None, size=None):
        self.transforms = transforms
        self.gen = cd.data.CPNTargetGenerator(
            samples=config.samples,
            order=config.order,
            max_bg_dist=config.bg_fg_dists[0],
            min_fg_dist=config.bg_fg_dists[1],
        )
        self._items = items or len(data)
        self.data = data
        self.size = size
        self.channels = config.in_channels

    def __len__(self):
        return self._items

    @staticmethod
    def map(image):
        image = image / 255
        if image.ndim == 2:
            image = image[..., None]
        return image.astype('float32')

    @staticmethod
    def unmap(image):
        image = image * 255
        image = np.clip(image, 0, 255).astype('uint8')
        if image.ndim == 3 and image.shape[2] == 1:
            image = np.squeeze(image, 2)
        return image

    def __getitem__(self, item):
        if item >= len(self):
            raise IndexError('Index out of bounds.')
        item = item % len(self.data)
        
        # Get image and labels
        name, img, _, labels = self.data[item]
        
        # Normalize intensities
        img, labels = np.copy(img).squeeze(), np.copy(labels)
        img = cd.data.normalize_percentile(img, percentile=99.8)
        labels = labels.astype('int32')       
        
        # Optionally crop
        if self.size is not None:
            h, w = self.size
            img, labels = cd.data.random_crop(img, labels, height=h, width=w)
        
        # Optionally transform
        if self.transforms is not None:
            r = self.transforms(image=img, mask=labels)
            img, labels = r['image'], r['mask']

        # Ensure channels exist
        if labels.ndim == 2:
            labels = labels[..., None]
        
        # Relabel to ensure that N objects are marked with integers 1..N
        cd.data.relabel_(labels)
        
        # Feed labels to target generator
        gen = self.gen
        gen.feed(labels=labels)
        
        # Map image to range -1..1
        image = self.map(img)
        
        # Return as dictionary
        return OrderedDict({
            'inputs': image,
            'labels': gen.reduced_labels,
            'fourier': (gen.fourier.astype('float32'),),
            'locations': (gen.locations.astype('float32'),),
            'sampled_contours': (gen.sampled_contours.astype('float32'),),
            'sampling': (gen.sampling.astype('float32'),),
            'targets': labels
        })
```

--------------------------------

### Train a single epoch

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/demos/demo-binary.ipynb

Trains the model for one epoch using the provided data loader, optimizer, and device. Supports mixed precision training with a scaler and learning rate scheduling.

```python
def train_epoch(model, train_loder, device, optimizer, epoch, scaler=None, scheduler=None):
    model.train()
    for batch_idx, batch in enumerate(tqdm(train_loader, desc="Epoch %d" % epoch)):
        batch = cd.to_device(batch, device)
        optimizer.zero_grad()
        with autocast(scaler is not None):
            outputs = model(batch['inputs'], targets=batch)
        loss = outputs['loss']
        if scaler is None:
            loss.backward()
            optimizer.step()
        else:
            scaler.scale(loss).backward()
            scaler.step(optimizer)
            scaler.update()
    if scheduler is not None:
        scheduler.step()
```

--------------------------------

### Pull Apptainer Image

Source: https://github.com/fzj-inm1-bda/celldetection/blob/main/docs/source/install.md

Pulls the celldetection Docker image for use with Apptainer in HPC environments. Remove --disable-cache if caching is allowed.

```bash
apptainer pull --dir . --disable-cache docker://ericup/celldetection:latest
```