Installation

There are multiple ways to obtain the nrtk package. The simplest is to install via the pip command. Alternatively, you can install via conda-forge command. For local development, you can use Poetry.

nrtk installation has been tested on Unix and Linux systems.

Note

To install with OpenCV, see instructions below.

From pip

pip install nrtk

From conda-forge

conda install -c conda-forge nrtk

From Source

The following assumes Poetry (installation and usage) is already installed.

Note

nrtk currently requires poetry<2.0

Poetry is used for development of nrtk. Unlike the previous options, Poetry will not only allows developers to install any extras they need, but also install developmental dependencies like pytest and nrtk’s linting tools.

Please heed the following warning from Poetry’s own documentation:

Warning

Poetry should always be installed in a dedicated virtual environment to isolate it from the rest of your system. It should in no case be installed in the environment of the project that is to be managed by Poetry. This ensures that Poetry’s own dependencies will not be accidentally upgraded or uninstalled. In addition, the isolated virtual environment in which poetry is installed should not be activated for running poetry commands.

If unfamiliar with Poetry, please take a moment to familiarize yourself using the above links, to ensure the smoothest introduction possible.

Note

Poetry installation is only recommended for advanced nrtk users. For most users, pip or conda installation is sufficient.

Quick Start

cd /where/things/should/go/
git clone https://github.com/kitware/nrtk.git ./
poetry install

Installing Developer Dependencies

The following installs both core and development dependencies as specified in the pyproject.toml file, with versions specified (including for transitive dependencies) in the poetry.lock file:

poetry install --sync --with linting,tests,docs

Building the Documentation

The documentation for nrtk is maintained as a collection of reStructuredText documents in the docs/ folder of the project. The Sphinx documentation tool can process this documentation into a variety of formats, the most common of which is HTML.

Within the docs/ directory is a Unix Makefile (for Windows systems, a make.bat file with similar capabilities exists). This Makefile takes care of the work required to run Sphinx to convert the raw documentation to an attractive output format. For example, calling the command below will generate HTML format documentation rooted at docs/_build/html/index.html.

poetry run make html

Calling the command make help here will show the other documentation formats that may be available (although be aware that some of them require additional dependencies such as TeX or LaTeX).

Live Preview

While writing documentation in a markup format such as reStructuredText, it is very helpful to preview the formatted version of the text. While it is possible to simply run the make html command periodically, a more seamless workflow of this is available. Within the docs/ directory is a small Python script called sphinx_server.py that can simply be called with:

poetry run python sphinx_server.py

This will run a small process that watches the docs/ folder contents, as well as the source files in src/nrtk/, for changes. make html is re-run automatically when changes are detected. This will serve the resulting HTML files at http://localhost:5500. Having this URL open in a browser will provide you with an up-to-date preview of the rendered documentation.

Installing with OpenCV

One of the optional packages for nrtk is OpenCV. OpenCV is required for blur perturbers and Optical Transfer Functions. To give users the option to use either opencv-python or opencv-python-headless, nrtk has the graphics and headless extras for opencv-python and opencv-python-headless respectively. The following commands will install the opencv-python version.

For pip:

pip install nrtk[graphics]

For conda-forge:

conda install -c conda-forge nrtk-graphics

For Poetry:

poetry install --sync --extras graphics

To install the opencv-python-headless version, replace graphics with headless in the above commands.

Extras

NRTK has multiple optional extras to expand functionality. The list below contains the extra name and a brief description of the extra.

graphics: installs the graphics version of opencv-python. graphics or headless is required for blur perturbers, TurbulenceApertureOTFPerturber, JitterOTFPerturber, DetectorOTFPerturber, CircularApertureOTFPerturber, and NIIRSImageMetric.

headless: installs the headless version of opencv-python. graphics or headless is required for blur perturbers, TurbulenceApertureOTFPerturber, JitterOTFPerturber, DetectorOTFPerturber, CircularApertureOTFPerturber, and NIIRSImageMetric.

pybsm: installs pyBSM. Required for CustomPybsmPerturbImageFactory, PybsmSensor, PybsmScenario, PybsmPerturber, TurbulenceApertureOTFPerturber, JitterOTFPerturber, DetectorOTFPerturber, CircularApertureOTFPerturber, DefocusOTFPerturber, SimplePybsmGenerator, and NIIRSImageMetric.

maite: installs MAITE and its associated dependencies. Required for everything in Interoperability.

tools: installs KWCOCO and Pillow. Required for COCOJATICObjectDetectionDataset, nrtk-perturber, and dataset_to_coco().

scikit-image: installs scikit-image. Required for random_noise perturbers.

Pillow: installs Pillow. Required for enhance perturbers.

albumentations: installs albumentations. Required for albumentations_perturber perturbers.

waterdroplet: installs scipy and shapely. Required for water_droplet_perturber perturber and water_droplet_perturber_utils utility functions. Note: This needs to be installed in conjunction with either the graphics or headless extras due to the OpenCV requirement.

notebook-testing: installs various dependencies required for running any notebook in docs/examples.