deepvisiontools 1.0.3

deepvisiontools is a library built on torch for training and inference processes for deep learning computer vision tasks.

Welcome to deepvisiontools!

deepvisiontools is a library built on torch for training and inference processes for deep learning computer vision tasks.

           

News

• release 1.0.0: detector / detector-seg / tabdet / tabdet-seg model wrappers are heavy but powerful models for detection and instance segmentation. However, they are not fully pretrained (only backbone on imagenet). Therefore, on small datasets (< 1000 images ish, but depend on the dataset ...) they can be slightly less competitive than yolo models (also included in the library) that were fully pretrained on coco. We are currently pretraining some of the models but it takes time. We are goind to update the weights once done, so keep tuned for new releases. We suggest you always train a yolo model as well for a baseline comparison. However, on larger datasets they can significantly outperform yolo11x, but again it depends on the dataset ...

patchs

• 1.0.3: fixed ddp desynchronization during validation, made ddp more robust, added ddp timeout control
• 1.0.2: added option to concat datasets for deepvisiondataset (DeepVisionDataset.concat)
• 1.0.1: fixed inconsistency for yolo wrappers due to modified behaviour in ultralytics between 8.3 and 8.4 versions. Fixed and compatible with both.

Scope

deepvisiontools is suitable for supervised learning computer vision tasks. Tasks currently available are:

• detection (bounding boxes)
• instance segmentation (object instance masks)
• semantic segmentation (semantic masks)

Future releases will include:

• classification
• regression
• keypoints/pose detection
• crowd detection (point detection)

deepvisiontools provides integrated pipelines that include dataset handlers, model wrappers, training and hyper-parameter fine-tuning helpers, metrics, inference and evaluation tools.

deepvisiontools is designed for both non-expert and expert users by providing default operational frameworks that are easy to use, while keeping maximal flexibility and control for experts.

Context

deepvisiontools is developed by INRAE, the French National Research Institute for Agriculture, Food and the Environment. It was partly supported by the PHENOME-EMPHASIS project. It is associated with INRAE CATI CONNECT.

Citations

To cite deepvisiontools when used, please cite the official repository: https://forge.inrae.fr/ue-apc/librairies/python/deepvisiontools

Important: deepvisiontools provides model wrappers and does not reimplement all models. It is the responsibility of the user to also cite the model developers.

If you are using one of these models, please cite the corresponding library as well:

• "yolo": cite Ultralytics (https://www.ultralytics.com/)
• "smp": cite segmentation-models-pytorch (https://github.com/qubvel-org/segmentation_models.pytorch)

Note that detector and tabdet models (VFNet, Cascade R-CNN/Mask R-CNN) are deepvisiontools reimplementations using PyTorch Image Models as backbones (https://timm.fast.ai/). They were reimplemented following MMDetection (https://github.com/open-mmlab/mmdetection) guidelines.

Finally, hyper-parameter optimisations were built on Optuna. If you use the OptunaWrapper helper, it is worth mentioning Optuna in your work (https://optuna.org/).

Installation

It is recommended to install deepvisiontools on a GPU-enabled machine/server. We suggest that you use a Python virtual environment (uv, conda, venv, etc.) with Python version between 3.10 and 3.14.

deepvisiontools is available on PyPI, so you can simply run in a Python environment:

pip install deepvisiontools

To install deepvisiontools in development mode, please clone the repository and run:

pip install -e deepvisiontools/ # local cloned repo

Finally, to install deepvisiontools with developer extras, move inside the cloned repo and run:

pip install -e ".[dev]"

This will include extras like documentation, pytest, nox, etc.

Documentation and tutorials

Official documentation for deepvisiontools can be found here: https://deepvisiontools-1233bd.pages-forge.inrae.fr/

To get started with deepvisiontools, after installation you can run:

deepvisiontools download-tutorials

You will also need to download the demo datasets:

deepvisiontools download-demo-datasets

The first tutorial, getting_started, takes about 1 hour and explains all the basics of deepvisiontools. From there you have all information to get started with simple tasks.

We then recommend moving to advanced_usage to get a broader view of what you can configure in deepvisiontools and all available helpers.

Finally, the hyper_parametrs_optimization tutorial will explain the usage of Optuna wrappers available in deepvisiontools to perform extensive parameter space searches.

Monitoring via MLflow

deepvisiontools includes MLflow for monitoring, checkpointing and artifacts during training.

If you use deepvisiontools as intended, at some point you will end up with an mlruns folder.

You can use the following command to start MLflow and then open the local page in your browser to display the MLflow UI:

mlflow server --backend-store-uri sqlite:////$(pwd)/mlruns/mlflow.db --default-artifact-root file:$(pwd)/mlruns --host 127.0.0.1 --port 5000

An alternative way for Jupyter notebooks is presented in the tutorial.

License

GNU Affero General Public License v3 or later (AGPLv3+) (AGPL-3.0).

Contributor specifics

If you wish to contribute as a developer to deepvisiontools, you need to be part of INRAE or PHENOME-EMPHASIS. You can contact [e-mail] to discuss your involvement.

Organization and CI

The deepvisiontools repository has two protected branches: main and prerelease. main is reserved for official releases, and only maintainers are allowed to merge or push. prerelease is used for pre-release validation: the full CI stages are run, but they are non-blocking, which allows checking potential problems or errors before merging into main.

The deepvisiontools repository has a CI pipeline that includes:

• linting / formatting checks with ruff
• security checks (high-risk issues are blocking only on protected release paths)
• package build
• tests (Python 3.10, 3.11, 3.12, 3.13, 3.14)
• documentation build

Unit and functional tests

For contributors, you can run the local series of unit/functional tests. First, install the additional test-related dependencies.

We strongly recommend that you run local tests before creating a merge request.

Run with coverage

coverage run -m pytest      # run tests under coverage
coverage report -m          # text coverage summary
coverage html               # HTML coverage report in htmlcov/index.html

Running subsets

pytest tests/unit -q         # only unit tests
pytest tests/functional -q   # only functional tests

Run with nox

nox -s tests-3.xx   # run CPU-only, slow-only tests on a specific Python version: 3.10, 3.11, 3.12, 3.13 or 3.14

For example:

nox -s tests-3.12

Check other CI stages locally

Use nox, which is installed if ".[dev]" was used during installation:

nox -s ruff        # formatting / linting
nox -s typecheck   # type checking with mypy
nox -s security    # security checks with bandit
nox -s tests-3.xx  # CPU-only, non-slow tests on a specific Python version
nox -s docs        # build the docs

note that the nox docs session produces a _nox_doc/ folder, so you can inspect the doc locally

Linting and formatting

We suggest that you use ruff during development to maintain code compatibility with the tests. You can use ruff to check linting and formatting:

ruff check src tests          # check linting on src and tests folders
ruff check --fix src tests    # apply safe lint fixes
ruff format --check src tests # check formatting
ruff format src tests         # apply safe formatting on src and tests folders

Even better is to use ruff in your IDE.

release on PyPi

Only maintainer can create release with propper tags

To release on pypi you must tag the version from the main branch according to this pattern "vX.Y.Z". The tag version must match the X.Y.Z package version of deepvisiontools.__version__. Once the tagged is done, you can push on main and the CI release stage will upload the dist to pypi.