Application to detect, track and calculate statistics of objects in video. With the option to view the statistics by using the UI or exporting to CSV.

This application is the result of a bachelor's project done by a group of computer scientists at the Norwegian University of Science and Technology (NTNU). The initial assignment was provided by the Norwegian Institute for Nature Research (NINA) who wanted a more efficient way of gather statistics of video material they had collected at various locations.

It is recommended to install the application in a virtual environment using for example virtualenv.

Running nina requires:

• Python 3.8 or higher
• venv or virtualenv (recommended)
• The URL for downloading the package

Find url to latest whl here for use in the commands below.

You can either install the package globally, as a user, or in a virtual environment.

We recommend using a virtual environment when developing and as a user when installing for production. This has the benefit of not to interfere with the global packages.

Note! Make sure that the python command is versions 3.8 or higher. This can be verifid by running python --version. If python reports back version 2.7, attempt to use python3 instead.

A virtual environment means that the application is confided inside a single directory which is loaded in the current shell and does not interfere with the system in any way.

Create the virtual environment:

$ virtualenv .venv  # recommended
# or
$ python -m venv .venv

Load the virtual environment:

$ . .venv/bin/activate

If you use an other shell than bash, like fish or zsh. Use either activate.fish or activate.zsh instead.

It's also recommended to update the environment before installing the package. After loading the virtual environment, run the following:

$ python -m pip install --upgrade pip setuptools wheel

To install the package inside a virtual environment, use the step for installing globally below.

When installing globally, every user on the system has access to use the application.

Note! This is not the case if the command is executed inside a virtual environment.

$ pip install 'nina[cpu] @ <url>'
# or if you have a `gpu`
$ pip install 'nina[gpu] @ <url>' --find-links https://download.pytorch.org/whl/torch_stable.html

$ pip install --user 'nina[cpu] @ <url>'
# or if you have a `gpu`
$ pip install --user 'nina[gpu] @ <url>' --find-links https://download.pytorch.org/whl/torch_stable.html

After the application is installed by one of the steps above, run the following to start:

$ nina

Then navigate to http://localhost:5000 to access the application interface.

A configuration file(config.ini) is saved to a local path if not found at first start-up. Path it is saved to depend on operation system as specified below:

• linux/unix:
  • If XDG_CONFIG_HOME environment variable is set, it is saved to a folder nina in this location.
  • Else, it is saved to ~/.config/nina/.
• windows: config is saved to LOCALAPPDATA.
• if it should not be able to determine where to save the config, it will be saved to the current working directory, where the solution are started from.

See also our Contribution Guidelines.

The project are using pre-commit. After install activate as below:

$ git clone <url> nina
$ cd nina
$ pre-commit install
$ pre-commit install --hook-type commit-msg  # Enable commitlint

Running development environment requires:

• Python (3.8, 3.9)
• pip >= 21.1
• virtualenv (recommended)
• git-lfs

This adds an extra dependency on make.

The provided Makefile sets up a virtual environment, installs all the dependencies, and overall automates the entire process of running the software. For manual steps see Manually.

This ensures all commands are ran inside a virtual environment, and your global Python paths will not get polluted. Also makes it easier to run commands from inside your editor.

To get an overview of the targets run:

$ make help

To install the requirements and setup virtual environment for development run:

$ make nina # Build the software so it can be easily ran.
$ make deps-cpu # Install development dependencies.
# or if you have `gpu`
$ make deps-gpu # Install development dependencies.

To run the software use:

make run

Testing is not included here, as when using tox, it handles its own virtual environments. Using pytest could require running inside a virtual environment.

# get source code
$ git clone <url> nina
$ cd nina
# make virtual environment
$ virtualenv .venv --download   # or `python -m venv .venv --upgrade-deps`
# activate environment
$ . .venv/bin/activate
# get dependencies
$ pip install -e .[testing, dev, cpu] # or `gpu`
# run application with Flask dev-server
$ python -m nina --dev
# or run a single module
$ python -m core

The project is using tox for testing. Various environments are provided so that tests can be executed separately or all at once.

# to build and run tests for all supported versions:
$ tox
# or for a specific Python version or target:
$ tox -e py39

Pass -l to tox to see all targets.

$ tox -l
py38
py39
coverage

or to run only tests

$ make deps
$ . .venv/bin/activate
$ pytest

To build the package for publishing, run the following command inside a virtual environment:

$ python -m build

The source code is licensed under GPLv3. License is available here.