Mammaus

AI-Powered Ultrasound Video Analysis With Vision Transformers

This project provides a pipeline for automatic analysis of ultrasound video sequences using artificial intelligence. It enables:

• Preprocessing of medical videos (DICOM)
• Frame-by-frame image classification with a deep model
• Generation of detailed clinical reports and visualizations

Clinical workflow:

1. Extract frames from DICOM ultrasound videos
2. Classify each frame (e.g., benign, malignant, normal) using a ViT model
3. Detect suspicious sequences (e.g., ≥3 consecutive malignant frames)
4. Generate per-acquisition and global reports (text + figures)
5. Review results for clinical decision support (radiology/oncology)

Example use case: breast ultrasound analysis

Project Structure

mammaus/              # Core package
    __init__.py
    constants.py
    predict.py        # Frame classification + per-acquisition reports
    preprocess.py     # DICOM → PNG extraction
    reporting.py      # Figures, statistics, global report
    MODEL.txt         # Model card (architecture, classes, limitations)
tests/                # Unit tests (pytest)
pyproject.toml        # Build config, entry points, dev tools
README.md

Pipeline Overview

Pipeline Overview:

DICOM Ultrasound Video
|
v
Preprocessing (PNG extraction)
|
v
AI Classification (per frame)
|
v
Save Scores (per acquisition)
|
+-----------+------------+
|                        |
v                        v
Per-acquisition   Global Report
Reports & Figures (summary, figure)
|                        |
+-----------+------------+
|
v
Physician Clinical Review

Installation

1. Install PyTorch following the official instructions for your system (CPU or GPU): 👉 https://pytorch.org/get-started/locally/

2. Install mammaus:

cd mammaus
pip install -e .

For development (testing + linting):

pip install -e ".[dev]"

Usage

1. DICOM → PNG Preprocessing

mammaus-preprocess /path/to/dicom_folder_or_file

2. AI Prediction on All Frames

mammaus-predict preprocessed/

3. Global Report

mammaus-report

Advanced Options

All CLI commands support additional parameters:

Option	Command(s)	Default	Description
--verbose	all	off	Enable detailed logging
--model MODEL_ID	mammaus-predict	hugging-science/breast-cancer-detector-2	HuggingFace model ID or local path
--threshold PCT	mammaus-predict, mammaus-report	30.0	Malignant confidence threshold (%)
--min-run N	mammaus-predict, mammaus-report	3	Min consecutive malignant frames for alert
--output DIR	mammaus-preprocess, mammaus-predict	preprocessed / results	Output folder
--results DIR	mammaus-report	results	Results folder to read scores from

Example with custom parameters:

mammaus-predict preprocessed/ --model my-org/my-model --threshold 20 --min-run 5 --verbose
mammaus-report --threshold 20 --min-run 5

Example Output

Per-acquisition report (excerpt)

═══════════════════════════════════════════════════
  1_RAP  —  Right breast — Areolar / Periareolar
  346 frames analyzed
═══════════════════════════════════════════════════

RESULT BY CATEGORY
------------------
    Benign :  272 / 346 frames (78.6%)  
    Malignant (suspicious) :    2 / 346 frames (0.6%)
    Normal :   72 / 346 frames (20.8%)

GENERAL ASSESSMENT (automatic heuristic)
----------------------------------------
  ✓  RESULT: OVERALL REASSURING
  2 frame(s) classified as malignant but isolated,
  without a consecutive sequence ≥ 3 — likely outliers.

Global report summary (excerpt)

SUMMARY BY ACQUISITION
----------------------
Acquisition Frames Benign Normal Malignant MaligMean MaligMax Review
--------------------------------------------------------------------
1_RAP       346    79%    21%    0.6%      10.3%      60.1%   Reassuring
1_RMED      346    77%     1%    22.3%     32.6%      91.4%   TO CHECK
...

⚠ 5 acquisition(s) require review (consecutive malignant frames detected).

Per-acquisition figures

Each acquisition produces a confidence plot + per-frame color bar:

This could give the user clues to identify key images or sub-sequences in ultrasound videos.

Global report figure

This could give the user clues to identify key part of the full ultrasound exam.

Testing

pip install -e ".[dev]"
python -m pytest tests/ -v

Adapting to Other Applications

This pipeline is model-agnostic. To adapt it to a different classification task:

1. Use --model to point to a different HuggingFace image classification model
2. Adjust --threshold and --min-run as needed for the new domain

Note: The model must be compatible with transformers.pipeline("image-classification", ...). This means a HuggingFace Hub ID or a local directory saved with save_pretrained(). Raw .pt, ONNX, or other formats are not supported directly for the moment.

Provided Example: Breast Ultrasound

• Model: HuggingFace ViT (breast-cancer-detector-2)
• 3 classes: benign, malignant, normal
• See MODEL.txt for the full model card

License

Apache 2.0

Authors

Thibault Escobar, 2026

---

Limitations and Future Improvements

• Performance: For very large datasets, parallelization of preprocessing and prediction could be considered. Easy to implement if needed with dedicated lib such as Ray or Joblib.

If you have suggestions or want to contribute improvements, feel free to open an issue or pull request.