Initial BioMedVisionLab research workbench

.gitignore

@@ -0,0 +1,18 @@
+data/
+venv/
+__pycache__/
+.streamlit/secrets.toml
+
+data/
+embeddings/
+*.pyc
+.DS_Store
+
+*.pt
+*.pth
+*.onnx
+*.h5
+*.ckpt
+*.npy
+*.npz
+*.csv

.streamlit/config.toml

@@ -0,0 +1,5 @@
+[server]
+maxUploadSize = 500
+
+[browser]
+gatherUsageStats = false

README.md

@@ -0,0 +1,399 @@
+# BioMedVisionLab
+
+**Biomedical Imaging Visualization Toolkit for Retrieval and Super-Resolution**
+
+BioMedVisionLab is a polished, professor-facing Streamlit workbench for evaluating biomedical image-like data. It supports visual inspection, embedding comparison, retrieval benchmarking, super-resolution baseline evaluation, future model-output comparison, contact-map visualization, and CSV experiment export.
+
+1. Chest X-ray similarity retrieval visualization
+2. Biomedical image super-resolution demo
+3. Grant Alignment Lab for chemical imaging and Hi-C contact-map research directions
+
+BioMedVisionLab is upload-first for deployed demonstrations. The app can use a built-in/local CXR embedding index when one is available, but it also works without a local Kaggle dataset by letting users upload biomedical images or contact-map matrices directly in the browser.
+
+The project is intended for education, research prototyping, professor-facing demonstrations, and portfolio presentation. It is not intended for medical diagnosis, triage, treatment, or clinical decision-making.
+
+## Overview
+
+BioMedVisionLab combines representation learning, medical image retrieval, CXR-specific encoder support, batch retrieval quality measurement, super-resolution baseline evaluation, model-output comparison, Hi-C-like matrix visualization, and report export in one interactive dashboard.
+
+- `build_index.py` scans a local chest X-ray dataset, extracts embeddings, and saves searchable encoder-specific indexes.
+- `app.py` launches a Streamlit toolkit with tabs for retrieval, super-resolution visualization, and grant-alignment demos.
+
+## Motivation
+
+Biomedical imaging research often needs visual, explainable tools for understanding what models learn and how image quality affects downstream interpretation. This project focuses on showing model behavior and image-processing concepts without making diagnostic claims.
+
+## Module 1: CXR Retrieval
+
+The CXR retrieval module visualizes similarity search over a local chest X-ray dataset.
+
+Features:
+
+- Loads saved embeddings from `embeddings/`
+- Shows a clear **Local CXR index available** or **Upload-only mode** status
+- Supports dataset image queries and uploaded image queries
+- If no saved embeddings are available, supports upload-first retrieval:
+  - upload a query image
+  - upload a small reference gallery of JPG/PNG/JPEG files
+  - build temporary in-session embeddings for the uploaded gallery
+  - retrieve visually similar uploaded reference images
+- Uploaded gallery retrieval is temporary and is not saved
+- Uses pretrained torchvision ResNet18 as a lightweight generic ImageNet feature-extraction baseline
+- Adds pretrained torchvision ResNet50 as a deeper generic ImageNet feature-extraction baseline
+- Optionally supports TorchXRayVision DenseNet121 as a CXR-specific embedding encoder when `torchxrayvision` is installed
+- Uses 512-dimensional L2-normalized embeddings for ResNet18, 2048-dimensional L2-normalized embeddings for ResNet50, and DenseNet feature embeddings for TorchXRayVision
+- Stores encoder-specific indexes in `embeddings/resnet18_imagenet/`, `embeddings/resnet50_imagenet/`, and `embeddings/torchxrayvision_densenet121/`
+- Stores metadata for encoder name, embedding dimension, dataset size, build time, and device
+- Lets the app sidebar switch between the generic ImageNet baseline and the CXR-specific encoder when their indexes are available
+- Retrieves top-k visually similar images with cosine similarity
+- Avoids returning the same image as the top result for dataset queries
+- Shows query image, query filename, query label, image resolution, embedding dimension, and query source
+- Uses colored clinical-style labels for `NORMAL`, `PNEUMONIA`, agreement state, and retrieval confidence
+- Includes a compact model card with encoder, embedding dimension, similarity metric, dataset, and clinical status
+- Adds a clinical-style retrieval triage panel for query source, majority retrieved pattern, agreement, similarity range, and review status
+- Reports retrieval quality metrics for dataset-selected queries:
+  - Top-k label agreement count
+  - Precision@K
+  - Mean cosine similarity
+- Shows Top-k sensitivity for Top-3, Top-5, and Top-10 label agreement when the query label is known
+- Shows a retrieval confidence badge using a simple heuristic based on top similarity and, when available, Precision@K
+- Makes clear that retrieval confidence is not clinical or diagnostic confidence
+- Renames retrieved examples as a **Similar Case Board**
+- Shows rank, filename, label badge, cosine similarity, query-label agreement, and a progress bar on each result card
+- Includes a compact result table with rank, filename, label, cosine similarity, and label agreement
+- Keeps compact charts for rank-based similarity scores and retrieved-label distribution
+- Adds a query-vs-retrieved comparison view with query image, selected retrieved image, and a simple absolute difference map
+- Adds an **Intensity Heatmap Preview** for the query image
+- Exports the current retrieval experiment as CSV
+- Adds batch retrieval evaluation for 20, 50, or 100 sampled queries
+- Reports Mean Precision@K, label-specific Precision@K, Top-1 match rate, same-label counts, and retrieved-label distributions
+- Exports a batch retrieval benchmark CSV with one row per retrieved result for comparing encoder experiments
+- Adds an Encoder Comparison Benchmark when both indexes exist, using the same sampled queries to compare Mean Precision@K, class Precision@K, and Top-1 match rate
+- Includes the Research Extension Roadmap in the CXR Retrieval tab only, so retrieval users can explore future encoder, explainability, text, microscopy, diffusion, and genomics directions without repeating the roadmap across every tab
+
+The intensity heatmap is a simple grayscale intensity visualization. It is not Grad-CAM and does not provide model-based lesion localization.
+The difference map is a visual comparison aid, not a clinical finding map.
+
+## Module 2: Super-Resolution Demo
+
+The super-resolution module demonstrates the basic image degradation and reconstruction problem.
+
+Features:
+
+- Select an image from the indexed CXR dataset or upload a biomedical image
+- Works in upload-only deployments when no local CXR index exists
+- Simulate low resolution by downsampling by `2x` or `4x`
+- Reconstruct the image back to original size with bicubic interpolation
+- Display original, simulated low-resolution, and bicubic enhanced images side by side
+- Calculate MSE, PSNR, and SSIM when `scikit-image` is available
+- Compare zoomed center crops of the original, low-resolution, and bicubic enhanced images
+- Use a crop-size slider for quick local inspection
+- Includes a baseline model card for degradation, reconstruction, metrics, and clinical status
+- Adds an artifact risk card explaining that bicubic interpolation can smooth fine structures and cannot recover true missing anatomical detail
+- Provides a large preview selector for original, simulated low-resolution, and bicubic enhanced images
+- Supports uploading a model-enhanced image for comparison against the bicubic baseline
+- Shows bicubic vs original and uploaded-output vs original metrics in a comparison table
+- Adds batch super-resolution evaluation for 20, 50, or 100 indexed images
+- Exports batch super-resolution benchmark CSV files for method comparison
+- Exports the current super-resolution experiment as CSV
+- Explains the relevance of throughput/resolution tradeoffs, microscopy/pathology, and future diffusion-based enhancement
+- Adds a **Super-Resolution Exploration Studio** with prompts for uploaded learned outputs, crop-level inspection, metric deltas, and artifact checks
+
+This module is a lightweight educational prototype. Bicubic super-resolution is an educational baseline, not a trained AI model or a clinical enhancement method.
+
+## Module 3: Grant Alignment Lab
+
+The Grant Alignment Lab frames BioMedVisionLab as a reusable visual evaluation workbench for biomedical imaging and multimodal biology research.
+
+Features:
+
+- Chemical Imaging Super-Resolution alignment card:
+  - low-resolution biomedical/chemical imaging challenge
+  - current support for degradation simulation, bicubic baseline, PSNR, SSIM, MSE, crop inspection, and artifact warnings
+  - future diffusion-based super-resolution, microscopy/pathology datasets, and SRS/Raman-style image support
+- Hi-C Contact Map Visualization alignment card:
+  - sparse, noisy, high-dimensional image-like contact matrices
+  - current support for matrix visualization and resolution-enhancement concepts
+  - future real Hi-C/Micro-C upload, contact-map retrieval, and RNA-seq/ATAC-seq metadata integration
+- Synthetic Hi-C contact map mini-demo:
+  - generates synthetic contact matrices with diagonal structure and loop-like bright spots
+  - simulates low-resolution contact maps and bicubic upscaling
+  - displays original, low-resolution, upscaled, and absolute difference maps
+  - reports Matrix MSE, Matrix PSNR, and optional Matrix SSIM
+  - exports the synthetic Hi-C demo report as CSV
+- Upload support for `.npy` or `.csv` square contact matrices:
+  - validates square matrices
+  - safely normalizes values
+  - displays uploaded contact map, simulated low-resolution map, bicubic-upscaled map, and difference map
+  - exports Hi-C matrix evaluation metrics as CSV
+- Adds a **Multimodal Exploration Hub** for matrix uploads, low/high-resolution matrix comparison, diagonal profiles, and future metadata links
+
+The deployed app can therefore demonstrate radiology image retrieval, biomedical super-resolution baselines, and contact-map matrix visualization without requiring users to download the repository or install the original local dataset.
+
+Synthetic contact maps are used only to demonstrate the visualization interface. They are not biological results.
+Uploaded contact maps are visualized as matrix images. This prototype does not yet perform biological feature calling.
+
+## Biomedical Imaging Relevance
+
+BioMedVisionLab connects to common biomedical imaging research workflows:
+
+- Chest X-ray dataset exploration
+- Visual search and content-based medical image retrieval
+- Representation learning with pretrained vision models
+- Retrieval confidence and uncertainty-style summaries for visual search behavior
+- Clinical-style retrieval triage and Top-k sensitivity checks for research review
+- Comparing generic ImageNet embeddings with CXR-specific embeddings
+- Batch measurement of retrieval quality across repeated query samples
+- Query-vs-retrieved visual comparison with a non-clinical difference map
+- Explainable AI previews and future Grad-CAM visual grounding
+- Image degradation and reconstruction experiments
+- Super-resolution metrics for biomedical imaging baselines
+- Artifact-risk framing for educational super-resolution baselines
+- Comparing future learned or diffusion-based super-resolution outputs against bicubic interpolation
+- Chemical imaging super-resolution grant prototypes
+- Chromatin contact-map visualization and retrieval concepts
+- Multimodal biology workbench patterns for image-like matrices and metadata
+- Educational demonstrations for biomedical AI portfolios
+- Conceptual links to microscopy and pathology super-resolution
+
+## Connection to Core Concepts
+
+**Representation learning:** ResNet18, ResNet50, or TorchXRayVision converts images into numerical embeddings that summarize visual patterns.
+
+**Image retrieval:** Cosine similarity compares embeddings and ranks images by visual resemblance.
+
+**Explainable AI:** The dashboard includes a simple intensity heatmap preview as a non-diagnostic visualization placeholder. Future work can add Grad-CAM or other model-based visual grounding.
+
+**Super-resolution:** The demo degrades an image and reconstructs it, illustrating why high-resolution structure matters in biomedical imaging.
+
+## Dataset Instructions
+
+Place a small public chest X-ray dataset inside:
+
+```text
+data/chest_xray/
+    train/
+        NORMAL/
+        PNEUMONIA/
+    test/
+        NORMAL/
+        PNEUMONIA/
+    val/
+        NORMAL/
+        PNEUMONIA/
+```
+
+The app also works if only `train/` and `test/` exist.
+
+Supported image formats:
+
+- `.jpg`
+- `.jpeg`
+- `.png`
+
+## Setup Commands
+
+Create and activate a virtual environment:
+
+```bash
+python -m venv venv
+```
+
+On Windows:
+
+```bash
+venv\Scripts\activate
+```
+
+On macOS or Linux:
+
+```bash
+source venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Build the CXR retrieval index with the default generic ResNet18 ImageNet encoder:
+
+```bash
+python build_index.py --encoder resnet18_imagenet
+```
+
+Build an optional TorchXRayVision DenseNet121 CXR-specific index:
+
+```bash
+python build_index.py --encoder torchxrayvision_densenet121
+```
+
+Indexes are stored separately:
+
+```text
+embeddings/
+    resnet18_imagenet/
+    resnet50_imagenet/
+    torchxrayvision_densenet121/
+```
+
+Build the deeper generic ResNet50 ImageNet encoder:
+
+```bash
+python build_index.py --encoder resnet50_imagenet
+```
+
+ResNet18 is a lightweight generic natural-image baseline pretrained on ImageNet. ResNet50 is a deeper generic ImageNet baseline with a 2048-dimensional penultimate feature vector. TorchXRayVision DenseNet121 is pretrained for chest X-ray tasks and is included to support research comparisons between generic and CXR-specific visual representations.
+
+Run the dashboard:
+
+```bash
+python -m streamlit run app.py
+```
+
+If `streamlit` is available on your PATH, this also works:
+
+```bash
+streamlit run app.py
+```
+
+## Deployment on Hugging Face Spaces
+
+BioMedVisionLab is prepared for Hugging Face Spaces as a Streamlit app. The main entry file is:
+
+```text
+app.py
+```
+
+The Streamlit configuration is stored in:
+
+```text
+.streamlit/config.toml
+```
+
+with a `500 MB` upload limit and browser usage-stat collection disabled.
+
+### Run Locally
+
+Install dependencies and start the app:
+
+```bash
+pip install -r requirements.txt
+python -m streamlit run app.py
+```
+
+Local CXR indexes are optional. If no embeddings are present, the app opens in upload-only mode for query/gallery retrieval, image super-resolution, and contact-map visualization.
+
+### Deploy to Hugging Face Spaces
+
+1. Create a new Hugging Face Space.
+2. Select **Streamlit** as the Space SDK.
+3. Upload or push the repository files, including:
+   - `app.py`
+   - `requirements.txt`
+   - `.streamlit/config.toml`
+   - `README.md`
+4. Spaces will install dependencies from `requirements.txt` and run the Streamlit app from `app.py`.
+5. Optional local embedding folders can be added under `embeddings/`, but deployed demos can also run without them through upload-first workflows.
+
+### Deployment Limitations
+
+- Uploaded files are temporary and are not saved as a persistent dataset.
+- Large datasets should be uploaded as smaller representative samples.
+- The app is not for diagnosis, triage, treatment, or clinical decision-making.
+- Heavy diffusion-model training or large-scale model inference is not supported in this demo.
+- If TorchXRayVision is unavailable, uploaded-image embedding falls back to ResNet18 and the app shows a warning.
+- If `cooler` is unavailable, `.cool` and `.mcool` upload is disabled with a helpful message; `.csv` and `.npy` contact matrices still work.
+
+## Method Details
+
+For CXR retrieval, each image is:
+
+1. Converted to RGB
+2. Resized to `224x224`
+3. Normalized with ImageNet mean and standard deviation
+4. Passed through pretrained ResNet18 with the classifier removed
+5. Converted into a 512-dimensional embedding
+6. L2-normalized for cosine similarity search
+7. Compared with indexed embeddings using cosine similarity
+8. Summarized with rank-based similarity, label agreement, Precision@K, and mean similarity
+9. Reviewed with model-card metadata, retrieval triage, Top-k sensitivity, and optional visual comparison
+10. Exported as a CSV experiment report
+
+Batch retrieval evaluation samples labeled dataset queries, retrieves Top-k neighbors while excluding the query image, and exports one row per retrieved result. This makes CSV exports useful for comparing generic and CXR-specific encoders.
+
+Retrieval confidence is a heuristic:
+
+- High confidence for dataset queries if top similarity is at least `0.90` and Precision@K is at least `0.80`
+- Medium confidence if top similarity is at least `0.80`
+- Low confidence otherwise
+- Uploaded images use top similarity only because query-label agreement is unavailable
+
+For super-resolution, each image is:
+
+1. Converted safely to RGB
+2. Downsampled by `2x` or `4x`
+3. Reconstructed to original size using bicubic interpolation
+4. Compared against the original image using MSE, PSNR, and optional SSIM
+5. Displayed with center-crop comparisons for local detail inspection
+6. Reviewed with artifact-risk and baseline-method cards
+7. Exported as a CSV experiment report
+
+ChemDiffuse-style comparison allows an externally generated enhanced image to be uploaded and compared against the original image and bicubic baseline using PSNR, SSIM, and MSE.
+
+For the synthetic Hi-C mini-demo:
+
+1. A synthetic square contact matrix is generated with diagonal structure and loop-like bright spots.
+2. Noise is added using the dashboard slider.
+3. The matrix is downsampled by `2x` or `4x`.
+4. The low-resolution matrix is bicubic-upscaled to the original matrix size.
+5. Matrix MSE, Matrix PSNR, and optional Matrix SSIM are reported.
+6. The demo can be exported as a CSV report.
+
+## Limitations
+
+- ResNet18 and ResNet50 are pretrained on natural images, not chest X-rays.
+- TorchXRayVision support requires optional dependency installation and a separately built index.
+- Retrieval results show visual similarity, not clinical equivalence.
+- Retrieval confidence is not clinical confidence.
+- Retrieval triage is a research dashboard summary, not clinical triage.
+- Query-vs-retrieved difference maps are visual comparison aids, not finding maps.
+- Folder labels are used only for visualization.
+- The intensity heatmap is not Grad-CAM and does not identify pathology.
+- Bicubic interpolation is a simple baseline, not a learned super-resolution model.
+- Bicubic interpolation may smooth fine detail and cannot recover true missing anatomical structure.
+- Synthetic Hi-C contact maps are interface demonstrations only and are not biological results.
+- Uploaded Hi-C/contact matrices are visualized as matrix images and are not biologically interpreted.
+- PSNR is a basic image-quality metric and does not measure clinical usefulness.
+- SSIM is an image-similarity metric and does not measure clinical usefulness.
+- The project should not be used for diagnosis, triage, treatment, or clinical decision-making.
+
+## CXR Retrieval Research Extension Roadmap
+
+The Research Extension Roadmap is shown only in the CXR Retrieval tab. The Super-Resolution and Grant Alignment tabs have their own exploration sections instead of repeating the same roadmap.
+
+- CXR-specific encoders such as TorchXRayVision or medical foundation models
+- Grad-CAM visual grounding
+- Report-aware retrieval using radiology text
+- Microscopy/pathology super-resolution datasets
+- Diffusion-based biomedical image enhancement
+- Learned super-resolution models such as SRCNN, EDSR, or SwinIR variants
+- Metadata-aware retrieval filters
+- Hi-C contact map visualization as a future biomedical data visualization extension
+- Real Hi-C/Micro-C upload, contact-map retrieval, and omics metadata integration
+- Chemical imaging super-resolution with SRS/Raman-style data
+- Grant-ready experiment report templates
+
+## Disclaimer
+
+BioMedVisionLab is a research visualization prototype and is not intended for medical diagnosis or clinical decision-making.
+
+- Retrieval confidence is not diagnostic or clinical confidence.
+- The intensity heatmap preview is not Grad-CAM.
+- Bicubic super-resolution is an educational baseline, not a trained AI model.
+- Synthetic Hi-C contact maps are not biological results.
+
+## Suggested LinkedIn Project Description
+
+Built **BioMedVisionLab**, a reusable biomedical visual evaluation workbench in Python and Streamlit. The app includes chest X-ray similarity retrieval using pretrained ResNet18, ResNet50, and optional TorchXRayVision embeddings with cosine similarity, retrieval triage, Top-k sensitivity, query-vs-result comparison, experiment report export, an educational super-resolution demo with MSE, PSNR, SSIM, artifact-risk framing, and a Grant Alignment Lab with a synthetic Hi-C contact-map mini-demo. The project highlights medical image retrieval, chemical imaging super-resolution, explainable AI, and chromatin contact-map visualization concepts for research and portfolio demonstration, not clinical diagnosis or biological interpretation.

build_index.py

@@ -0,0 +1,291 @@
+import argparse
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch.nn as nn
+from PIL import Image, UnidentifiedImageError
+from torchvision import models, transforms
+
+try:
+    import torchxrayvision as xrv
+except ImportError:
+    xrv = None
+
+
+DATA_DIR = Path("data/chest_xray")
+EMBEDDINGS_ROOT = Path("embeddings")
+ENCODER_TYPE = "resnet18_imagenet"
+VALID_EXTENSIONS = {".jpg", ".jpeg", ".png"}
+VALID_LABELS = {"NORMAL", "PNEUMONIA"}
+
+IMAGENET_MEAN = [0.485, 0.456, 0.406]
+IMAGENET_STD = [0.229, 0.224, 0.225]
+
+
+class EncoderBundle:
+    def __init__(self, key: str, name: str, model: nn.Module, transform: transforms.Compose, output_dim: int):
+        self.key = key
+        self.name = name
+        self.model = model
+        self.transform = transform
+        self.output_dim = output_dim
+
+
+ENCODER_CONFIGS = {
+    "resnet18_imagenet": {
+        "name": "ResNet18 ImageNet baseline",
+        "output_dim": 512,
+    },
+    "resnet50_imagenet": {
+        "name": "ResNet50 ImageNet baseline",
+        "output_dim": 2048,
+    },
+    "torchxrayvision_densenet121": {
+        "name": "TorchXRayVision DenseNet121 CXR encoder",
+        "output_dim": 1024,
+    },
+}
+
+
+def canonical_encoder_name(encoder_name: str) -> str:
+    aliases = {
+        "resnet18": "resnet18_imagenet",
+        "resnet50": "resnet50_imagenet",
+        "torchxrayvision": "torchxrayvision_densenet121",
+    }
+    return aliases.get(encoder_name, encoder_name)
+
+
+def find_image_files(data_dir: Path) -> list[Path]:
+    """Find supported image files that live under NORMAL or PNEUMONIA folders."""
+    image_files = []
+
+    for path in data_dir.rglob("*"):
+        if not path.is_file() or path.suffix.lower() not in VALID_EXTENSIONS:
+            continue
+
+        if infer_label(path) in VALID_LABELS:
+            image_files.append(path)
+
+    return sorted(image_files)
+
+
+def infer_label(image_path: Path) -> str:
+    """Infer a chest X-ray label from any parent folder named NORMAL or PNEUMONIA."""
+    for parent in image_path.parents:
+        label = parent.name.upper()
+        if label in VALID_LABELS:
+            return label
+    return "UNKNOWN"
+
+
+def get_resnet_transform() -> transforms.Compose:
+    return transforms.Compose(
+        [
+            transforms.Resize((224, 224)),
+            transforms.Grayscale(num_output_channels=3),
+            transforms.ToTensor(),
+            transforms.Normalize(mean=IMAGENET_MEAN, std=IMAGENET_STD),
+        ]
+    )
+
+
+def get_xrv_transform() -> transforms.Compose:
+    return transforms.Compose(
+        [
+            transforms.Resize((224, 224)),
+            transforms.Grayscale(num_output_channels=1),
+            transforms.ToTensor(),
+            transforms.Lambda(lambda tensor: (tensor * 2048.0) - 1024.0),
+        ]
+    )
+
+
+def load_encoder(encoder_name: str, device: torch.device | None = None) -> EncoderBundle:
+    encoder_name = canonical_encoder_name(encoder_name)
+    device = device or torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    if encoder_name == "torchxrayvision_densenet121":
+        if xrv is None:
+            raise ImportError(
+                "torchxrayvision is not installed. Install requirements or use --encoder resnet18_imagenet."
+            )
+        model = xrv.models.DenseNet(weights="densenet121-res224-all")
+        model.op_threshs = None
+        model.to(device)
+        model.eval()
+        return EncoderBundle(
+            key="torchxrayvision_densenet121",
+            name="TorchXRayVision DenseNet121 CXR encoder",
+            model=model,
+            transform=get_xrv_transform(),
+            output_dim=1024,
+        )
+
+    if encoder_name == "resnet50_imagenet":
+        weights = models.ResNet50_Weights.DEFAULT
+        model = models.resnet50(weights=weights)
+        output_dim = 2048
+        encoder_label = "ResNet50 ImageNet baseline"
+    else:
+        weights = models.ResNet18_Weights.DEFAULT
+        model = models.resnet18(weights=weights)
+        output_dim = 512
+        encoder_label = "ResNet18 ImageNet baseline"
+    model.fc = nn.Identity()
+    model.to(device)
+    model.eval()
+    return EncoderBundle(
+        key=encoder_name,
+        name=encoder_label,
+        model=model,
+        transform=get_resnet_transform(),
+        output_dim=output_dim,
+    )
+
+
+def preprocess_image_for_encoder(image: Image.Image, encoder_name: str) -> torch.Tensor:
+    encoder_name = canonical_encoder_name(encoder_name)
+    transform = get_xrv_transform() if encoder_name == "torchxrayvision_densenet121" else get_resnet_transform()
+    return transform(image).unsqueeze(0)
+
+
+def load_rgb_image(image_path: Path) -> Image.Image:
+    """Open a chest X-ray and convert grayscale images to 3-channel RGB."""
+    return Image.open(image_path).convert("RGB")
+
+
+def extract_embedding(
+    image: Image.Image,
+    encoder_name: str,
+    encoder: EncoderBundle | None = None,
+    device: torch.device | None = None,
+) -> np.ndarray:
+    """Extract one L2-normalized embedding."""
+    encoder_name = canonical_encoder_name(encoder_name)
+    device = device or torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    encoder = encoder or load_encoder(encoder_name, device)
+    image_tensor = preprocess_image_for_encoder(image, encoder_name).to(device)
+
+    with torch.no_grad():
+        if encoder_name == "torchxrayvision_densenet121":
+            features = encoder.model.features(image_tensor)
+            features = torch.nn.functional.relu(features, inplace=False)
+            features = torch.nn.functional.adaptive_avg_pool2d(features, (1, 1))
+            embedding = torch.flatten(features, 1).cpu().numpy()[0]
+        else:
+            embedding = encoder.model(image_tensor).cpu().numpy()[0]
+
+    norm = np.linalg.norm(embedding)
+    if norm > 0:
+        embedding = embedding / norm
+
+    return embedding.astype(np.float32)
+
+
+def extract_embedding_from_path(
+    image_path: Path,
+    encoder: EncoderBundle,
+    device: torch.device,
+) -> np.ndarray | None:
+    try:
+        image = load_rgb_image(image_path)
+    except (OSError, UnidentifiedImageError) as error:
+        print(f"Skipping unreadable image: {image_path} ({error})")
+        return None
+    return extract_embedding(image, encoder.key, encoder, device)
+
+
+def encoder_feature_note(encoder_key: str) -> str:
+    if encoder_key == "torchxrayvision_densenet121":
+        return "TorchXRayVision DenseNet121 intermediate convolutional features with global average pooling."
+    if encoder_key == "resnet50_imagenet":
+        return "ResNet50 penultimate 2048-D feature vector."
+    return "ResNet18 penultimate 512-D feature vector."
+
+
+def build_index(encoder_type: str) -> None:
+    encoder_type = canonical_encoder_name(encoder_type)
+    if not DATA_DIR.exists():
+        raise FileNotFoundError(
+            "Dataset folder was not found. Please place images under data/chest_xray/ "
+            "with folders such as train/NORMAL and train/PNEUMONIA."
+        )
+
+    image_files = find_image_files(DATA_DIR)
+    if not image_files:
+        raise ValueError(
+            "No JPG, JPEG, or PNG images were found under data/chest_xray inside "
+            "NORMAL or PNEUMONIA folders."
+        )
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"Using device: {device}")
+
+    encoder = load_encoder(encoder_type, device)
+    print(f"Using encoder: {encoder.name}")
+
+    indexed_paths = []
+    labels = []
+    embeddings = []
+
+    for image_path in image_files:
+        embedding = extract_embedding_from_path(image_path, encoder, device)
+        if embedding is None:
+            continue
+
+        indexed_paths.append(str(image_path))
+        labels.append(infer_label(image_path))
+        embeddings.append(embedding)
+
+    if not embeddings:
+        raise ValueError("Images were found, but none could be read successfully.")
+
+    output_dir = EMBEDDINGS_ROOT / encoder.key
+    output_dir.mkdir(parents=True, exist_ok=True)
+    np.save(output_dir / "image_paths.npy", np.array(indexed_paths, dtype=object))
+    np.save(output_dir / "labels.npy", np.array(labels, dtype=object))
+    np.save(output_dir / "embeddings.npy", np.vstack(embeddings).astype(np.float32))
+
+    metadata = {
+        "encoder_key": encoder.key,
+        "encoder_name": encoder.name,
+        "embedding_dimension": int(np.vstack(embeddings).shape[1]),
+        "dataset_size": len(indexed_paths),
+        "build_time": datetime.now(timezone.utc).isoformat(),
+        "device": str(device),
+        "feature_note": encoder_feature_note(encoder.key),
+    }
+    (output_dir / "metadata.json").write_text(json.dumps(metadata, indent=2), encoding="utf-8")
+
+    print(f"Indexed {len(indexed_paths)} images.")
+    print(f"Saved embeddings to: {output_dir.resolve()}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Build BioMedVisionLab CXR embedding index.")
+    parser.add_argument(
+        "--encoder",
+        choices=[
+            "resnet18_imagenet",
+            "resnet50_imagenet",
+            "torchxrayvision_densenet121",
+            "resnet18",
+            "resnet50",
+            "torchxrayvision",
+        ],
+        default=ENCODER_TYPE,
+        help="Encoder used to build embeddings.",
+    )
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    try:
+        build_index(args.encoder)
+    except (FileNotFoundError, ValueError, ImportError) as error:
+        print(f"Error: {error}")
+        raise SystemExit(1)

requirements.txt

@@ -0,0 +1,10 @@
+streamlit
+torch
+torchvision
+Pillow
+numpy
+pandas
+scikit-image
+altair
+torchxrayvision
+cooler