# DL 3D - Train Object Classifier

This is an experimental module from the Xtra Library: https://www.thermofisher.com/software-em-3d-vis/xtra-library/.

This module extracts 3D volumetric patches around labeled objects, and trains a deep learning classification model.

It supports multiple neural network architectures with configurable training parameters including optimizer, learning rate scheduler, and early stopping. It leverages TensorBoard for monitoring training progress and supports transfer learning from pretrained weights or custom models.

Trained classification models are used with DL - Predict Object Class module.

## Connections

Input | Description
--- | ---
Data [required] | 3D label field containing classified object instances for training. Each label value or material represents a class. The notion of object is implicitly associated with the notion of connected components. The module Disconnect Touching Labels can help ensure this.
Input Grayscale Volume [required] | 3D grayscale volume from which training patches will be extracted around labeled objects.

## Parameters (Ports)

Parameter | Description
--- | ---
Console | Displays status messages and technical information.
Train/Validation Ratio | Fraction of objects used for training (remainder used for validation). Typical value is 0.75.
Options | Enable to randomly shuffle objects when splitting into training and validation sets.
Resample | Target voxel size for resampling volumes before training. Downsampling will reduce computational cost, but may affect accuracy. Should match the expected scale of discriminating features.
Margin around object [px] | Additional padding around each 3D object when extracting volumetric patches. Provides spatial context.
Classes to Train | Select which classes from the 3D label field to include in training.
Model Architecture | 3D neural network architecture to use. Selection is a tradeoff between computation resources, memory requirements, amount of training data, and accuracy. 3D models require significantly more GPU memory than 2D equivalents. r3d_18: Standard 3D ResNet, balanced choice for most volumetric classification tasks with moderate memory requirements mc3_18: Mixed 3D-2D convolutions, reduced memory footprint while maintaining 3D spatial understanding r2plus1d_18: Factorized 3D convolutions, efficient memory usage and fast training for volumetric data swin3d_t: Transformer-based architecture, highest accuracy for complex 3D features but requires large datasets (>1000 objects/class) and substantial GPU memory
Input Patch Size (XY) | Size in pixels of square XY planes in 3D patches. Balance between capturing 3D features and memory usage. Should fit the typical object size to avoid excessive downsampling. Larger values increase GPU memory and computational requirements.
Input Patch Depth (Z) | Number of slices in the Z direction for 3D patches. Balance between capturing 3D features and memory usage.
Initial Weights | Start from random weights or custom pretrained 3D model weights for transfer learning.
Model Filename | Path to custom pretrained 3D model file (.pth) when using custom initial weights.
Training Options | Select optimizer among the following options: Adam: Default adaptive optimizer, good general-purpose choice for most applications AdamW: Adam with weight decay regularization, better generalization and recommended for larger models SGD: Classic optimizer with momentum, slower but can achieve better final accuracy with careful tuning Select learning rate scheduler among the following options: ConstantLR: Fixed learning rate throughout training, simplest option for stable convergence OneCycleLR: Cyclical learning rate with warmup and decay, often fastest convergence (default) CosineAnnealingLR: Smooth cosine decay, good for fine-tuning and transfer learning ReduceLROnPlateau: Reduces learning rate when validation loss plateaus, adaptive and robust choice StepLR: Periodic learning rate reduction at fixed intervals, predictable decay schedule
Training Params | Number of epochs, early stopping patience (epochs without improvement before stopping), and batch size.
Base Learning Rate | Initial learning rate for training. Typical values range from 1e-5 to 1e-3.
Output Directory | Directory where trained 3D model and TensorBoard logs will be saved.
Base Filename | Base name for output 3D model file and tensorboard logs.

## See also

DL - Predict Object Class

Disconnect Touching Labels

ObjectClassification_Tuto.pdf