Utils#

Load#

Load an image from a url#

load_image_from_url(url, save_filename=None, s3_client=None)[source]#

Load an image from url.

Parameters

url (str) – The image url.
save_filename (Optional[str]) – The filename to save to.
s3_client (Optional[Any]) – A boto3 S3 client, e.g. s3_client = boto3.client("s3"). Needs to be provided if your images are in a private S3 bucket. Defaults to None.

Return type

Image

Returns

A PIL image.

Load a point cloud from a url#

load_pointcloud_from_url(url, save_filename=None, s3_client=None)[source]#

Load a pointcloud from url.

Parameters

url (str) – The pointcloud url.
save_filename (Optional[str]) – The filename to save to.
s3_client (Optional[Any]) – A boto3 S3 client, e.g. s3_client = boto3.client("s3"). Needs to be provided if your point clouds are in a private S3 bucket. Defaults to None.

Return type

o3d.geometry.PointCloud

Returns

A pointcloud.

Raises

ImportError – If open3d is not installed (to install run pip install open3d).

Load a label bitmap from a url#

load_label_bitmap_from_url(url, save_filename=None)[source]#

Load a label bitmap from url.

Parameters

url (str) – The label bitmap url.
save_filename (Optional[str]) – The filename to save to.

Return type

ndarray[Any, dtype[uint32]]

Returns

A numpy.ndarray with numpy.uint32 dtype where each unique value represents an instance id.

Load a release#

load_release(release)[source]#

Load JSON from Segments release.

Parameters: release (Release) – A Segments release.
Return type: Any
Returns: A JSON with the release labels.

Transform#

Turn a bitmap into a file#

bitmap2file(bitmap, is_segmentation_bitmap=True)[source]#

Convert a label bitmap to a file with the proper format.

Parameters

bitmap (ndarray[Any, dtype[uint32]]) – A numpy.ndarray with numpy.uint32 dtype where each unique value represents an instance id.
is_segmentation_bitmap (bool) – If this is a segmentation bitmap. Defaults to True.

Return type

BytesIO

Returns

A file object.

Raises

ValueError – If the dtype is not np.uint32 or np.uint8.
ValueError – If the bitmap is not a segmentation bitmap.

Turn an instance bitmap and annotations dict into a semantic bitmap#

get_semantic_bitmap(instance_bitmap=None, annotations=None, id_increment=0)[source]#

Convert an instance bitmap and annotations dict into a segmentation bitmap.

Parameters

instance_bitmap (Optional[ndarray[Any, dtype[uint32]]]) – A numpy.ndarray with numpy.uint32 dtype where each unique value represents an instance id. Defaults to None.
annotations (Optional[Dict[str, Any]]) – An annotations dictionary. Defaults to None.
id_increment (int) – Increment the category ids with this number. Defaults to 0.

Return type

Optional[ndarray[Any, dtype[uint32]]]

Returns

An array here each unique value represents a category id.

Fix an image rotation#

handle_exif_rotation(image)[source]#

Handle the exif rotation of a PIL image.

Parameters: image (Image) – A PIL image.
Return type: Image
Returns: A rotated PIL image.

Turn a cuboid label into a segmentation label#

cuboid_to_segmentation(pointcloud, label_attributes, ego_pose=None)[source]#

Convert a cuboid label to an instance segmentation label.

Parameters

pointcloud (ndarray[Any, dtype[float32]]) – A pointcloud of size Nx3.
label_attributes (PointcloudCuboidLabelAttributes) – A cuboid label from a single frame interface or one frame from a sequence interface.

Return type

ndarray[Any, dtype[uint32]]

Returns

An instance segmentation label of size Nx1 mapping each point cloud point to a cuboid instance.

Raises

ImportError – If pyquaternion is not installed (to install run pip install pyquaternion).
ImportError – If open3d is not installed (to install run pip install open3d).

Export#

Export a dataset to a different format#

export_dataset(dataset, export_folder='.', export_format=ExportFormat.COCO_PANOPTIC, id_increment=0, **kwargs)[source]#

Export a dataset to a different format.

Export format	Supported dataset type
COCO panoptic	`segmentation-bitmap` and `segmentation-bitmap-highres`
COCO instance	`segmentation-bitmap` and `segmentation-bitmap-highres`
YOLO	`vector`, `bboxes` and `image-vector-sequence`
Instance	`segmentation-bitmap` and `segmentation-bitmap-highres`
Colored instance	`segmentation-bitmap` and `segmentation-bitmap-highres`
Semantic	`segmentation-bitmap` and `segmentation-bitmap-highres`
Colored semantic	`segmentation-bitmap` and `segmentation-bitmap-highres`
Polygon	`segmentation-bitmap` and `segmentation-bitmap-highres`

Example:

# pip install segments-ai
from segments import SegmentsClient, SegmentsDataset
from segments.utils import export_dataset

# Initialize a SegmentsDataset from the release file
client = SegmentsClient('YOUR_API_KEY')
release = client.get_release('jane/flowers', 'v1.0') # Alternatively: release = 'flowers-v1.0.json'
dataset = SegmentsDataset(release, labelset='ground-truth', filter_by=['labeled', 'reviewed'])

# Export to COCO panoptic format
export_dataset(dataset, export_format='coco-panoptic')

Alternatively, you can use the initialized SegmentsDataset to loop through the samples and labels, and visualize or process them in any way you please:

import matplotlib.pyplot as plt
from segments.utils import get_semantic_bitmap

for sample in dataset:
    # Print the sample name and list of labeled objects
    print(sample['name'])
    print(sample['annotations'])

    # Show the image
    plt.imshow(sample['image'])
    plt.show()

    # Show the instance segmentation label
    plt.imshow(sample['segmentation_bitmap'])
    plt.show()

    # Show the semantic segmentation label
    semantic_bitmap = get_semantic_bitmap(sample['segmentation_bitmap'], sample['annotations'])
    plt.imshow(semantic_bitmap)
    plt.show()

Parameters

dataset (SegmentsDataset) – A SegmentsDataset.
export_folder (str) – The folder to export the dataset to. Defaults to ..
export_format (ExportFormat) – The destination format. Defaults to coco-panoptic.
id_increment (int) – Increment the category ids with this number. Defaults to 0. Ignored unless export_format is semantic or semantic-color.

Return type

Optional[Union[Tuple[str, Optional[str]], Optional[str]]]

Returns

Returns the file name and the image directory name (for COCO panoptic, COCO instance, YOLO and polygon), or returns the export folder name (for (colored) instance and (colored) panoptic).

Raises

ImportError – If scikit image is not installed (to install run pip install scikit-image).
ValueError – If an unvalid export_format is used.

Show#

Show the exported contours of a segmented image#

show_polygons(image_directory_path, image_id, exported_polygons_path, seed=0, output_path=None)[source]#

Show the exported contours of a segmented image (i.e., resulting from export_dataset() with polygon export format).

Parameters

image_directory_path (str) – The image directory path.
image_id (int) – The image id (this can be found in the exported polygons JSON file).
exported_polygons_path (str) – The exported polygons path.
seed (int) – The seed used to generate random colors. Defaults to 0.
output_path (Optional[str]) – The directory to save the plot to. Defaults to None.

Return type

None

Returns

None

Raises

ImportError – If matplotlib is not installed.