See also

Please visit our docs for more information on Segments.ai and visit the setup page to learn how to install and setup the Segments.ai Python SDK.

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

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]]

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.

Export#

Export a dataset to a different format#

export_dataset(dataset, export_folder='.', export_format='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

segmentation-bitmap, segmentation-bitmap-highres, vector, bboxes and keypoints

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 (Literal[‘coco-panoptic’, ‘coco-instance’, ‘yolo’, ‘instance’, ‘instance-color’, ‘semantic’, ‘semantic-color’, ‘polygon’]) – 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

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

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.

Raises

ImportError – If matplotlib is not installed.

Return type

None