Multiview images
Introduction
This easy-to-follow tutorial will show you how to upload multiview images and label groups to Supervisely using Python SDK and get the advantage of the multiview 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 multiview in the project settings, upload multiview images and explore the multiview 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
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 https://github.com/supervisely-ecosystem/import-multiview-images-tutorial.git
cd import-multiview-images-tutorial
sh create_venv.sh
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/main.py
.
Import libraries
import os
from dotenv import load_dotenv
import supervisely as sly
Load environment variables
if sly.is_development():
load_dotenv("local.env")
load_dotenv(os.path.expanduser("~/supervisely.env"))
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(project.id, "ds0")
Enable multiview in the project settings
api.project.set_multiview_settings(project.id)
You can also enable multiview in the Image Labeling Tool interface:
And now we're ready to upload images.
How to upload multiview images
In this tutorial, we'll be using the api.image.upload_multiview_images
method to upload multiview images to Supervisely.
def upload_multiview_images(
dataset_id: int,
group_name: str,
paths: Optional[List[str]] = None,
metas: Optional[List[Dict]] = None,
progress_cb: Optional[Union[tqdm, Callable]] = None,
links: Optional[List[str]] = None,
conflict_resolution: Optional[Literal["rename", "skip", "replace"]] = "rename",
force_metadata_for_links: Optional[bool] = False,
) -> List[ImageInfo]:
dataset_id
int
ID of the dataset to upload
group_name
str
Name of the group (tag value)
paths
Optional[List[str]]
List of paths to the images (optional)
metas
Optional[List[Dict]]
List of image metas (optional)
progress_cb
Optional[Union[tqdm, Callable]]
Function for tracking upload progress (optional)
links
Optional[List[str]]
List of links to the images (optional)
conflict_resolution
Literal["rename", "skip", "replace"]
Conflict resolution strategy (optional)
force_metadata_for_links
Optional[bool]
Force metadata for links (optional)
So, the method uploads images to Supervisely and returns a list of ImageInfo
objects.
Upload multiview images
for group_dir in os.scandir("src/images"):
if not group_dir.is_dir():
continue
images_paths = sly.fs.list_files(group_dir.path, valid_extensions=sly.image.SUPPORTED_IMG_EXTS)
api.image.upload_multiview_images(dataset.id, group_dir.name, images_paths)
Group existing images for multiview
If you already have images uploaded to Supervisely and you want to group them for multiview, you can use the api.image.group_images_for_multiview
method.
images = [2389126, 2389127, 2389128, 2389129, 2389130, ...]
for idx, batch_ids in enumerate(sly.batched(images, batch_size=6)):
api.image.group_images_for_multiview(batch_ids, f"group_{idx}")
Default tag name is
multiview
. You can change it by passing themultiview_tag_name
argument.If the tag does not exist, it will be created automatically.
Automatically enables multiview mode in the project settings.
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.
Multiview 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.
How to upload label groups
There are many cases when you need to group labels together. For example, if you have some labels captured from different perspectives that represent one object on different images and you want to analyze the object as a whole and not as separate instances, you can join them into a single group.
Label group - is a simple group of objects, that displays the relationship between objects and helps you to quickly locate the object on different images and to avoid labeling the same object multiple times.
Using the api.annotation.append_labels_group
method, you can upload labels as a group to images.
def append_labels_group(
self,
dataset_id: int,
image_ids: List[int],
labels: List[Label],
project_meta: Optional[ProjectMeta] = None,
group_name: Optional[str] = None,
) -> None:
dataset_id
int
Destination Dataset ID
image_ids
List[int]
Multiview images IDs
labels
List[Label]
group of labels (should be the same length as images_ids)
project_meta
Optional[ProjectMeta]
Project Meta (optional). Provide to avoid extra API calls
group_name
Optional[str]
Group name (optional). Labels will be assigned by tag with this value.
Let's group it all together and upload local images and labels to Supervisely using this method.
Our sample data directory structure:
π data
β£ π images
β β£ ποΈ car_01.jpeg
β β£ ποΈ car_02.jpeg
β β ποΈ car_03.jpeg
β π masks
β£ ποΈ car_01.png
β£ ποΈ car_02.png
β ποΈ car_03.png
β¬οΈ You can download this sample here: data.zip
Follow the code below to upload images and labels to Supervisely.
project_id = 56
dataset_id = 196
# GET PROJECT META
meta = sly.ProjectMeta.from_json(api.project.get_meta(project_id, with_settings=True))
# GET OBJ CLASS FROM META BY NAME
obj_cls = meta.get_obj_class("car")
# OR CREATE NEW OBJ CLASS IF NOT EXISTS
# obj_cls = sly.ObjClass(name="car", geometry_type=sly.Rectangle, color=[255, 0, 0])
# UPDATE PROJECT META IF CREATING NEW OBJ CLASS
# meta = meta.add_obj_classes([obj_cls])
# api.project.update_meta(project_id, meta.to_json())
# SET MULTIVIEW SETTINGS
api.project.set_multiview_settings(project_id)
# GET IMAGES AND MASKS PATHS
image_dir = os.path.join("data", "images")
mask_dir = os.path.join("data", "masks")
# SORT PATHS FOR CORRECT LABELS ORDER
image_paths = sorted([os.path.join(image_dir, path) for path in os.listdir(image_dir)])
mask_paths = sorted([os.path.join(mask_dir, path) for path in os.listdir(mask_dir)])
# CREATE LABELS
labels = []
for image_path, mask_path in zip(image_paths, mask_paths):
# READ MASK
bitmap = sly.Bitmap.from_path(mask_path)
# CREATE LABEL
label = sly.Label(geometry=bitmap, obj_class=obj_cls)
labels.append(label)
# UPLOAD IMAGES
image_infos = api.image.upload_multiview_images(dataset_id, "white_car", image_paths)
images_ids = [image_info.id for image_info in image_infos]
# APPEND LABELS TO IMAGES
api.annotation.append_labels_group(
dataset_id=dataset_id,
image_ids=images_ids,
labels=labels,
project_meta=meta,
)
Summary
In this tutorial, you learned how to upload multiview images and label groups to Supervisely using Python SDK and get the advantage of the multiview 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:
Create a new project and dataset.
Set multiview settings for the project using the
api.project.set_multiview_settings
method.Upload images using the
api.image.upload_multiview_images
method.Group existing images for multiview using the
api.image.group_images_for_multiview
method.Upload label groups using the
api.annotation.append_labels_group
method.
And that's it! Now you can upload your multview images to Supervisely using Python SDK.
Last updated
Was this helpful?