README.md

---
license: mit
tags:
- computer-vision
- acne-detection
- skin-analysis
- classification
- sklearn
- catboost
- medical-imaging
- traditional-ml
language:
- en
datasets:
- ACNE04
metrics:
- accuracy
- f1
pipeline_tag: image-classification
---

# Acne Severity Detection — 42-Dim Handcrafted Feature Models

21 trained sklearn/CatBoost classifiers for acne severity classification (Grade I / II / III).
Part of the **Acne CV Playground** — an interactive web tool that walks through every pipeline stage from raw pixels to prediction, with live parameter sliders and a 42-dim feature inspector.

## Model Description

Each model is a `sklearn.pipeline.Pipeline` of `[StandardScaler → Classifier]`, trained on a **42-dimensional handcrafted feature vector** extracted from face photos:

| Group | Dims | Description |
|---|---|---|
| Structural | 8 | Lesion count, total area, intensity mean/std, area max/std, density, circularity |
| Multi-scale LBP | 27 | Uniform LBP histograms at radii R=1,2,3 (9 bins × 3 scales, last bin dropped) |
| GLCM Texture | 3 | Contrast, homogeneity, energy (4 angles, 64 levels, dissimilarity removed) |
| Global Redness | 4 | Mean + std of LAB a* and YCrCb Cr over all skin pixels |

### Preprocessing pipeline (OpenCV)
1. Resize to 512×512
2. CLAHE (clipLimit=3.0, tileGridSize=8×8) on grayscale
3. Haar cascade face detection — 4-attempt fallback chain (frontal default + alt2)
4. ROI mask — eyes, nose, lips blacked out via sub-cascades
5. YCrCb skin segmentation + morphological close/open
6. Adaptive lesion thresholding — requires both Cr > thr_cr AND a* > thr_a simultaneously
7. Connected-component shape filtering — aspect ratio, fill ratio, local a* contrast

## Training Data

Subset of the **ACNE04** dataset — 3-class balanced split:

| Split | acne1 (mild) | acne2 (moderate) | acne3 (severe) |
|---|---|---|---|
| Train | 300 | 300 | 300 |
| Test | 218 | 61 | 34 |

## Results (42-dim feature set, 3-class)

| Rank | Model | Accuracy | Precision | Recall | F1 |
|---|---|---|---|---|---|
| 🥇 1 | **SGD Classifier** | **0.7542** | 0.7530 | 0.7542 | **0.7504** |
| 2 | CatBoost | 0.7318 | **0.7796** | 0.7318 | 0.7494 |
| 3 | Calibrated Linear SVM | 0.7486 | 0.7503 | 0.7486 | 0.7466 |
| 4 | SVM (RBF) | 0.7263 | 0.7605 | 0.7263 | 0.7399 |
| 5 | LDA | 0.7207 | 0.7615 | 0.7207 | 0.7371 |
| 6 | Logistic Regression | 0.7207 | 0.7588 | 0.7207 | 0.7360 |
| 7 | MLP | 0.7151 | 0.7558 | 0.7151 | 0.7301 |
| 8 | Stacking Ensemble (top-5) | 0.7151 | 0.7511 | 0.7151 | 0.7297 |
| 9 | Ridge Classifier | 0.7207 | 0.7309 | 0.7207 | 0.7233 |
| 10 | KNN | 0.7095 | 0.7394 | 0.7095 | 0.7222 |
| 11–21 | *(see Evaluation_Summary(42dim).txt)* | | | | |

**Per-class note:** acne2 (moderate) is the hardest class — best F1 only 0.456 (SVM RBF).
Severe acne3 best F1 0.553 (CatBoost). Full per-class rankings in the summary file.

## Files

```
model_42dim/
  acne_sgd_classifier_model.pkl         ← overall champion  (F1=0.7504)
  acne_catboost_model.pkl               ← best precision     (0.7796)
  acne_svm_rbf_model.pkl                ← best acne2 F1      (0.456)
  acne_stacking_ensemble_model.pkl      ← top-5 stacking
  acne_voting_ensemble_model.pkl        ← top-3 soft voting
  acne_extra_trees_model.pkl
  acne_random_forest_model.pkl
  acne_bagging_svm_model.pkl
  acne_gradient_boosting_model.pkl
  acne_histgradientboosting_model.pkl
  acne_adaboost_model.pkl
  acne_knn_model.pkl
  acne_lda_model.pkl
  acne_logistic_regression_model.pkl
  acne_mlp_model.pkl
  acne_qda_model.pkl
  acne_gaussian_nb_model.pkl
  acne_ridge_classifier_model.pkl
  acne_calibrated_linear_svm_model.pkl
  acne_svm_linear_model.pkl
  acne_svm_polynomial_model.pkl
Evaluation_Summary(42dim).txt           ← full per-class metrics table
```

## Usage

```python
import joblib
import numpy as np

# Load champion model
model = joblib.load("model_42dim/acne_sgd_classifier_model.pkl")

# feature_vec: 42-dim numpy array from the extraction pipeline (see preprocessing above)
label = model.predict(feature_vec.reshape(1, -1))[0]
# Returns: 'acne1_1024' (mild) | 'acne2_1024' (moderate) | 'acne3_1024' (severe)

# Confidence (available on most models)
proba = model.predict_proba(feature_vec.reshape(1, -1))[0]
```

### Download via huggingface_hub

```python
from huggingface_hub import snapshot_download

path = snapshot_download(repo_id="will702/acne-cv-models")
# models at: path/model_42dim/*.pkl
```

## Requirements

```
scikit-learn==1.7.2   # must match training version exactly
catboost
joblib
numpy
opencv-python-headless
scikit-image
```

## Limitations

- Trained on ACNE04 (Asian skin tones, studio lighting). May underperform on other demographics or lighting conditions.
- acne2 (moderate) classification is substantially weaker than acne1/acne3 — class imbalance in test set.
- No CNN/deep features — intentionally classical for interpretability and the interactive playground.

## Citation

If you use these models, please cite the ACNE04 dataset:

```bibtex
@inproceedings{wu2019joint,
  title={Joint Acne Image Grading and Counting via Label Distribution Learning},
  author={Wu, Xiaoping and Liang, Wen and Yu, Kezhou and Xu, Fei and Liang, Weiwei and others},
  booktitle={ICCV},
  year={2019}
}
```