# Clara Viz
NVIDIA Clara Viz is a platform for visualization of 2D/3D medical imaging data. It enables building applications
that leverage powerful volumetric visualization using CUDA-based ray tracing. It also allows viewing of multi resolution
images used in digital pathology.
<div style="display: flex; width: 100%; justify-content: center;">
<div style="padding: 5px; height: 200px;">
<img src="images/rendering.gif" alt="Volume Rendering"/>
</div>
<div style="padding: 5px; height: 200px;">
<img src="images/pathology.gif" alt="Pathology"/>
</div>
</div>
Clara Viz offers a Python Wrapper for rapid experimentation. It also includes a collection of
visual widgets for performing interactive medical image visualization in Jupyter Lab notebooks.
## Known issues
On Windows, starting with Chrome version 91 (also with Microsoft Edge) the interactive Jupyter widget is not working correctly. There is a delay in the interactive view after starting interaction. This is an issue with the default (D3D11) rendering backend of the browser. To fix this open `chrome://flags/#use-angle` and switch the backend to `OpenGL`.
## Requirements
* OS: Linux x86_64
* NVIDIA GPU: Pascal or newer, including Pascal, Volta, Turing and Ampere families
* NVIDIA driver: 450.36.06+
## Documentation
https://docs.nvidia.com/clara-viz/index.html
## Quick Start
### Installation
This will install all Clara Viz packages use pip:
```bash
$ pip install clara-viz
```
Clara Viz is using namespace packages. The main functionality is implemented in the 'clara-viz-core' package,
Jupyter Notebook widgets are found in the 'clara-viz-widgets' package.
So for example if you just need the renderer use
```bash
$ pip install clara-viz-core
```
### Use interactive widget in Jupyter Notebook
Install the Jupyter notebook widgets.
```bash
$ pip install clara-viz-widgets
```
Start Jupyter Lab, open the notebooks in the `notebooks` folder. Make sure Git LFS is installed when cloning the repo, else the data files are not downloaded correctly and you will see file open errors when using the example notebooks.
```python
from clara.viz.widgets import Widget
from clara.viz.core import Renderer
import numpy as np
# load a RAW CT data file (volume is 512x256x256 voxels)
input = np.fromfile("CT.raw", dtype=np.int16)
input = input.reshape((512, 256, 256))
display(Widget(Renderer(input)))
```
### Render CT data from Python
```python
from PIL import Image
import clara.viz.core
import numpy as np
# load a RAW CT data file (volume is 512x256x256 voxels)
input = np.fromfile("CT.raw", dtype=np.int16)
input = input.reshape((512, 256, 256))
# create the renderer
renderer = clara.viz.core.Renderer(input)
# render to a raw numpy array
output = renderer.render_image(1024, 768, image_type=clara.viz.core.ImageType.RAW_RGB_U8_DEPTH_U8)
rgb_data = np.asarray(output)[:, :, :3]
# show with PIL
image = Image.fromarray(rgb_data)
image.show()
```
## Use within a Docker container
Clara Viz requires CUDA, use a `base` container from `https://hub.docker.com/r/nvidia/cuda` for example `nvidia/cuda:11.4.2-base-ubuntu20.04`. By default the CUDA container exposes the `compute` and `utility` capabilities only. Clara Viz additionally needs the `graphics` and `video` capabilities. Therefore the docker container needs to be run with the `NVIDIA_DRIVER_CAPABILITIES` env variable set:
```bash
$ docker run -it --rm -e NVIDIA_DRIVER_CAPABILITIES=graphics,video,compute,utility nvidia/cuda:11.4.2-base-ubuntu20.04
```
or add:
```
ENV NVIDIA_DRIVER_CAPABILITIES graphics,video,compute,utility
```
to your docker build file.
See https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/user-guide.html#driver-capabilities for more information.
## WSL (Windows Subsystem for Linux)
Currently Clara Viz won't run under WSL because OptiX is not supported in that environment.
## Acknowledgments
Without awesome third-party open source software, this project wouldn't exist.
Please find `LICENSE-3rdparty.md` to see which third-party open source software
is used in this project.
## License
Apache-2.0 License (see `LICENSE` file).
Copyright (c) 2020-2021, NVIDIA CORPORATION.
# clara-viz 0.2.2 (October 17 2022)
## Bug Fixes
* Jupyter notebooks fail with AttributeError: 'Widget' object has no attribute 'on_displayed' (https://github.com/NVIDIA/clara-viz/issues/23)
## Security
* Update Jupyter widget Java code packages to fix vulnerabilities
## Documentation
* pip install fails on Windows machines (https://github.com/NVIDIA/clara-viz/issues/22)
* Windows is not supported, added a section on supported OS to readme
# clara-viz 0.2.1 (March 29 2022)
## Bug Fixes
* Widget can't be displayed because of version mismatch
# clara-viz 0.2.0 (March 29 2022)
## Features
* Add support for rendering multi resolution images used in digital pathology
## Security
* Update Jupyter widget Java code packages to fix vulnerabilities
## Bug Fixes
* Error when using a widget with a renderer using a numpy array (https://github.com/NVIDIA/clara-viz/issues/18)
## Documentation
* Fix typo for `image_type` parameter in the sample code of the readme file
* Extended documentation, added multi resolution image rendering
# clara-viz 0.1.4 (Feb 15 2022)
## Security
* Update Jupyter widget Java code packages to fix vulnerabilities
## Bug Fixes
* Regression - cinematic rendering example throws an error (https://github.com/NVIDIA/clara-viz/issues/16)
# clara-viz 0.1.3 (Jan 31 2022)
## New
* Support installation of recommended dependencies
## Bug Fixes
* Failed to load data files with ITK when using Clara Train docker image (https://github.com/NVIDIA/clara-viz/issues/12)
* Rendering is wrong when passing non-contiguous data in (e.g. transposed numpy array)
* Widget interaction in slice mode not working correctly (https://github.com/NVIDIA/clara-viz/issues/13)
# clara-viz 0.1.2 (Jan 19 2022)
## Bug Fixes
* When the renderer is immediately destroyed after creation there is a segmentation fault. This could happen when providing a unsupported data type (e.g. 64 bit floating point values), when creating a temporary object (e.g. in Python `print(Renderer(data)))`) or when the initialization of the Renderer failed. (https://github.com/NVIDIA/clara-viz/issues/7, https://github.com/NVIDIA/clara-viz/issues/8)
* Widget is not working with Jupyter Notebooks (but with Jupyter Lab) (https://github.com/NVIDIA/clara-viz/issues/9)
## Documentation
* Added missing `video` capability to docker run command
# clara-viz 0.1.1 (Dec 14 2021)
## Bug Fixes
* When installing the `clara-viz-core` Python package only there is the error `ModuleNotFoundError: No module named 'packaging'` when doing `import clara.viz.core`
* When getting the settings from the renderer the 'TransferFunctions' sections is returned as 'Transferfunctions' with lower case 'f'
## Documentation
* Added a section on using Clara Viz within a docker container.
* Added a link to the documentation.
* Added a section on WSL (Windows Subsystem for Linux).
## Notebooks
* The DataDefinition class is using ITK to load the data files, make sure ITK is available.
* Added a slice rendering example (Slice_rendering.ipynb)
* Fixed the check if the volume file exists in Render_image.ipynb, also fixed volume orientation and scaling.
* Updated the settings files to match the settings conventions used by the renderer.
## Misc
* Changed the camera names and removed the `Slice` prefix of the orthographic cameras. Renamed the perspective camera from `Cinematic` to `Perspective`
# clara-viz 0.1.0 (Dec 3 2021)
Initial release of Clara Viz