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 currently requires poetry<2.0
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.
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
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.graphicsorheadlessis required forblurperturbers, AlbumentationsPerturber, RandomRotationPerturber, and RandomScalePerturber.headless: installs the headless version of
opencv-python.graphicsorheadlessis required forblurperturbers, AlbumentationsPerturber, RandomRotationPerturber, and RandomScalePerturber.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_noiseperturbers.Pillow: installs Pillow. Required for
enhanceperturbers.albumentations: installs albumentations. Required for
albumentations_perturber,random_rotation_perturber, andrandom_scale_perturber.waterdroplet: installs scipy, shapely, and geopandas <https://geopandas.org/en/stable/>__. Required for :mod:`~nrtk.impls.perturb_image.generic.water_droplet_perturber perturber and utility functions.
diffusion: installs torch, diffusers, accelerate, and Pillow. Required for DiffusionPerturber.
notebook-testing: installs various dependencies required for running any notebook in
docs/examples.
Installing with OpenCV
One of the optional packages for nrtk is OpenCV, which is required for
blur perturbers and
Optical Transfer Functions.
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 install --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 |
Extra(s) Required |
Key Dependencies Provided by Extra(s) |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
— |
— |
|
|
|
|
|
|
|
|
|
|
DiffusionPerturber |
|
|
|
|
|
|
|
|
— |
— |
|
|
|
|
|
|
|
— |
— |
|
|
|
|
|
|
|
— |
— |
|
— |
— |
|
|
|
|
|
|
|
— |
— |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|