Multi-view images


This easy-to-follow tutorial will show you how to upload multi-view images to Supervisely using Python SDK and get the advantage of the multi-view image annotaion in the Supervisely Labeling Toolbox, which allows you to label images quickly and efficiently on one screen. You will learn how to enable multi-view in the project settings, upload multi-view images and explore the multi-view in the labeling interface.

In this tutorial, we will show you how to do it programmatically using Python, but you can also do it manually in the Web UI using Import Images Groups app from Supervisely Ecosystem or using our Import Wizard in the Web UI. Here is an illustrated example of how to do it:

How to debug this tutorial

Everything you need to reproduce this tutorial is on GitHub: source code and additional app files.

Step 1. Prepare ~/supervisely.env file with credentials. Learn more here.

Step 2. Clone the repository with source code and demo data and create a Virtual Environment.

git clone

cd import-multiview-images-tutorial


Step 3. Open the repository directory in Visual Studio Code.

code -r .

Step 4. Change the Workspace ID in the local.env file by copying the ID from the context menu.

WORKSPACE_ID=942 # ⬅️ change value

Step 5. Start debugging src/

Supervisely instance version >= 6.9.14 Supervisely SDK version >= 6.72.214

In the tutorial, Supervisely Python SDK version is not directly defined in the requirements.txt. But when developing your app, we recommend defining the SDK version in the requirements.txt.

Import libraries

import os

from dotenv import load_dotenv

import supervisely as sly

Load environment variables

if sly.is_development():

workspace_id = sly.env.workspace_id()

Init API client

api = sly.Api.from_env()

Explore the directory with images

here is the structure of the directory with images (src/images):

 📂 images
 ┣ 📂 audi
 ┃ ┣ 🏞️ audi_01.jpg
 ┃ ┣ 🏞️ audi_02.jpg
 ┃ ┗ 🏞️ audi_03.jpg
 ┣ 📂 mercedes
 ┃ ┣ 🏞️ mercedes_01.jpg
 ┃ ┣ 🏞️ mercedes_02.jpg
 ┃ ┣ 🏞️ mercedes_03.jpg
 ┃ ┣ 🏞️ mercedes_04.jpg
 ┃ ┣ 🏞️ mercedes_05.jpg
 ┃ ┗ 🏞️ mercedes_06.jpg
 ┣ 📂 renault
 ┃ ┣ 🏞️ renault_01.jpg
 ┃ ┣ 🏞️ renault_02.jpg
 ┃ ┣ 🏞️ renault_03.jpg
 ┃ ┗ 🏞️ renault_04.jpg
 ┗ 📂 ford
   ┣ 🏞️ ford_01.jpg
   ┣ 🏞️ ford_02.jpg
   ┣ 🏞️ ford_03.jpg
   ┣ 🏞️ ford_04.jpg
   ┗ 🏞️ ford_05.jpg

Create a new project and dataset

project = api.project.create(workspace_id, "Grouped cars", change_name_if_conflict=True)
dataset = api.dataset.create(, "ds0")

Enable multi-view in the project settings


You can also enable multi-view in the Image Labeling Tool interface:

And now we're ready to upload images.

How to upload multi-view images

In this tutorial, we'll be using the api.image.upload_multiview_images method to upload multi-view images to Supervisely.

def upload_multiview_images(
    dataset_id: int,
    group_name: str,
    paths: List[str],
    metas: Optional[List[Dict]] = None,
    progress_cb: Optional[Union[tqdm, Callable]] = None,
) -> List[ImageInfo]:



ID of the dataset to upload



Name of the group (tag value)


List[str] (paths to the images)

List of paths to the images


List[Dict] (metas of the images)

List of image metas (optional)


Optional[Union[tqdm, Callable]]

Function for tracking upload progress.

So, the method uploads images to Supervisely and returns a list of ImageInfo objects.

Upload multi-view images

for group_dir in os.scandir("src/images"):
    if not group_dir.is_dir():
    images_paths = sly.fs.list_files(group_dir.path, valid_extensions=sly.image.SUPPORTED_IMG_EXTS)

    api.image.upload_multiview_images(,, images_paths)

Grouped view in the labeling interface

So now, that we've uploaded all the images, let's take a look at the labeling interface.

As you can see, the images in the Labeling tool are grouped in the same way as in your images in folders (images from one folder are combined into one group). When importing, each image from the folders will be assigned tags with the same values, which allows them to be grouped into one group.

Multi-view labeling can be very useful when annotating objects of multiple classes simultaneously on several images. You don't need to shift your attention to find the necessary class every time you switch between images, allowing you to increase efficiency and save time and effort.


In this tutorial, you learned how to upload multi-view images to Supervisely using Python SDK and get the advantage of the multi-view image annotation in the labeling interface, which allows you to label images quickly and efficiently on one screen. Let's recap the steps we did:

  1. Create a new project and dataset.

  2. Set multi-view settings for the project using the api.project.set_multiview_settings method.

  3. Upload images using the api.image.upload_multiview_images method.

And that's it! Now you can upload your multi-view images to Supervisely using Python SDK.

Last updated