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.

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 requires Poetry 2.2 or higher.

Poetry acts as a comprehensive tool for dependency management, virtual environment handling, and package building. It streamlines development by automating tasks like dependency resolution, ensuring consistent environments across different machines, and simplifying the packaging and publishing of Python projects. Unlike the previous options, Poetry will not only allow developers to install any extras they need, but also install multi-dependency groups like nrtk’s docs, tests, and linting tools.

Be sure to note 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, 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.

Clone & Install#

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 sync --with linting,tests,docs

Note

Developers should also ensure their enviroment has Git LFS installed before their first commit. See the Git LFS documentation for more details.

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.

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, AlbumentationsPerturber, RandomRotationPerturber, and RandomScalePerturber.

headless: installs the headless version of opencv-python. graphics or headless is required for blur perturbers, AlbumentationsPerturber, RandomRotationPerturber, and RandomScalePerturber.

pybsm: installs pyBSM. Required for PybsmPerturber, TurbulenceAperturePerturber, JitterPerturber, DetectorPerturber, CircularAperturePerturber, and DefocusPerturber.

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

tools: installs KWCOCO and Pillow. Required for nrtk-perturber.

skimage: installs scikit-image. Required for noise perturbers.

pillow: installs Pillow. Required for enhance perturbers.

albumentations: installs nrtk-albumentations. Required for AlbumentationsPerturber, RandomRotationPerturber, and RandomScalePerturber.

waterdroplet: installs scipy and numba. Required for WaterDropletPerturber perturber and utility functions.

diffusion: installs torch, diffusers, accelerate, and Pillow. Required for DiffusionPerturber.

Installing with OpenCV#

One of the optional packages for nrtk is OpenCV, which is required for blur perturbers and Optical Transfer Function perturbations.

OpenCV receives dedicated installation guidance due to its unique dual-installation options. Unlike other optional dependencies that have single-path installations, OpenCV requires users to choose between opencv-python (full GUI capabilities) and opencv-python-headless (minimal, no GUI) versions depending on their deployment environment and requirements.

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.

opencv-python-headless is a minimal package version of opencv-python that contains the core capabilities of OpenCV, without including any of the GUI-related functionalities.

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 sync --extras graphics

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

Perturber Dependencies#

The following table lists the perturbers and the extra/dependencies required to use them.

Perturber Dependencies#
Perturber	Extra(s) Required	Key Dependencies Provided by Extra(s)
Photometric Perturbers
`AverageBlurPerturber`	`graphics` or `headless`	`OpenCV`
`BrightnessPerturber`	`pillow`	`Pillow`
`ColorPerturber`	`pillow`	`Pillow`
`ContrastPerturber`	`pillow`	`Pillow`
`GaussianBlurPerturber`	`graphics` or `headless`	`OpenCV`
`GaussianNoisePerturber`	`skimage`	`scikit-image`
`MedianBlurPerturber`	`graphics` or `headless`	`OpenCV`
`PepperNoisePerturber`	`skimage`	`scikit-image`
`SaltAndPepperNoisePerturber`	`skimage`	`scikit-image`
`SaltNoisePerturber`	`skimage`	`scikit-image`
`SharpnessPerturber`	`pillow`	`Pillow`
`SpeckleNoisePerturber`	`skimage`	`scikit-image`
Geometric Perturbers
`RandomCropPerturber`	—	—
`RandomRotationPerturber`	`albumentations`, and (`graphics` or `headless`)	`nrtk-albumentations`, `OpenCV`
`RandomScalePerturber`	`albumentations`, and (`graphics` or `headless`)	`nrtk-albumentations`, `OpenCV`
`RandomTranslationPerturber`	—	—
Environment Perturbers
`HazePerturber`	—	—
`WaterDropletPerturber`	`waterdroplet`	`scipy`, `numba`
Optical Perturbers
`CircularAperturePerturber`	`pybsm`	`pyBSM`
`DefocusPerturber`	`pybsm`	`pyBSM`
`DetectorPerturber`	`pybsm`	`pyBSM`
`JitterPerturber`	`pybsm`	`pyBSM`
`PybsmPerturber`	`pybsm`	`pyBSM`
`RadialDistortionPerturber`	—	—
`TurbulenceAperturePerturber`	`pybsm`	`pyBSM`
Generative Perturbers
`DiffusionPerturber`	`diffusion`	`torch`, `diffusers`, `accelerate`, `Pillow`
Utility Perturbers
`AlbumentationsPerturber`	`albumentations`, and (`graphics` or `headless`)	`nrtk-albumentations`, `OpenCV`
`ComposePerturber`	—	—