Metadata-Version: 2.4
Name: mammoinsight-math
Version: 0.1.1
Summary: Deterministic biomedical image processing algorithms, lesion morphometry, and radiomic feature extraction for mammography
Author-email: Ernesto Rafael Perez <mammoinsight@gmail.com>
Project-URL: Homepage, https://www.mammoinsight.org/
Project-URL: Repository, https://github.com/mammoinsight/mammoinsight-math
Project-URL: Documentation, https://github.com/mammoinsight/mammoinsight-math#readme
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: scipy
Requires-Dist: scikit-image
Requires-Dist: matplotlib

# 🌸 mammoinsight-math

**Deterministic Biomedical Image Processing & Clinical Feature Extraction for Mammography**
*The Transparent Box Approach to Biomedical Image Analysis*

[![PyPI Version](https://img.shields.io/pypi/v/mammoinsight-math.svg)](https://pypi.org/project/mammoinsight-math/)
[![Python Versions](https://img.shields.io/pypi/pyversions/mammoinsight-math.svg)](https://pypi.org/project/mammoinsight-math/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 📌 Overview

`mammoinsight-math` is a specialized, open-source Python library providing deterministic, non-black-box algorithms for mammographic image analysis. Developed as part of the **MammoInsight Project**, it provides robust algorithms for frequency-domain enhancement, BI-RADS lesion morphometry, radiomic texture extraction (Haralick GLCM), and classical segmentation.

- 🌐 **Official Website:** [https://www.mammoinsight.org/](https://www.mammoinsight.org/)
- 📦 **Source Code Repository:** [https://github.com/mammoinsight/mammoinsight-math](https://github.com/mammoinsight/mammoinsight-math)

---

## ⚡ Quickstart & Installation

Install the package via `pip`:

```bash
pip install mammoinsight-math
```

### Quick Usage Example

```python
import cv2
import mammo_math as mm

# Load ROI image and lesion mask
image = cv2.imread("mammo_roi.png", cv2.IMREAD_GRAYSCALE)
mask = cv2.imread("lesion_mask.png", cv2.IMREAD_GRAYSCALE)

# 1. Image Enhancement (Homomorphic Filter in Fourier Domain)
enhanced_img = mm.homomorphic_filter(image, cutoff=15)

# 2. Deterministic Morphometry (BI-RADS Lesion Geometry)
geom = mm.LesionGeometry(mask)
print(f"Circularidad:  {geom.calcular_circularidad():.4f}")
print(f"Diámetro Feret: {geom.calcular_diametro_feret():.2f} px")

# 3. Radiomic Texture Extraction (Haralick GLCM Descriptors)
texture_vector = mm.extract_glcm_features(enhanced_img)
print("Firma GLCM (Contraste, Disimilitud, Homogeneidad, Energía, Correlación, ASM):")
print(texture_vector)
```

---

## 🧪 Included Core Modules

1. **Preprocessing (`mammo_math.preprocessing`)**:
   - `homomorphic_filter`: Frequency-domain illumination correction via 2D FFT.
   - `apply_clahe`: Contrast Limited Adaptive Histogram Equalization.
   - `apply_unsharp_masking`: Edge enhancement filter.
   - `segment_with_frangi`: Frangi vesselness filter for vascular structure suppression.
   - `segment_with_gabor_kmeans`: Multi-scale Gabor filter bank clustering.

2. **Lesion Geometry & Morphometry (`mammo_math.core`)**:
   - `LesionGeometry`: Deterministic calculations of Circularity, Feret Diameter, Eccentricity, and Elongation for BI-RADS mass shape characterization.
   - `novoas_core`: Boundary roughness and shape indices.

3. **Radiomic Texture (`mammo_math.features`)**:
   - `extract_glcm_features`: Gray-Level Co-occurrence Matrix (Haralick 6-descriptor texture vector).
   - `extract_feature_vector`: Combined 6 and 12-dimensional feature extractors.

4. **Segmentation & Clustering (`mammo_math.segmentation`)**:
   - `novoas_segmentation`: Contour-based lesion segmentation.
   - `apply_gdc_filter`: Grid-Density Clustering for noise reduction.
   - `QuantileSegmenter`: Dynamic quantile thresholding.
   - `crecimiento_de_regiones` & `segmentacion_otsu_local`: Local Otsu & Region Growing.

---

## 📚 Academic References & Citations

1. **Haralick, R. M., Shanmugam, K., & Dinstein, I. (1973).** Textural features for image classification. *IEEE Transactions on Systems, Man, and Cybernetics*, SMC-3(6), 610–621. [DOI: 10.1109/TSMC.1973.4309314](https://doi.org/10.1109/TSMC.1973.4309314) | [IEEE Xplore](https://ieeexplore.ieee.org/document/4309314/)
2. **Suckling, J., et al. (1994).** The Mammographic Image Analysis Society Digital Mammogram Database (MIAS). *Excerpta Medica. International Congress Series*, 1069, 375–378. [Cambridge Repository](https://www.repository.cam.ac.uk/items/b6a97f0c-3b9b-40ad-8f18-3d121eef1459) | [PMC 3092049](https://pmc.ncbi.nlm.nih.gov/articles/PMC3092049/)

---

## 👤 Author & License

- **Author:** Ernesto Rafael Perez — Project Lead & Researcher (`mammoinsight@gmail.com`)
- **Website:** [https://www.mammoinsight.org/](https://www.mammoinsight.org/)
- **License:** MIT License. Free for academic, clinical, and open-source research use.
