ADM_LSIR

Source-code release for ADM_LSIR: a physics-inspired laparoscopic aerosol degradation dataset.

This repository provides the reproducible software components used by the paper:

1. synthesis/ - Algorithm 1: synthesize aerosol-degradation images from a clean surgical frame plus one fog mask and one trajectory mask.
2. quality_screening/ - ResNet50-based quality screening that classifies laparoscopic frames as Clean or Degraded. The release includes both an interpretable LDA classifier workflow and an MLP classifier workflow.
3. reproduce_figures/ - reproducibility metadata for the technical validation figures, including thresholds, random seed, and the subset manifest template for Figures 7-11.

The image dataset itself is hosted separately on Zenodo: https://doi.org/10.5281/zenodo.20470138.

Repository layout

ADM_LSIR/
├── synthesis/
│   ├── synthesize.py
│   └── __init__.py
├── quality_screening/
│   ├── extract_features.py
│   ├── train_classifier.py
│   ├── predict.py
│   └── __init__.py
├── reproduce_figures/
│   ├── README.md
│   ├── thresholds_v1.0.json
│   ├── subset_manifest_v1.0.csv
│   └── run_technical_validation.py
├── examples/
├── docs/
├── environment.yml
├── Dockerfile
├── requirements.txt
├── RELEASE_NOTES_v1.0.0.md
├── LICENSE
└── README.md

Installation

Clone the repository:

git clone https://github.com/SweetDeathh/ADM_LSIR.git
cd ADM_LSIR

For a reproducible environment, use conda:

conda env create -f environment.yml
conda activate adm_lsir

or Docker:

docker build -t adm_lsir:1.0.0 .

For a lightweight local install:

pip install -r requirements.txt

A CUDA-capable GPU is recommended for ResNet50 feature extraction. CPU execution is supported but substantially slower.

Quick start

1. Synthesize one aerosol-degraded image

python -m synthesis.synthesize \
    --clean      path/to/clean.png \
    --mask-fog   path/to/mask_fog.png \
    --mask-white path/to/mask_white.png \
    --output     path/to/synthesized.png \
    --size       256

Programmatic use:

from synthesis import synthesize_one, imread_unicode, imwrite_unicode

clean = imread_unicode("path/to/clean.png")
mask_fog = imread_unicode("path/to/mask_fog.png")
mask_white = imread_unicode("path/to/mask_white.png")
syn = synthesize_one(clean, mask_fog, mask_white)
imwrite_unicode("out.png", syn)

The synthesis follows two steps:

1. Fog compositing: syn = 255 - (255 - clean) * (255 - mask_fog) / 255
2. Trajectory pasting: syn = (1 - mask_bin) * syn + mask_bin * 255

2. Train the quality screener

python -m quality_screening.extract_features \
    --input-dir path/to/clean_images \
    --output    cache/clean_features.npz

python -m quality_screening.extract_features \
    --input-dir path/to/degraded_images \
    --output    cache/degraded_features.npz

python -m quality_screening.train_classifier \
    --clean-features      cache/clean_features.npz \
    --degraded-features   cache/degraded_features.npz \
    --save-dir            models/ \
    --classifier          both

3. Screen new images

python -m quality_screening.predict \
    --model-dir   models/ \
    --classifier  lda \
    --input-dir   path/to/new_images \
    --output      results.csv

Reproducibility notes

• Random seed for cross-validation and comparative sampling: 42.
• ResNet50 backbone: torchvision.models.ResNet50_Weights.IMAGENET1K_V1.
• Recommended thresholds are stored in reproduce_figures/thresholds_v1.0.json.
• The exact comparative subset list for Figures 9-11 should be recorded in reproduce_figures/subset_manifest_v1.0.csv when all external benchmark files are staged locally.

Recommended thresholds

Mode	LDA threshold	MLP threshold	Use case
Balanced	-0.9543	0.6268	General dataset filtering
High Purity	0.0998	1.0000	Selected images must be clean
High Recall	0.0998	0.7776	Capture as many clean images as possible

Citation

Dataset:

Guo N, Pan J, Li T, Zhang Q, Li H, Li Y, Xu T, Wang F. ADM_LSIR: a physics-inspired laparoscopic aerosol degradation dataset. Zenodo. 2026. doi:10.5281/zenodo.20470138.

Source code:

Guo N, Pan J, Li T, Zhang Q, Li H, Li Y, Xu T, Wang F. ADM_LSIR source code, version 1.0.0. GitHub/archived release. 2026. Persistent identifier to be added after release archival.

License

This source code is released under the MIT License. See LICENSE for details.