Skip to content



Supervisely project is a way of organizing annotated images.

A project is a named set of datasets. A dataset is a named set of annotated images. Each image has corresponding annotation, and vice versa.

Dataset name is unique within a project, and image name is unique within a dataset.


Please note that in terms of projects "annotation" means full set of objects (figures) linked with some image.

Project in filesystem

When stored on disk, project has the following structure:

├── meta.json
├── dataset_name_01
│   ├── ann
│   │   ├── my_favorite_image.json
│   │   ├── img_y.json
│   │   └── img_z.json
│   └── img
│       ├── my_favorite_image.jpg
│       ├── img_y.png
│       └── img_z.jpeg
└── dataset_name_02
    ├── ann
    │   ├── img_x.json
    │   ├── img_y.json
    │   └── img_z.json
    └── img
        ├── img_x.jpg
        ├── img_y.jpg
        └── img_z.jpg

In details:

  • The project is called "my_project".

  • Project directory ("my_project" in the example) contains some dataset directories and file meta.json.

  • meta.json contains metainfo about project: figure classes and image tags.

  • Each dataset directory contains two directories, ann with JSON annotations and img with images.

  • Each image shares name (e.g., img_x) with corresponding anotation.

  • PNGs and JPGs images are supported.

How to use

Look at simple examples:

Create project structure with ProjectStructure or read it from disk with ProjectFS.

Work with project meta using ProjectMeta.

Work with single annotation using Annotation.