Metadata-Version: 2.4
Name: open-vvv
Version: 0.8.0
Summary: A fast, minimalist 3D/4D medical image viewer, successor to VV.
Author-email: David Sarrut <david.sarrut@creatis.insa-lyon.fr>
License-Expression: LGPL-3.0-only
Project-URL: Homepage, https://github.com/dsarrut/vvv
Project-URL: Documentation, https://github.com/dsarrut/vvv/blob/master/user_docs/README.md
Project-URL: Source, https://github.com/dsarrut/vvv
Project-URL: Issues, https://github.com/dsarrut/vvv/issues
Keywords: medical imaging,image viewer,DICOM,NIfTI,radiotherapy,4D,MPR
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Environment :: X11 Applications
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: SimpleITK
Requires-Dist: dearpygui>=2.3.1
Requires-Dist: numpy
Requires-Dist: scikit-image
Requires-Dist: Pillow
Requires-Dist: setproctitle
Requires-Dist: pydicom
Requires-Dist: pyobjc-framework-Cocoa; sys_platform == "darwin"
Requires-Dist: fabio
Requires-Dist: numba
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: fonttools; extra == "dev"
Provides-Extra: memory
Requires-Dist: psutil; extra == "memory"
Dynamic: license-file

# VVV

**VVV** is a fast, research-oriented, and "minimalist" 3D/4D (medical) image viewer, conceived as a successor to [VV](https://github.com/open-vv).

📖 **[Complete User Documentation](https://github.com/dsarrut/vvv/blob/master/user_docs/README.md)** | **[Getting Started Guide](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_01_overview.md)** | **[CLI Reference](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_03_command_line.md)**

---

## Highlights

- **Fast & Minimalist:** Instant startup, keyboard and command-line driven.
- **Multi-Planar Reconstruction (MPR):** Seamless switching between Axial (`F1`), Coronal (`F2`), and Sagittal (`F3`) planes.
- **Formats & 4D Support:** Reads standard medical formats (`.nii`, `.nii.gz`, `.mha`, `.mhd`, `.nrrd`, `.dcm`, etc.) and multi-frame 4D series (cardiac/respiratory phases).
- **Sub-Pixel Synchronization:** Synchronize pan, zoom, and crosshair slices across multiple image viewers.
- **Image Fusion & Overlays:** Alpha blending, checkerboard, difference maps, colormaps, and displacement vector fields (DVF).
- **ROIs & RT-STRUCT:** Native sub-pixel RT-STRUCT contour rendering, binary masks, and interactive thresholding.
- **Radiotherapy Tools:** Quantitative dose visualization, isodose contours/wash, and interactive Dose-Volume Histograms (DVH).
- **Measurement & Alignment:** 1D line profiles (`P`), 3D point landmarks, publication legends (`L`), and 6-DOF manual rigid registration.
- **Sessions & Workspaces:** Save and reload full multi-viewer workspaces (`.vvw`), with automatic history.

> **In-App Help:** Click the **"baby" icon** at the bottom-left of the application to display interactive guides, shortcuts, and tooltips directly inside the UI.

---

## Installation

```bash
pip install open-vvv
```

> **The package is `open-vvv`**: `pip install vvv` installs an unrelated project (a 2012 code-validation tool) that happens to own the `vvv` name on PyPI. The installed command is `vvv`.

Requires Python 3.10 to 3.14, on Linux (x64), Windows (x64) or macOS 13+ on Apple Silicon. Intel Macs and Windows on ARM are not supported: DearPyGui (and SimpleITK on Windows ARM) provide no wheels for them.

Or install the development version from source:

```bash
git clone https://github.com/dsarrut/vvv
cd vvv
pip install -e .          # or pip install -e ".[dev]" to also get the test tools (pytest, fonttools)
```

<details>
<summary><b>Linux Note (Clipboard support for screenshots)</b></summary>

On Linux, copying screenshots directly to the system clipboard requires `xclip` (X11) or `wl-clipboard` (Wayland):
```bash
sudo apt install xclip         # Ubuntu / Debian (X11)
# or: sudo apt install wl-clipboard   # Ubuntu / Debian (Wayland)
# or: sudo dnf install xclip          # Fedora / RHEL
```
If neither is installed, screenshots are automatically saved to `~/Pictures/vvv_screenshot_<timestamp>.png` (or `~/vvv_screenshot_...png`).
</details>

---

## Quick Start (CLI)

```bash
# View a single image
vvv ct.nii.gz

# Open two images synchronized
vvv ct.nii.gz spect.nii.gz -s

# Fuse two images with a colormap
vvv ct.nii.gz, spect.nii.gz, jet

# Overlay an image with a binary mask
vvv ct.nii.gz + labels.nii.gz

# Restore a saved session
vvv my_session.vvw
```

For more CLI options and syntax, see the **[CLI Documentation](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_03_command_line.md)**.

---

## Screenshots

| Single 3D Image | Image Fusion |
| :---: | :---: |
| ![vvv ct.nii.gz](https://raw.githubusercontent.com/dsarrut/vvv/master/screenshots/ct.png) | ![vvv ct.nii.gz, spect.nii.gz, jet](https://raw.githubusercontent.com/dsarrut/vvv/master/screenshots/ct_spect.png) |

| 4D Sequence | ROI Contours |
| :---: | :---: |
| ![vvv ct_4D.mha](https://raw.githubusercontent.com/dsarrut/vvv/master/screenshots/ct_4d.png) | ![vvv and open ROIs](https://raw.githubusercontent.com/dsarrut/vvv/master/screenshots/rois.png) |

| DICOM Series Browser |
| :---: |
| ![vvv and mini DICOM browser](https://raw.githubusercontent.com/dsarrut/vvv/master/screenshots/dicom.png) |

---

## User Documentation

Explore the detailed topic guides in [`user_docs/`](https://github.com/dsarrut/vvv/blob/master/user_docs/README.md):

- [01. Overview & Interface](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_01_overview.md)
- [02. Working with Images](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_02_images.md)
- [03. Command-Line Interface](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_03_command_line.md)
- [04. Workspaces & Sessions](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_04_workspaces_and_sessions.md)
- [05. Multi-Viewer Synchronization](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_05_synchronisation.md)
- [06. Fusion & Overlays](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_06_fusion_and_overlays.md)
- [07. Intensity, Units & Colormaps](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_07_intensity_and_units.md)
- [08. ROIs & Contours](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_08_roi_and_contours.md)
- [09. Interactive Thresholding](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_09_thresholding.md)
- [10. Line Profiles](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_10_profiles.md)
- [11. 3D Landmarks](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_11_landmarks.md)
- [12. Rigid Registration](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_12_registration.md)
- [13. Maximum Intensity Projection (MIP)](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_13_mip.md)
- [14. Displacement Vector Fields (DVF)](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_14_dvf.md)
- [15. DICOM Browser](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_15_dicom.md)
- [16. Radiation Dose & DVH](https://github.com/dsarrut/vvv/blob/master/user_docs/doc_16_dose.md)

---

*VVV has been carefully crafted with AI assistance (mostly Gemini, Claude) following the spirit of VV, focusing on performance, clean architecture, and research productivity.*
