Hotspot - Mammogram Lesion Detection System

A modular, maintainable system for detecting lesions in mammogram images using advanced image processing and machine learning techniques.

Features

• Modular Architecture: Clean separation of concerns with dedicated modules for preprocessing, detection, and utilities
• Multiple Detection Profiles: Configurable detection sensitivity (sensitive, balanced, specific, high-resolution, fast, research)
• Batch Processing: Efficient processing of multiple mammogram images
• Temporal Analysis: Track lesion changes across time series
• Comprehensive Feature Detection: Spiculation, mass, density, texture, and distortion analysis

Installation

1. Clone the repository:

git clone <repository-url>
cd hotspot

2. Install dependencies:

pip install -r requirements.txt

Quick Start

Single Image Detection

from hotspot import detect_lesions

results = detect_lesions(
    image_path="mammogram.png",
    profile="balanced"
)

print(f"Found {len(results['lesion_points'])} lesions")

Batch Processing

from hotspot import batch_process

image_paths = ["mammo1.png", "mammo2.png", "mammo3.png"]
results = batch_process(
    image_paths=image_paths,
    profile="sensitive",
    output_dir="batch_results/"
)

Temporal Analysis

from hotspot import evaluate_series

timepoint_paths = {
    0: "mammogram_2020.nii.gz",
    1: "mammogram_2021.nii.gz", 
    2: "mammogram_2022.nii.gz"
}

temporal_results = evaluate_series(
    patient_id="Patient_001",
    timepoint_nifti_paths=timepoint_paths,
    mask_nifti_path="ground_truth.nii.gz",
    profile="balanced"
)

📚 Examples and Tutorials

Getting Started (Beginner Friendly)

# Run the complete getting started guide
python -m hotspot.examples.getting_started

# Or run individual examples
python -c "from hotspot.examples.getting_started import simple_detection_example; simple_detection_example()"

Available Examples:

• Simple Detection - Basic lesion detection in one image
• Different Profiles - How sensitivity settings affect results
• Batch Processing - Analyzing multiple images
• Custom Configuration - Fine-tuning parameters

Advanced Examples

from hotspot.examples import run_all_examples
run_all_examples()  # Run all advanced examples

Advanced Topics:

• Profile comparison and analysis
• Custom configuration examples
• Temporal analysis for longitudinal studies
• Quick parameter tuning

Test Your Setup

python test_examples.py  # Verify everything works

Detection Profiles

• conservative: Very few detections, high confidence
• moderate_conservative: Between conservative and balanced
• balanced: Balanced sensitivity and precision (default)
• moderate: Between balanced and sensitive
• sensitive: More detections, may have false positives
• clinical: Optimized for clinical lesions like hemangiomas

Architecture

hotspot/
├── __init__.py                 # Main API
├── config/
│   └── tuning_config.py       # Configuration profiles
├── preprocessing/
│   ├── breast_segmentation.py # Breast region detection
│   └── pectoral_detection.py  # Pectoral muscle detection
├── detection/
│   ├── features.py            # Feature extraction algorithms
│   └── pipeline.py            # Main detection pipeline
├── utils/
│   ├── helpers.py             # Utility functions
│   └── file_ops.py            # File operations
└── examples/
    ├── getting_started.py     # Beginner-friendly examples
    ├── basic_usage.py         # Advanced usage examples
    └── README.md              # Detailed examples guide

Dependencies

• numpy
• opencv-python
• scikit-image
• scipy
• matplotlib
• nibabel
• SimpleITK

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

[License information]

Citation

If you use this software in your research, please cite:

[Citation information]