🔬 OnSight Pathology – Local Development and Build Guide

📚 Documentation & Downloads
For full documentation, publication details, and pre-built executables, please visit our official website: onsightpathology.github.io

This document describes how to run OnSight Pathology locally, how to build the application from source on Windows and macOS, and where to find model training pipelines.

📦 Downloads

Pre-built packages and additional resources are available through the following platforms:

• Zenodo (primary, DOI-versioned):
  https://zenodo.org/records/20402050

---

💻 System Requirements

OnSight Pathology is designed to be cross-platform.

• Windows: Supported for both GPU and CPU builds.
• macOS: Supported for both Intel and Apple Silicon.
• Linux: Beta support available for the GPU version (please see the linux branch).
• Hardware (optional): NVIDIA GPU with CUDA 12.8 support for the GPU build. Apple Silicon GPUs are used via the MPS backend when available.

---

Running Locally (Development Mode)

1. Create a Virtual Environment

python -m venv onsight_env
onsight_env\Scripts\activate          # Windows
source onsight_env/bin/activate       # macOS / Linux

Confirm Python version:

python --version

Recommended: Python 3.11.9

---

2. Install Dependencies

Two dependency files are provided:

GPU:

pip install -r requirements.txt

CPU:

pip install -r requirements_cpu.txt

Device selection at runtime is handled by device_compat.py, which transparently picks CUDA → MPS → CPU in that order. No code changes are needed when switching machines.

---

3. Launch the Application

python app.py

This launches the PyQt6 desktop application. No additional configuration is required when running directly from source.

---

Building the Executable (PyInstaller)

Two build modes are supported and shared between Windows (app.spec) and macOS (app_mac.spec):

On Windows, you can also choose the output format:

Ensure PyInstaller is installed:

pip install pyinstaller

---

Windows Build

Local + HF build (bundled weights)

PowerShell:

$env:ONSIGHT_BUILD="local"
pyinstaller app.spec --noconfirm

Command Prompt:

set ONSIGHT_BUILD=local
pyinstaller app.spec --noconfirm

Output: dist\app_local\

HF-only build (online download, single exe)

$env:ONSIGHT_BUILD="hf"
pyinstaller app.spec --noconfirm

Output: dist\OnSight_HF.exe

CPU-only build

For machines without an NVIDIA GPU, set BUILD_TYPE=CPU before building.

$env:BUILD_TYPE="CPU"
$env:ONSIGHT_BUILD="local"
pyinstaller app.spec --noconfirm

---

macOS Build

The full Mac build pipeline is automated in build_mac.sh:

chmod +x build_mac.sh
./build_mac.sh

This script performs:

1. Clean previous build/ and dist/.
2. Run PyInstaller with app_mac.spec (defaults to ONSIGHT_BUILD=local).
3. Sign every inner .dylib / .so with the ad-hoc identity.
4. Ad-hoc sign the full .app bundle with onsight.entitlements.

Outputs:

dist/OnSightPathology_App.app

For an HF-only Mac build, set ONSIGHT_BUILD=hf before invoking the script (or run PyInstaller directly with app_mac.spec).

macOS-specific runtime permission handling (Screen Recording, Accessibility, Input Monitoring) is centralized in mac_permissions.py and surfaced through MacPermissionDialog.py.

---

Creating a Windows Installer (Inno Setup)

OnSight Pathology can be packaged using Inno Setup 6.5 or newer.

Download: https://jrsoftware.org/isdl.php

Two installer scripts are provided:

Building from the onedir build

Default (local with bundled weights):

iscc installer.iss

HF-only onedir mode:

iscc installer.iss /DBuildMode=hf

Building from the single-exe HF build

iscc installer_hf.iss

Compiled installers are written to output/.

---

Training Pipelines

The repository includes a:

training/

directory containing scripts used to train the models bundled with OnSight Pathology.

Each model has its own subdirectory within training/ that contains:

• Data preparation scripts
• Dataset conversion utilities
• Training configuration files
• Training scripts
• Model-specific documentation

Detailed instructions for reproducing model training can be found in the respective README.md files within each model's training directory. These materials are provided for transparency and reproducibility.

---

Adding New Models

To integrate additional models into OnSight Pathology:

1. Add a metadata JSON file to: metadata/ (see existing files such as cell_vit.json, mib_yolo_1024.json, lingshu.json for reference).
2. Update settings.py to add a dropdown entry referencing the metadata file.
3. Modify utils.py to define how the model is initialized and loaded when selected.
4. Create a process_region_*.py file to define how the model performs inference on captured screen frames and how outputs are structured.

Existing implementations (process_region_cellpose.py, process_region_cellvit.py, process_region_YOLO.py, etc.) may be used as references.

---

Acknowledgements

The project was built on top of excellent open-source repositories including MIDOG++, CellViT, Cellpose, and the Lingshu medical VLM. We thank the authors and developers for their contributions.

---

Citation

If you use OnSight Pathology in research, please cite the associated publication listed at:

https://onsightpathology.github.io/