TDSC-ABUS2023 · PyTorch

A lightweight PyTorch Dataset for the TDSC-ABUS 2023 challenge
Tumor Detection, Segmentation and Classification on Automated 3D Breast Ultrasound

Paper · Challenge · Quick Start · Citation

_{Figure 1. Case 8 (malignant). (a) Axial slice of the full volume returned by TDSC, with the tumor mask and bounding box. (b) The same tumor as returned by TDSCTumors, cropped to its bounding box.}

Highlights

• Zero setup. Each split is downloaded and extracted on first use, then cached locally.
• Ready-to-train samples. Volumes, masks, labels and tumor bounding boxes, straight from dataset[i].
• Tumor crops. TDSCTumors yields volumes already cropped to the tumor, for classification or patch-based segmentation.
• Minimal dependencies. torch, numpy, pandas, pynrrd and gdown, nothing else.

Installation

pip install tdsc-abus2023-pytorch

Requires Python 3.9 or newer.

Quick Start

Full volumes

from tdsc_abus2023_pytorch import TDSC, DataSplits

dataset = TDSC(path="./data", split=DataSplits.TRAIN, download=True)
volume, mask, label, bbox = dataset[0]

Tumor crops

from tdsc_abus2023_pytorch import TDSCTumors, DataSplits

dataset = TDSCTumors(path="./data", split=DataSplits.TRAIN, download=True)
volume, mask, label = dataset[0]

Faster loading

The volumes ship as gzip-compressed NRRD, so every read decompresses about 200 MB. Pass cache=True to convert each file to an uncompressed .npy next to it on first access. Later reads memory-map that file: TDSC skips decompression, and TDSCTumors reads only the tumor region. DataLoader workers share the OS page cache. The cache takes about 1.5x the disk space of the NRRD files.

dataset = TDSCTumors(path="./data", split=DataSplits.TRAIN, cache=True)
loader = torch.utils.data.DataLoader(dataset, batch_size=1, num_workers=4)

Anatomical views

ViewTransformer transposes each volume/mask pair into the requested anatomical plane.

from tdsc_abus2023_pytorch import TDSC, DataSplits, ViewTransformer, ViewTransposeConfig

dataset = TDSC(
    path="./data",
    split=DataSplits.TRAIN,
    transforms=[ViewTransformer(view=ViewTransposeConfig.CORONAL)],
)

_{Figure 2. Slice through the tumor of case 8 in each view produced by ViewTransformer: (a) axial, (b) coronal, (c) sagittal.}

Custom transforms

Any callable (volume, mask) -> (volume, mask) works as a transform. Transforms run in the order given.

class MyTransform:
    def __call__(self, volume, mask):
        return volume, mask  # your logic here

dataset = TDSC(
    path="./data",
    split=DataSplits.TRAIN,
    transforms=[ViewTransformer(ViewTransposeConfig.AXIAL), MyTransform()],
)

Dataset

The dataset has 200 3D breast ultrasound volumes acquired with an Invenia ABUS system (GE Healthcare) at Harbin Medical University Cancer Hospital, China. Experienced radiologists annotated and verified the tumor masks and bounding boxes.

With download=True, each requested split is fetched from Google Drive, extracted and cached under path/<Split>/. Later runs reuse the cached copy and don't touch the network:

data/
├── Train/
│   ├── DATA/            # volumes (.nrrd)
│   ├── MASK/            # masks (.nrrd)
│   ├── labels.csv
│   └── bbx_labels.csv
├── Validation/
└── Test/

API Reference

split also accepts a plain string, for example split="Train".

Development

git clone https://github.com/mralinp/tdsc-abus2023-pytorch.git
cd tdsc-abus2023-pytorch
pip install -r requirements.txt pytest pytest-cov
pytest

The test suite runs offline against a small synthetic dataset and never downloads the real data. Contributions are welcome through pull requests.

Citation

If you use this dataset, please cite the challenge paper:

@misc{luo2025tumordetectionsegmentationclassification,
  title         = {Tumor Detection, Segmentation and Classification Challenge on Automated 3D Breast Ultrasound: The TDSC-ABUS Challenge},
  author        = {Gongning Luo and others},
  year          = {2025},
  eprint        = {2501.15588},
  archivePrefix = {arXiv},
  primaryClass  = {eess.IV},
  url           = {https://arxiv.org/abs/2501.15588}
}

License

The code is released under the MIT License. The dataset itself is provided by the TDSC-ABUS 2023 organizers and is subject to their terms of use.