DentXplain

DentXplain is a research prototype for hierarchical analysis of panoramic dental X-rays. The project compares a flat detector with a quadrant → tooth → FDI → diagnosis pipeline on the DENTEX benchmark.

The intended output is an auditable research result: each abnormal-tooth box is associated with a quadrant, tooth number, FDI number, diagnosis, confidence, and review status. It is not a diagnostic or treatment system.

5-second project tour

Current status

Phase 5 — the locked evaluation, research demo, and public repository are complete. C1 retained its development advantage on the official 50-image cohort. The selected research bundle is frozen for reproducible release packaging.

• Official source and archive sizes recorded.
• Validation annotation schema inspected.
• Validation image archive downloaded locally for integrity and visual review.
• Training archive downloaded, verified, and selectively extracted.
• The 705-image full-label pool is frozen as 564 training + 141 development validation images; the official 50-image cohort remains locked for final use.
• B0 YOLO labels and image hard-links are prepared without duplicating image bytes.
• The 960 px B0 run stopped at epoch 38 and selected epoch 28 on development mAP50-95. It reached 0.545 mAP50 and 0.368 mAP50-95 without touching the locked 50-image final cohort.
• The B1 pool excludes all 18 enumeration images that exactly overlap the final cohort. Its SHA-grouped split contains 492 training and 124 development-validation images with all 32 permanent-tooth FDI classes represented.
• The selected B1 checkpoint reached 0.951 mAP50 and 0.545 mAP50-95 across all 32 FDI classes on development validation.
• A 100-image joint development cohort unseen by both model training sets is frozen for B2 matching and abstention thresholds.
• On that cohort, B2 reached 0.502 joint F1 and C1 reached 0.510 while increasing correct diagnosis+FDI results from 313 to 320. The official final cohort remains untouched.
• Thresholded B0 error analysis confirms Periapical Lesion recall (0.259) and Caries false positives (290) as the priorities for the next controlled ablation.
• B0-R1 whole-image rare-class resampling was tested and rejected: AP50-95 fell from 0.369 to 0.355 and Periapical Lesion did not improve. The original B0 checkpoint remains selected.
• B0-R2 changed only global input resolution from 960 to 1280 px and was also rejected: AP50-95 reached 0.360 and Periapical Lesion fell to 0.181. Further development tuning is stopped; the selected B0+B1+C1 bundle is ready to freeze.
• The pre-frozen C1 configuration reached 0.372 joint precision, 0.610 recall, 0.463 F1, and 0.957 conditional FDI accuracy on the official 50-image final cohort. C1 reduced wrong FDI assignments from eight to five relative to B2.
• Ten-thousand-image-level bootstrap resamples place C1 F1 at 0.385–0.534; the paired C1−B2 interval includes zero, so superiority is not claimed.
• A FastAPI service and responsive browser interface now run the frozen bundle, provide annotated PNG output, separate pathology confidence from FDI matching, group related same-tooth candidates, and keep low-confidence candidates visible behind an explicit review control.

Dataset boundary

DENTEX data is not part of this repository. The current Hugging Face dataset card labels it CC BY-NC-SA 4.0; therefore data and derived data are handled as non-commercial research material and kept outside Git. The repository code is planned to use the MIT license independently.

Experiment design

1. Establish a simple fully-annotated flat detector baseline.
2. Add quadrant and enumeration supervision without treating missing diagnosis labels as negatives.
3. Apply FDI sequence and neighborhood consistency constraints.
4. Compare the same frozen split using AP/AR, FDI accuracy, class-wise recall, calibration, and risk–coverage.

First commands

python -m pip install -e ".[dev,audit]"
python scripts/audit_validation.py `
  --annotations data/raw/metadata/validation_triple.json `
  --images data/raw/validation_data/validation_data/quadrant_enumeration_disease/xrays `
  --output artifacts/data_audit/validation_audit.json
python -m pytest -q
python scripts/train_b0.py `
  --data data/processed/b0_yolo/dentex_b0.yaml `
  --epochs 1 --image-size 640 --batch 1 --name b0_smoke_640

python scripts/train_b0.py `
  --data data/processed/b0_yolo/dentex_b0.yaml `
  --epochs 40 --image-size 960 --batch 2 --name b0_main_960

python scripts/train_b1.py `
  --data data/processed/b1_yolo/dentex_b1.yaml `
  --epochs 40 --image-size 960 --batch 2 --name b1_main_960

Local research demo

The web interface runs the frozen B0+B1+C1 bundle, draws diagnosis boxes, assigns FDI numbers when the anatomical match clears the frozen threshold, and explicitly marks enumeration abstentions. The presentation layer groups related Caries and Deep Caries candidates on the same FDI tooth and defaults the annotated image to medium/high-priority findings; raw API findings remain unchanged and low-priority findings can still be reviewed. Every response requires expert review.

python -m pip install -e ".[service]"
python -m uvicorn dentxplain.service.app:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000/ for the visual demo or /docs for the API schema. The service expects the locally trained checkpoints at the paths recorded in configs/evaluation/dentex_final_v1.json; model weights and DENTEX data are not distributed by this repository.

See the data-gate record for confirmed facts and risks, and the experiment contract for the leakage-safe evaluation boundary and ordered model ladder. The complete B0 interpretation is recorded in the B0 result report, and the FDI baseline in the B1 result report. Joint cascade results are in the B2/C1 report, with the bottleneck analysis in the B0 error report and the rejected sampling experiment in the B0-R1 report. The resolution ablation is recorded in the B0-R2 report. The locked outcome and uncertainty analysis are in the final result report; intended use and limitations are summarized in the model card.