Flatmount vessel segmentation -- Streamlit app

Interactive demo: upload one corneal flatmount image, run the trained segmentation model, see the vessel/cornea overlay, and optionally compute morphometry.

Recommended setup: public app, private code and model. The supervisors asked for the app to be openly viewable so other professors working on this kind of images can try it. That only needs the deployed app to be public (step 4). Keep the GitHub repo and the Hugging Face model repo private: the app downloads the weights server-side with a secret token, so visitors can use the model but never get the weights or the code. Because this project involves data covered by a confidentiality agreement, still make sure the PI has confirmed that exposing the trained model through a public app is allowed -- "private repo" reduces exposure, it does not by itself guarantee NDA compliance. That is a policy question, not a technical one.

Files in this folder (everything you need, nothing more)

• app_streamlit.py -- the app itself
• model_def.py, predict_core.py, analyze_core.py -- model/inference/ morphometry code, imported by the app
• requirements.txt -- Python dependencies for Streamlit Cloud to install
• .gitignore -- keeps the checkpoint, secrets and caches out of git

The trained model checkpoint (best_model.ckpt, ~90MB) must not be committed (.gitignore excludes it, even if a copy sits in this folder) -- see "1. Host the checkpoint" below.

1. Host the checkpoint on Hugging Face (private repo)

GitHub's browser upload only accepts files up to 25MB, and this checkpoint is ~90MB, so it needs to live somewhere else that the app can download it from at startup.

1. On https://huggingface.co, create a model repo (New Model), and set its visibility to Private (not Public) when creating it, or in its Settings afterwards if you already created it public.
2. Files and versions -> Add file -> Upload files -> drag in the checkpoint (on the cluster: checkpoints/vessel_train_tiled_52064/best_model_epoch_epoch=271.ckpt -- download it to your computer first, then upload here).
3. Note the file's URL pattern: https://huggingface.co/<your-username>/<repo-name>/resolve/main/<filename> -- you'll paste this into app_streamlit.py's CHECKPOINT_URL (see step 3). Since the repo is private, this URL alone does not let anyone download the file -- it also requires the access token from step 4, which is kept separately as a Streamlit secret, never committed to the code repo.
4. Create an access token: Profile picture -> Settings -> Access Tokens -> New token. "Read" permission is enough. Copy it somewhere safe (you'll paste it into Streamlit's secrets in step 5, not into any file in the repo).

2. Create the GitHub repository (private)

1. On https://github.com, New repository. Give it a name, and set visibility to Private. This is the "GitHub account" Mathilde asked about.
2. On the empty repo page, click uploading an existing file, and drag in the 5 code files from this folder: app_streamlit.py, model_def.py, predict_core.py, analyze_core.py, requirements.txt (and this README.md too, if you'd like).
3. Commit the changes.

3. Fill in the checkpoint URL (not the token -- see step 5)

In app_streamlit.py, find:

CHECKPOINT_URL = "PASTE_YOUR_CHECKPOINT_URL_HERE"

Replace with the URL from step 1.3. This is safe to keep in the code repo even though it's private data -- the URL by itself is useless without the access token, which never goes in this file. You can edit this directly in GitHub's browser file editor (pencil icon -> edit -> commit).

4. Deploy on Streamlit Community Cloud

1. On https://share.streamlit.io, sign in with GitHub, New app.
2. Pick your repository, branch main, Main file path: app_streamlit.py.
3. Streamlit Cloud needs permission to read your private GitHub repo -- it'll prompt you to grant this via GitHub's OAuth flow the first time.
4. Before or after the first deploy, go to the app's Settings -> Secrets and add:

   HF_TOKEN = "hf_xxxxxxxxxxxxxxxxxxxx"

   using the token from step 1.4. This is stored by Streamlit separately from your code repo and is what app_streamlit.py reads via st.secrets["HF_TOKEN"] to authenticate the checkpoint download.
5. Deploy. First build takes a few minutes (installing PyTorch/MONAI is not instant); the checkpoint then downloads on first use and is cached.

Making the deployed app public

In Streamlit Community Cloud, open the app -> Settings -> Sharing and choose the public option (wording changes over time; the alternative is an email allow-list). A private GitHub repo does not make the app private, and a public app does not expose a private repo. After switching, open the *.streamlit.app link in a private/incognito window to confirm it loads without signing in. Uploaded images are processed in memory and are not stored by the app, but anyone with the link can use it -- don't upload data you are not allowed to share.

Something to test carefully, not just assume works

Streamlit Community Cloud's free tier has limited memory (historically around 1GB) and no GPU. Full-resolution tiled inference on a large flatmount image (several thousand pixels per side) allocates fairly large arrays and runs on CPU there, so it may be slow (up to a couple of minutes) or, for very large images, could hit a memory limit. Test with one of the smaller validation images first before assuming it works for everything. If it's consistently too slow/crashes on large images, the fix would be adding a maximum-resolution downscale step before tiling in app_streamlit.py -- not implemented here since it would trade off segmentation detail, so it's worth trying without it first.