Project Structure
In Supervisely, all data and annotations are stored inside individual projects which consist of datasets containing files and Project Meta - a collection of classes and tags.
When downloaded, each project is converted into a folder structure that includes a meta.json
file containing Project Meta, and dataset folders with individual annotation files (and optionally the original data files). This organization enables seamless data transfer between Supervisely and local storage using the Supervisely Format
import plugin when needed.
This structure remains the same for every type of project in Supervisely.
Project Structure System

Project Folder
On the top level we have Project folders, these are the elements visible on the main Supervisely dashboard. Inside them, they can contain only Datasets and Project Meta information, all other data has to be stored a level below in a Dataset. All datasets within a project have to contain content of the same category.
Project Meta
Project Meta contains essential information about the project, including Classes and Tags, which are defined project-wide and can be used for labeling in any dataset within the current project. It also includes the Project Type and Settings, which configure the labeling interface.
Datasets
Datasets are the second level folders inside the project, they host the individual data files and their annotations.
Items
Every data file in the project has to be stored inside a dataset. Each file as its own set of annotations.
Downloaded Project Structure
All projects downloaded from Supervisely maintain the same basic structure, with the contents varying based on which download option you chose.
Download Archive
When you select one of the download option, the system automatically creates an archive with the following name structure: project_name.tar
Downloaded Project
All projects downloaded from Supervisely have the following structure:

π Root folder for the project named project name
:
π
meta.json
fileπ Dataset folders, each named
dataset_name
, which contains:π
ann
folder, contains annotation files, each namedsource_media_file_name.json
for the corresponding fileπ
img
(video
orpointcloud
) folder, contains source mediaπ
img_info
folder, contains JSON files with representation ofImageInfo
downloaded from instanceπ
meta
optional folder, contains corresponding JSON files with metadata for images
Project Structure Eample
The following structure is an example of a project with 2 datasets, each containing 2 images with annotations, and also meta directory with metadata for each image.
π¦ project-name
β£ π dataset-name-001
β β£ π ann
β β β£ π pexels-photo-101063.png.json
β β β π pexels-photo-103127.png.json
β β£ π img
β β β£ ποΈ pexels-photo-101063.png
β β β ποΈ pexels-photo-103127.png
β β£ π meta
β β β£ π pexels-photo-101063.png.json
β β β π pexels-photo-103127.png.json
β β£ π img_info
β β β£ π pexels-photo-101063.png.json
β β β π pexels-photo-103127.png.json
β£ π dataset-name-002
β β£ π ann
β β β£ π pexels-photo-100583.png.json
β β β π pexels-photo-106118.png.json
β β£ π img
β β β£ ποΈ pexels-photo-100583.png
β β β ποΈ pexels-photo-106118.png
β β π meta
β β β£ π pexels-photo-100583.png.json
β β β π pexels-photo-106118.png.json
β β£ π img_info
β β β£ π pexels-photo-100583.png.json
β β β π pexels-photo-106118.png.json
β π meta.json
Extended Project Structure
A project directory may contain the following folders or files:
π
blob
optional folder, contains blob files that are used for optimized uploads of projects. These blob files are TAR archives with hundreds of thousands of small images.π
obj_class_to_machine_color.json
- optional file for image annotation projects. Mapping between machine colors and classes in machine mask. Could be generated by applications such as Export As Masksπ
key_id_map.json
- optional file, created when annotating inside the Supervisely interface. Establishes correspondence between unique identifiers (keys and IDs) of items, objects, and frames where objects are located. The project file system stores these identifiers and keys on disk, which is necessary for navigation and for using the high-level API and applications.A dataset directory may contain the following folders or files:
π
masks_human
optional folder for image annotation projects, contains .png files with RGB semantic segmentation masks where every pixel has the color of the corresponding class. Could be generated by applications such as Export As Masksπ
masks_machine
optional folder for image annotation projects, contains .png files with semantic segmentation masks (machine annotations). This files should have the same name as the original images (may have a different extension). Could be generated by applications such as Export As Masksπ
masks_instances
optional folder contains BW instance segmentation masks for every object on the image. Could be generated by applications such as Export As Masksπ
blob_1_offsets.pkl
optional pickle files, contain batches (lists) ofBlobImageInfo
objects, which represent file names and their offsets inside blob files. These files are used to add images to the project dataset based on their offsets.
Understanding Blob Files and Offsets for Optimized Project Handling
Supervisely provides a powerful optimization for projects containing a large number of small image files through its blob file system. Instead of handling thousands of individual files (which can lead to significant overhead in network transfers and filesystem operations), blob files consolidate many images into a single large binary file. This approach dramatically improves upload and download speeds, especially when dealing with datasets containing tens or hundreds of thousands of images.
Complementing the blob files are offset files with the suffix _offsets.pkl
, which store metadata about each image's location within the blob. These files contain BlobImageInfo
objects that define the byte range representing each image in the binary.
π project-name
β£ π blob
β β π¦ small_images.tar
β£ π dataset-name-001
β β£ π small_images_offsets.pkl
β β£ π ann
β β β£ π pexels-photo-101063.png.json
β β β£ π small-image-0000001.png.json
β β β£ ...
β β β π small-image-0999999.png.json
β β π img
β β ποΈ pexels-photo-101063.png
β π meta.json
Related:
To learn more about the offsets file format and how to prepare it, refer to this article: Optimized Import of Small Images
To export extended Supervisely format with the blob files and offsets, use the Export to Supervisely format: Blob application. βοΈ However, other applications export projects in the Supervisely format using the traditional method, downloading each image separately.
Importing the extended Supervisely format happens automatically in applications that previously imported projects in the Supervisely format without blobs. Such as Import Images in Supervisely Format application or Auto Import tool.
Last updated
Was this helpful?