README.md

# CephVIT

CephVIT is a deep learning application for automatic **cephalometric landmark detection** from cephalogram images.

## Requirements

CephViT requires the following Python packages:

```text
torch
torchvision
torchaudio
timm
gradio
opencv-python
numpy
pillow
albumentations
cryptography
huggingface_hub
pandas
pydantic
tqdm
```

All dependencies are included in `requirements.txt` and can be installed with:

```bash
pip install -r requirements.txt
```


## Run Locally

Clone the repository:

```bash
git clone https://huggingface.co/nlm-dir/CephViT
cd CephViT
```

Install dependencies:

```bash
pip install -r requirements.txt
```

The included model checkpoint is encrypted. Set the `MODEL_KEY` environment variable before running:

```bash
export MODEL_KEY="2d65697cf6ad50c95a0a2558c73658a7"
```

Then start the app:

```bash
python app.py
```

## Project Structure

```text
CephVIT/
├── app.py                  # Gradio inference application
├── model.py                # Model definitions
├── heatmap_utils.py        # Heatmap generation and decoding
├── secure_torch_load.py    # Encrypted checkpoint loader
├── best.pt.enc             # Encrypted model checkpoint
└── requirements.txt
```

## License

OpenMDW 1.1.

## Citation

If you use CephViT in your work, please cite:

```bibtex
@inproceedings{hou2026automatic,
  title     = {Automatic Cephalometric Landmark Localization on {CBCT}-Derived Digitally Reconstructed Radiographs for Skeletal Malocclusion Classification},
  author    = {Hou, Benjamin and Almpani, Konstantinia and Lee, Janice S. and Lu, Zhiyong},
  booktitle = {Oral and Dental Image Analysis (ODIN 2026)},
  series    = {Lecture Notes in Computer Science},
  publisher = {Springer},
  year      = {2026},
  note      = {Accepted for publication}
}
```

*Accepted to ODIN 2026. Citation details will be updated when the Springer proceedings are published.*