<h1 align="center">
  <a href="https://supervise.ly"><img alt="Supervisely" title="Supervisely" src="https://i.imgur.com/B276eMS.png"></a>
</h1>

<h4 align="center">AI for everyone! Neural networks, tools and Python SDK we use with <a href="https://supervise.ly">
Supervisely</a>.</h4>

<p align="center">
  <a href="https://ecosystem.supervise.ly" target="_blank"> <img src="https://img.shields.io/badge/supervisely-ecosystem-brightgreen" alt="Ecosystem"> </a>
  <a href="https://supervise.ly/slack" target="_blank"> <img src="https://img.shields.io/badge/slack-chat-green.svg?logo=slack" alt="Slack"> </a>
  <a href='https://supervisely.readthedocs.io/en/rtd-docs-adaptation-test-templates/?badge=rtd-docs-adaptation-test-templates'><img src='https://readthedocs.org/projects/supervisely/badge/?version=rtd-docs-adaptation-test-templates' alt='Documentation Status' /></a>
  <a href="https://img.shields.io/docker/pulls/supervisely/base-py-sdk"> <img src="https://img.shields.io/docker/pulls/supervisely/base-py-sdk" alt="docker pulls"> </a>
  <a href="https://github.com/supervisely/supervisely" target="_blank"> <img src="https://img.shields.io/github/repo-size/supervisely/supervisely.svg" alt="Repository size"> </a>
  <a href="https://pypi.org/project/supervisely" target="_blank"> <img src="https://img.shields.io/pypi/v/supervisely?color=%2334D058&label=pypi%20package" alt="Package version"> </a>
  <a href="https://github.com/supervisely/supervisely/pulls" target="_blank"> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="Pull requests"> </a>
</p>


<p align="center">
  <a href="#introduction">Introduction</a> •
  <a href="#agent">Agent</a> •
  <a href="#neural-networks">Neural Networks</a> •
  <a href="#import-plugins">Import Plugins</a> •
  <a href="#python-sdk">Python SDK</a> •
  <a href="#data-transformation-language">Data Transformations</a> •
  <a href="#resources">Resources</a>
</p>

![screenshot](https://i.imgur.com/5dzQrrA.gif)

## Introduction

Supervisely is a web platform where you can find everything you need to build Deep Learning solutions within a single
environment.

We learn a lot from our awesome community and want to give something back. Here you can find the Python SDK we use to
implement neural network models, import plugins for custom data formats, and tools like the Data Transformation
Language. You can also find the source code for the agent to turn your PC into a worker node to deploy your neural nets.

## Agent

Supervisely Agent is a simple open-source task manager available as a Docker image.

The Agent runs on a worker node. It connects to the Supervisely WEB instance and listens for the tasks (like neural net
training request) to run. It handles downloading and uploading data to the web instance, sets up proper environments for
the specific tasks to run, and keeps track of progress, successes and failures of individual tasks. By deploying the
agent on worker machine you bring up a virtual computing claster that your team can run their tasks on from the
Supervisely web instance.

<p align="center">
<img src="https://gblobscdn.gitbook.com/assets%2F-M4BHwRbuyIoH-xoF3Gv%2F-M5JQKcQ0OcHshO-q9Kz%2F-M5JQLtrAGKs7RWLDVdA%2Fagent-diagramm.png" alt="Deploying agent to Supervisely" width="400" />
</p>

Check out [explanation](https://github.com/supervisely/agent) on how agent works
and [documentation](https://docs.supervise.ly/customization/agents) on how to deploy a new agent.

## Neural Networks

We have ported and implemented a number of popular neural network (NN)
architectures to be available as Supervisely plugins. Each plugin is a separate Docker image. We continue to work on
porting more NN architectures to Supervisely.

We also have a detailed guide on how
to [make your own neural net plugin](./help/tutorials/03_custom_neural_net_plugin/custom_nn_plugin.md), so you do not
have to depend on anyone else to be able to use your favorite architecture.

Here are the neural network architectures available out of the box today:

* [CNN-LSTM-CTC](./nn/cnn_lstm_ctc) (OCR)
* [DeepLab v3 Plus](./plugins/nn/deeplab_v3plus) (segmentation)
* [EAST](./plugins/nn/east) (text detection)
* [ICNet](./plugins/nn/icnet) (segmentation)
* [Mask RCNN](./plugins/nn/mask_rcnn_matterport) (detection and segmentation)
* [ResNet](./plugins/nn/resnet_classifier) (classification)
* [Models from TensorFlow Object Detection](./plugins/nn/tf_object_detection) (detection)
* [U-Net](./plugins/nn/unet_v2) (segmentation)
* [YOLO v3](./plugins/nn/yolo_v3) (detection)

Read [here](https://docs.new.supervise.ly/neural-networks/overview/overview/) how to run training or inference with this
models.

For all source implementations of NNs the original authors are retaining all their original rights.

## Import plugins

We provide import plugins for over 30 popular dataset formats out of the box. You can also leverage
our [Python SDK](#python-sdk) to implement a new plugin for your custom format.

## Python SDK

We have organized most of the common functionality for processing data in
[Supervisely format](https://docs.supervise.ly/ann_format/) and for training and inference with neural networks into
the [Python SDK](./supervisely_lib). Our stock plugins rely on the SDK extensively, and we believe the SDK will be also
valuable to the community.

The SDK not only wraps all the low-level details of handling the data and communicating with the Supervisely web
instance, but also provides convenience helpers for the common tasks that we found useful in our own work of developing
Supervisely plugins, such as neural network architectures and custom dataset imports.

Key features:

* Read, modify and write Supervisely projects on disk.
* Work with labeling data: geometric objects and tags.
* Common functionality for developing Supervisely plugins, so that you only need to focus on the core of your custom
  logic, and not on low level interactions with the platform.

#### Installation

```
pip install supervisely
```

or

```
git clone https://github.com/supervisely/supervisely.git && \
pip install -e ./supervisely
```

or

```
python -m pip install git+https://github.com/supervisely/supervisely.git
```

We release updates quite often, so use following command if you would like to upgrade you current supervisely package:

```
pip install supervisely --upgrade
```

By default `pip install supervisely` installs only “recommended” dependencies, that are required for general usage. If
you face some import errors then you should install extra dependencies (used only in limited scenarios). To install
extras dependencies use the following command:

```bash
pip install 'supervisely[extras]'
```

The only prerequisites are `Python` >= 3.8 and `pip`.

Tip: `opencv-python` may require `apt-get install libgtk2.0-dev` Or use pre-built Docker image which can be found on
Docker Hub:

```docker pull supervisely/base-py```

The corresponding `Dockerfile` can be found in `base_images` directory.

## Data Transformation Language

Data Transformation Language allows to automate complicated pipelines of data transformation. Different actions
determined by *DTL layers* may be applied to images and annotations. In details it is
described [here](https://docs.new.supervise.ly/export/).

## Resources

- [Supervise.ly](https://supervise.ly) - Website
- [Medium](https://medium.com/@deepsystems) - Our technical blog. Regular updates on how to use state of the art models
  and solve practical data science problems with Supervisely.
- [Tutorials and Cookbooks](./help) in this repository.
