object-segmentation/scripts/README_FLOAT32_TRAINING.md

Standalone Float32 Training Script for 16-bit TIFFs

Overview

This standalone script (train_float32_standalone.py) trains YOLO models on 16-bit grayscale TIFF datasets with no data loss.

• Loads 16-bit TIFFs with tifffile (not PIL/cv2)
• Converts to float32 [0-1] on-the-fly (preserves full 16-bit precision)
• Replicates grayscale → 3-channel RGB in memory
• No disk caching required
• Uses custom PyTorch Dataset + training loop

Quick Start

# Activate virtual environment
source venv/bin/activate

# Train on your 16-bit TIFF dataset
python scripts/train_float32_standalone.py \
    --data data/my_dataset/data.yaml \
    --weights yolov8s-seg.pt \
    --epochs 100 \
    --batch 16 \
    --imgsz 640 \
    --lr 0.0001 \
    --save-dir runs/my_training \
    --device cuda

Arguments

Argument	Required	Default	Description
--data	Yes	-	Path to YOLO data.yaml file
--weights	No	yolov8s-seg.pt	Pretrained model weights
--epochs	No	100	Number of training epochs
--batch	No	16	Batch size
--imgsz	No	640	Input image size
--lr	No	0.0001	Learning rate
--save-dir	No	runs/train	Directory to save checkpoints
--device	No	cuda/cpu	Training device (auto-detected)

Dataset Format

Your data.yaml should follow standard YOLO format:

path: /path/to/dataset
train: train/images
val: val/images
test: test/images  # optional

names:
  0: class1
  1: class2

nc: 2

Directory structure:

dataset/
├── train/
│   ├── images/
│   │   ├── img1.tif  (16-bit grayscale TIFF)
│   │   └── img2.tif
│   └── labels/
│       ├── img1.txt  (YOLO format)
│       └── img2.txt
├── val/
│   ├── images/
│   └── labels/
└── data.yaml

Output

The script saves:

• epoch{N}.pt: Checkpoint after each epoch
• best.pt: Best model weights (lowest loss)
• Training logs to console

Features

✅ 16-bit precision preserved: Float32 [0-1] maintains full dynamic range
✅ No disk caching: Conversion happens in memory
✅ No PIL/cv2: Direct tifffile loading
✅ Variable-length labels: Handles segmentation polygons
✅ Checkpoint saving: Resume training if interrupted
✅ Best model tracking: Automatically saves best weights

Example

Train a segmentation model on microscopy data:

python scripts/train_float32_standalone.py \
    --data data/microscopy/data.yaml \
    --weights yolov11s-seg.pt \
    --epochs 150 \
    --batch 8 \
    --imgsz 1024 \
    --lr 0.0003 \
    --save-dir data/models/microscopy_v1

Troubleshooting

Out of Memory (OOM)

Reduce batch size:

--batch 4

Slow Loading

Reduce num_workers (edit script line 208):

num_workers=2  # instead of 4

Different Image Sizes

The script expects all images to have the same dimensions. For variable sizes:

1. Implement letterbox/resize in dataset's _read_image()
2. Or preprocess images to same size

Loss Computation Errors

If you see "Cannot determine loss", the script may need adjustment for your Ultralytics version. Check:

# In train() function, the preds format may vary
# Current script assumes: preds is tuple with loss OR dict with 'loss' key

vs GUI Training

Feature	Standalone Script	GUI Training Tab
Float32 conversion	✓ Yes	✓ Yes (automatic)
Disk caching	✗ None	✗ None
Progress UI	✗ Console only	✓ Visual progress bar
Dataset selection	Manual CLI args	✓ GUI browsing
Multi-stage training	Manual runs	✓ Built-in
Use case	Advanced users	General users

Technical Details

Data Loading Pipeline

16-bit TIFF file
    ↓ (tifffile.imread)
uint16 [0-65535]
    ↓ (/ 65535.0)
float32 [0-1]
    ↓ (replicate channels)
float32 RGB (H,W,3) [0-1]
    ↓ (permute to C,H,W)
torch.Tensor (3,H,W) float32
    ↓ (DataLoader stack)
Batch (B,3,H,W) float32
    ↓
YOLO Model

Precision Comparison

Method	Unique Values	Data Loss
float32 [0-1]	~65,536	None ✓
uint16 RGB	65,536	None ✓
uint8	256	99.6% ✗

Example: Pixel value 32,768 (middle intensity)

• Float32: 32768 / 65535.0 = 0.50000763 (exact)
• uint8: 32768 → 128 → many values collapse!

License

Same as main project.