Installation#
This page covers installation options beyond the basic PyPI/conda install shown in the Getting Started section, including installing from source. NRTK has been tested on Unix-based systems, including Linux, macOS, and WSL.
Attention
Not all perturbers are available with the base PyPI install — many require optional third-party libraries such as pyBSM, OpenCV, or Pillow. With PyPI, you can selectively install only the extras that your workflow requires (see the Perturber Requirements table below). The conda-forge package includes all optional dependencies by default.
Installing nrtk#
See also
See Perturber Requirements below for the full list of optional extras and which perturbers they enable.
nrtk can be installed via pip from PyPI.
Warning
The recommended way to install nrtk via pip is to use a virtual environment. To learn
more, see creating virtual environments in the Python Packaging User Guide.
$ pip install nrtk[extra1,extra2,...]
nrtk can be installed via conda from conda-forge.
Warning
The recommended way to install nrtk via conda is to use a virtual environment. To learn
more, see creating environments in the conda documentation.
$ conda install -c conda-forge nrtk
Install from source with Poetry when you are contributing to nrtk, need to build the documentation locally, or want to run the test suite.
Warning
Poetry installation is only recommended for advanced nrtk users. For most users, pip or conda installation is sufficient.
The following assumes Poetry is already installed. Otherwise, please refer to Poetry installation and usage before proceeding.
Note
nrtk requires Poetry 2.2 or higher.
About Poetry
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. Poetry not only allows 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.
Clone and 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.
Installing Extras
To install an extra group(s) to enable a perturbation, add the --extras flag to
your install command, e.g.:
$ poetry sync --with linting,tests,docs --extras "extra1 extra2 ..."
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).
See also
Developers looking to contribute to NRTK should check out our additional development resources.
Perturber Requirements#
The following table lists each perturber and the extras required to use them. Install any
combination of extras as needed for your use case (e.g., pip install nrtk[pybsm,headless]).
Note
Perturbers that require OpenCV list graphics or headless as their extra.
Use graphics for full GUI capabilities (opencv-python) or headless
for minimal, no-GUI environments (opencv-python-headless).
The conda package includes all optional dependencies by default.
Photometric Perturbers#
Modify visual appearance (color, brightness, blur, noise)
Perturber |
Required Inputs |
Extra(s) Required |
Key Dependencies Provided by Extra(s) |
|---|---|---|---|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
Geometric Perturbers#
Alter spatial positioning (rotation, scaling, cropping, translation)
Perturber |
Required Inputs |
Extra(s) Required |
Key Dependencies Provided by Extra(s) |
|---|---|---|---|
Image (RGB, Grayscale) |
— |
— |
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
— |
— |
Environment Perturbers#
Simulate atmospheric effects (haze, water droplets)
Perturber |
Required Inputs |
Extra(s) Required |
Key Dependencies Provided by Extra(s) |
|---|---|---|---|
Image (RGB, Grayscale) |
— |
— |
|
Image (RGB, Grayscale) |
|
|
Optical Perturbers#
Model physics-based sensor and optical phenomena
Perturber |
Required Inputs |
Extra(s) Required |
Key Dependencies Provided by Extra(s) |
|---|---|---|---|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
|
|
|
Image (RGB, Grayscale) |
— |
— |
|
Image (RGB, Grayscale) |
|
|
Generative Perturbers#
Model physics-based sensor and optical phenomena
Perturber |
Required Inputs |
Extra(s) Required |
Key Dependencies Provided by Extra(s) |
|---|---|---|---|
Image (converts to RGB) |
|
|
Utility Perturbers#
Enable composition and third-party library integration
Perturber |
Required Inputs |
Extra(s) Required |
Key Dependencies Provided by Extra(s) |
|---|---|---|---|
Image (format varies by transform) |
|
|
|
Image (format varies by perturbers) |
— |
— |