Research desktop software for DICOM CT visualization, vertebral segmentation, and interactive pedicle screw planning with synchronized MPR and 3D review.
Version: 0.1.0
Primary tested environment: macOS, Python 3.12
Creator: Sang-Min Park, MD, Ph.D.
Affiliation: Spine Center and Department of Orthopaedic Surgery, Seoul National University Bundang Hospital; Seoul National University College of Medicine
Contact: psmini@snu.ac.kr
Research and education use only. This software is not a certified medical device and must not be used as the sole basis for diagnosis, surgery, navigation, or patient care. Every segmentation, screw proposal, dimension, breach grade, and warning requires independent review by a qualified clinician.
- Multi-series DICOM CT loading
- Synchronized axial, sagittal, and coronal MPR
- CPU-based VTK volume rendering and selectable vertebral meshes
- Optional GPU-first TotalSegmentator integration with CPU retry
- Multi-level vertebra selection and automatic screw proposals
- Standard and screw-aligned oblique MPR review
- Direct entry, tip, and whole-screw editing in MPR and 3D
- Manual screw placement, distance measurement, and angle measurement
- JSON plan save/load and supported CSV/STL export
- Three UI themes, MPR pan/zoom, and 3D navigation controls
git clone https://github.com/grotyx/pedicle-screw-simulator.git
cd pedicle-screw-simulator
./scripts/run_app.shThe launcher creates a local venv, installs required packages, and starts the application.
./scripts/run_app.sh --with-totalsegThe first TotalSegmentator run may download model weights and can require substantial RAM or GPU memory.
python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
python main.py./scripts/run_app.sh --check
./scripts/run_app.sh --testThe current automated suite contains 469 tests.
For exact reproduction of the validated macOS/Python 3.12 environment:
python -m pip install -r requirements-lock.txtrequirements.txt provides compatible minimum versions. requirements-lock.txt records the exact core runtime and test environment used for v0.1.0 verification. requirements-desktop.txt pins the additional TotalSegmentator and PyTorch runtime used in standalone builds.
The GitHub Build desktop packages workflow creates separate archives for:
- macOS Apple Silicon (
.app) - Windows x64 (
.exewith its support folder)
See Desktop Build Guide. The macOS package is not Apple-notarized yet, so Gatekeeper may require right-clicking the app and selecting Open.
Standalone packages include TotalSegmentator 2.12.0, PyTorch, and nnU-Net. No separate Python installation is required. The first automatic segmentation downloads the open total task model weights to the user's TotalSegmentator cache, so an internet connection and additional disk space are required once. Later runs reuse the cached models.
- Open a DICOM CT folder.
- Verify the study in standard MPR and 3D.
- Run automatic segmentation.
- Select the vertebral levels to display and plan.
- Select Plan Screws to generate editable proposals.
- Select a screw and enter Screw MPR for trajectory-aligned review.
- Edit the entry, tip, shaft, diameter, or length as needed.
- Add measurements and save the planning file.
| Action | Control |
|---|---|
| Change standard slice | Mouse wheel |
| Zoom | Ctrl/Cmd + wheel or − / + |
| Move image and overlays | Enable Pan, then left-drag |
| Restore framing | Fit or Fit MPR |
| Window/level | Right-drag |
| Action | Control |
|---|---|
| Rotate | Left-drag |
| Zoom | Mouse wheel |
| Pan | Enable Pan, then drag; or Shift-drag |
| Focus | Double-click anatomy |
| Restore orientation | Reset View |
| Show internal screws | Increase Vertebra Transparency |
| Selection | Result |
|---|---|
| Double-click screw head | Move entry only |
| Double-click tip or distal shaft | Move tip only |
| Double-click middle shaft | Move the complete screw |
| Double-click again | Confirm the current position |
Esc |
Leave active movement mode |
- English User Guide
- 한국어 사용설명서
- Contributing
- Security and medical-data privacy
- Local DICOM data policy
- Authors and credits
- Citation metadata
- macOS and Windows build guide
Clinical DICOM files may expose identity through standard and private attributes, UIDs, filenames, overlays, metadata, or burned-in pixel annotations. This repository intentionally excludes local DICOM, NIfTI, logs, virtual environments, and generated exports.
Never upload clinical images, identifying screenshots, planning exports, or unredacted logs to GitHub issues, pull requests, releases, or CI artifacts.
main.py application entry point
src/ application source code
tests/ automated tests
scripts/ launcher and optional TotalSegmentator installer
docs/ English and Korean user guides
data/README.md local-data privacy instructions; no clinical data
- Automatic planning is geometric research software, not clinically validated navigation.
- Results depend on DICOM geometry and segmentation quality.
- Deformity, fracture, implants, artifacts, transitional anatomy, and poor segmentation may invalidate proposals.
- Standalone builds are provided for Apple Silicon macOS and Windows x64; Intel macOS and Linux packages are not provided.
- TotalSegmentator is bundled in standalone builds, but its model weights are downloaded on first use and require substantial memory and disk space.
- Clinical accuracy, inter-observer agreement, and prospective outcomes have not been established.
If this software supports academic work, use GitHub's Cite this repository function or the metadata in CITATION.cff:
Park S-M. Pedicle Screw Simulator (Version 0.1.0) [Computer software]. 2026. https://github.com/grotyx/pedicle-screw-simulator
A peer-reviewed software-paper DOI can be added as the preferred citation after publication without replacing the versioned software citation.
Project source code is released under the MIT License. Use, modification, and redistribution are permitted provided that the copyright and permission notice are retained.
Third-party components retain their own licenses. See Third-Party Notices. Distributors must separately comply with the PyQt6 GPL/commercial licensing terms and the licenses of VTK, SimpleITK, TotalSegmentator, PyTorch, nnU-Net, and other dependencies.