Resource API

Usage

There are 2 main approaches to using the SDK. One is using the SegmentsClient for each API call directly. However, you can also call methods attached to the Segments.ai resources directly. We recommend using the latter in most cases, as this allows the SDK to perform better validation checks to the inputs you provide to the API. This will both speed up performance, reduce the risk of errors, and give more descriptive error messages in case there is a mistake anywhere.

When using the resource-driven approach, you will always start out fetching or creating a resource using a SegmentsClient:

import segments

client = segment.SegmentsClient(api_key_here)
dataset = client.get_dataset(your_dataset_identifier)

# Get all samples in a dataset
samples = dataset.get_samples()
# Add samples to the dataset
sample = dataset.add_sample(attributes=your_sample_attributes, name="Sample 1")
# Add a prelabel to that sample
label = sample.add_label(attributes=your_prelabel_attributes)

# Update the sample
sample.update(name="New name")
# Delete the sample
sample.delete()

API

Dataset

class Dataset(**data)[source]

See Dataset an overview of the properties this model has.

add_sample(name, attributes, metadata=None, priority=0, assigned_labeler=None, assigned_reviewer=None, readme='', enable_compression=True)[source]

Adds a sample to the dataset, see segments.client.SegmentsClient.add_sample() for more details.

Parameters:

  • name (str) – The name of the sample.

  • attributes (Union[Dict[str, Any], ImageSampleAttributes, ImageSequenceSampleAttributes, PointcloudSampleAttributes, PointcloudSequenceSampleAttributes, MultiSensorSampleAttributes]) – The sample attributes. Please refer to the online documentation.

  • metadata (Optional[Dict[str, Any]]) – Any sample metadata. Example: {'weather': 'sunny', 'camera_id': 3}.

  • priority (float) – Priority in the labeling queue. Samples with higher values will be labeled first. Defaults to 0.

  • assigned_labeler (Optional[str]) – The username of the user who should label this sample. Leave empty to not assign a specific labeler. Defaults to None.

  • assigned_reviewer (Optional[str]) – The username of the user who should review this sample. Leave empty to not assign a specific reviewer. Defaults to None.

  • readme (str) – The sample readme. Defaults to None.

  • enable_compression (bool) – Whether to enable gzip compression for the request. Defaults to True.

Raises:
Return type:

Sample

delete()[source]

Deletes this dataset. See segments.client.SegmentsClient.delete_dataset() for more details.

Raises:
Return type:

None

update(description=None, task_type=None, task_attributes=None, category=None, public=None, readme=None, metadata=None, labeling_inactivity_timeout_seconds=None, enable_skip_labeling=None, enable_skip_reviewing=None, enable_ratings=None, enable_interpolation=None, enable_same_dimensions_track_constraint=None, enable_save_button=None, enable_label_status_verified=None, enable_3d_cuboid_rotation=None, enable_confirm_on_commit=None)[source]

Updates the dataset, see segments.client.SegmentsClient.update_dataset() for more details.

Parameters:

  • description (Optional[str]) – The dataset description. Defaults to None.

  • task_type (Optional[TaskType]) – The dataset’s task type. Defaults to None.

  • task_attributes (Union[Dict[str, Any], TaskAttributes, None]) – The dataset’s task attributes. Please refer to the online documentation. Defaults to None.

  • category (Optional[Category]) – The dataset category. Defaults to None.

  • public (Optional[bool]) – The dataset visibility. Defaults to None.

  • readme (Optional[str]) – The dataset readme. Defaults to None.

  • metadata (Optional[Dict[str, Any]]) – Any dataset metadata. Example: {'day': 'sunday', 'robot_id': 3}.

  • labeling_inactivity_timeout_seconds (Optional[int]) – The number of seconds after which a user is considered inactive during labeling. Only impacts label timing metrics. Defaults to None.

  • enable_skip_labeling (Optional[bool]) – Enable the skip button in the labeling workflow. Defaults to None.

  • enable_skip_reviewing (Optional[bool]) – Enable the skip button in the reviewing workflow. Defaults to None.

  • enable_ratings (Optional[bool]) – Enable star-ratings for labeled images. Defaults to None.

  • enable_interpolation (Optional[bool]) – Enable label interpolation in sequence datasets. Ignored for non-sequence datasets. Defaults to None.

  • enable_same_dimensions_track_constraint (Optional[bool]) – Enable constraint to keep same cuboid dimensions for the entire object track in point cloud cuboid datasets. Ignored for non-cuboid datasets. Defaults to None.

  • enable_save_button (Optional[bool]) – Enable a save button in the labeling and reviewing workflow, to save unfinished work. Defaults to False.

  • enable_label_status_verified (Optional[bool]) – Enable an additional label status “Verified”. Defaults to False.

  • enable_3d_cuboid_rotation (Optional[bool]) – Enable 3D cuboid rotation (i.e., yaw, pitch and roll). Defaults to False.

  • enable_confirm_on_commit (Optional[bool]) – Enable a confirmation dialog when saving a sample in this dataset. Defaults to None.

Raises:
Return type:

Dataset

get_samples(labelset=None, name=None, label_status=None, metadata=None, sort='name', direction='asc', per_page=1000, page=1, include_full_label=False)[source]

Gets all samples within a dataset, see segments.client.SegmentsClient.get_samples() for more details.

Parameters:

  • labelset (Optional[str]) – If defined, this additionally returns for each sample a label summary or full label (depending on include_full_label) for the given labelset. Defaults to None.

  • name (Optional[str]) – Name to filter by. Defaults to None (no filtering).

  • label_status (Union[LabelStatus, List[LabelStatus], None]) – Sequence of label statuses to filter by. Defaults to None (no filtering).

  • metadata (Union[str, List[str], None]) – Sequence of ‘key:value’ metadata attributes to filter by. Defaults to None (no filtering).

  • sort (Literal['name', 'created', 'priority', 'updated_at', 'gt_label__updated_at']) – What to sort results by. One of name, created, priority, updated_at, gt_label__updated_at. Defaults to name.

  • direction (Literal['asc', 'desc']) – Sorting direction. One of asc (ascending) or desc (descending). Defaults to asc.

  • per_page (int) – Pagination parameter indicating the maximum number of samples to return. Defaults to 1000.

  • page (int) – Pagination parameter indicating the page to return. Defaults to 1.

  • include_full_label (bool) – Whether to include the full label in the response, or only a summary. Ignored if labelset is None. Defaults to False.

Raises:
Return type:

List[Sample]

clone(new_name=None, new_task_type=None, new_public=None, organization=None, clone_labels=False)[source]
Return type:

Dataset

get_collaborator(username)[source]

Fetches a specific collaborator from the dataset, see segments.client.SegmentsClient.get_dataset_collaborator() for more details.

Parameters:

username (str) – The username of the collaborator to be added.

Raises:

  • ValidationError – If validation of the collaborator fails.

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or dataset collaborator is not found.

  • NetworkError – If the request is not valid (e.g., if the dataset collaborator does not exist) or if the server experienced an error.

  • TimeoutError – If the request times out.

Return type:

Collaborator

add_collaborator(username, role=Role.LABELER)[source]

Adds a collaborator to the dataset, see segments.client.SegmentsClient.add_dataset_collaborator() for more details.

Parameters:

  • username (str) – The username of the collaborator to be added.

  • role (Role) – The role of the collaborator to be added. One of labeler, reviewer, manager, admin. Defaults to labeler.

Raises:
Return type:

Collaborator

add_release(name, description='')[source]

Adds a release to the dataset, see segments.client.SegmentsClient.add_release() for more details.

Parameters:

  • name (str) – The name of the release.

  • description (str) – The release description. Defaults to ''.

Raises:
Return type:

Release

get_release(name)[source]

Gets a specific release from the dataset, see segments.client.SegmentsClient.get_release() for more details.

Parameters:

name (str) – The name of the release.

Raises:

  • ValidationError – If validation of the release fails.

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or release is not found.

  • NetworkError – If the request is not valid (e.g., if the dataset does not exist) or if the server experienced an error.

  • TimeoutError – If the request times out.

Return type:

Release

get_releases()[source]

Lists all releases in the dataset, see segments.client.SegmentsClient.get_releases() for more details.

Raises:
Return type:

List[Release]

get_labelsets()[source]

Gets all labelsets in this dataset, see segments.client.SegmentsClient.get_labelsets() for more details.

Raises:
Return type:

List[Labelset]

get_labelset(name)[source]

Gets a labelset from this dataset, see segments.client.SegmentsClient.get_labelset() for more details.

Parameters:

name (str) – The name of the labelset.

Raises:

  • ValidationError – If validation of the labelset fails.

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or labelset is not found.

  • NetworkError – If the request is not valid (e.g., if the dataset does not exist) or if the server experienced an error.

  • TimeoutError – If the request times out.

Return type:

Labelset

add_labelset(name, description='')[source]

Adds a labelset to the dataset, see segments.client.SegmentsClient.add_labelset() for more details.

Parameters:

  • name (str) – The name of the labelset.

  • description (str) – The labelset description. Defaults to ''.

Raises:
Return type:

Labelset

get_issues()[source]

Gets all issues in this dataset, see segments.client.SegmentsClient.get_issues() for more details.

Raises:
Return type:

List[Issue]

get_workunits(sort='created_at', direction='desc', start=None, end=None, per_page=1000, page=1)[source]

Lists all workunits associated to this dataset, see segments.client.SegmentsClient.get_workunits() for more details.

Parameters:

  • sort (str) – What to sort results by. One of created_at. Defaults to created_at.

  • direction (str) – Sorting direction. One of asc (ascending) or desc (descending). Defaults to desc.

  • start (Optional[str]) – The start datetime for filtering workunits. Must be in the format ‘YYYY-MM-DDTHH:MM:SS’. Defaults to None.

  • end (Optional[str]) – The end datetime for filtering workunits. Must be in the format ‘YYYY-MM-DDTHH:MM:SS’. Defaults to None.

  • per_page (int) – Pagination parameter indicating the maximum number of results to return. Defaults to 1000.

  • page (int) – Pagination parameter indicating the page to return. Defaults to 1.

Raises:
Return type:

List[Workunit]

Sample

class Sample(**data)[source]

See Sample an overview of the properties this model has.

property dataset: Dataset

This property contains a lazy loaded dataset object that this sample belongs to.

When using the high level API, this property is always available. When fetching the sample with a SegmentsClient directly, using this property will trigger an additional API request to fetch the dataset.

delete()[source]

Deletes this sample. See segments.client.SegmentsClient.delete_sample() for more details.

Raises:
Return type:

None

update(name=None, attributes=None, metadata=None, priority=None, assigned_labeler=None, assigned_reviewer=None, readme=None, enable_compression=True)[source]

Updates this sample. See segments.client.SegmentsClient.update_sample() for more details.

Parameters:

  • name (Optional[str]) – The name of the sample.

  • attributes (Union[Dict[str, Any], ImageSampleAttributes, ImageSequenceSampleAttributes, PointcloudSampleAttributes, PointcloudSequenceSampleAttributes, MultiSensorSampleAttributes, None]) – The sample attributes. Please refer to the online documentation.

  • metadata (Optional[Dict[str, Any]]) – Any sample metadata. Example: {'weather': 'sunny', 'camera_id': 3}.

  • priority (Optional[float]) – Priority in the labeling queue. Samples with higher values will be labeled first.

  • assigned_labeler (Optional[str]) – The username of the user who should label this sample. Leave empty to not assign a specific labeler.

  • assigned_reviewer (Optional[str]) – The username of the user who should review this sample. Leave empty to not assign a specific reviewer.

  • readme (Optional[str]) – The sample readme.

  • enable_compression (bool) – Whether to enable gzip compression for the request. Defaults to True.

Raises:
Return type:

Sample

get_label(labelset='ground-truth')[source]

Gets the label of this sample. See segments.client.SegmentsClient.get_label() for more details.

Parameters:

labelset (Optional[str]) – The labelset this label belongs to. Defaults to ground-truth.

Raises:
Return type:

Label

add_label(labelset, attributes, label_status=LabelStatus.PRELABELED, score=None, enable_compression=True)[source]

Adds a label to this sample. See segments.client.SegmentsClient.add_label() for more details.

Parameters:
Raises:
Return type:

Label

update_label(labelset, attributes, label_status=LabelStatus.PRELABELED, score=None, enable_compression=True)[source]

Updates the label of this sample. See segments.client.SegmentsClient.update_label() for more details.

Parameters:
Raises:
Return type:

Label

delete_label(labelset)[source]

Deletes the label of this sample. See segments.client.SegmentsClient.delete_label() for more details.

Parameters:

labelset (str) – The labelset this label belongs to.

Raises:
Return type:

None

add_issue(description, status=IssueStatus.OPEN)[source]

Adds an issue to this sample. See segments.client.SegmentsClient.add_issue() for more details.

Parameters:

  • description (str) – The issue description.

  • status (IssueStatus) – The issue status. One of OPEN or CLOSED. Defaults to OPEN.

Raises:
Return type:

Issue

get_issues()[source]

Gets all issues associated to this sample. See segments.client.SegmentsClient.get_issues() for more details.

Raises:
Return type:

List[Issue]

Label

class Label(**data)[source]

See Label an overview of the properties this model has.

update(attributes, label_status=LabelStatus.PRELABELED, score=None, enable_compression=True)[source]

Updates this sample. See segments.client.SegmentsClient.update_label() for more details.

Parameters:
Raises:
Return type:

Label

delete()[source]

Deletes this label. See segments.client.SegmentsClient.delete_label() for more details.

Raises:
Return type:

None

Issue

class Issue(**data)[source]

See Issue an overview of the properties this model has.

update(description=None, status=None)[source]

Updates this issue. See segments.client.SegmentsClient.add_issue() for more details.

Parameters:

  • description (Optional[str]) – The issue description. Defaults to None.

  • status (Optional[IssueStatus]) – The issue status. One of OPEN or CLOSED. Defaults to None.

Raises:
Return type:

Issue

delete()[source]

Deletes this issue. See segments.client.SegmentsClient.delete_issue() for more details.

Raises:
Return type:

None

Collaborator

class Collaborator(**data)[source]

See Collaborator an overview of the properties this model has.

property dataset
delete()[source]

Delete a dataset collaborator. See segments.client.SegmentsClient.delete_dataset_collaborator() for more details.

Raises:

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or dataset collaborator is not found.

  • NetworkError – If the request is not valid or if the server experienced an error.

  • TimeoutError – If the request times out.

  • MissingContextError – If the dataset property is not available, usually because the Collaborator object was not fetched using the resource api.

Return type:

None

update(role)[source]

Update this dataset collaborator. See segments.client.SegmentsClient.update_dataset_collaborator() for more details.

Parameters:

role (Role) – The role of the collaborator to be added. Defaults to labeler.

Raises:

  • ValidationError – If validation of the collaborator fails.

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or dataset collaborator is not found.

  • NetworkError – If the request is not valid or if the server experienced an error.

  • TimeoutError – If the request times out.

  • MissingContextError – If the dataset property is not available, usually because the Collaborator object was not fetched using the resource api.

Return type:

Collaborator

Labelset

class Labelset(**data)[source]
property dataset
delete()[source]

Deletes this labelset. See segments.client.SegmentsClient.delete_labelset() for more details.

Raises:

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or labelset is not found.

  • NetworkError – If the request is not valid or if the server experienced an error.

  • TimeoutError – If the request times out.

  • MissingContextError – If the dataset property is not available, usually because the Labelset object was not fetched using the resource api.

Return type:

None

Release

class Release(**data)[source]
property dataset
delete()[source]

Deletes this release. See segments.client.SegmentsClient.delete_release() for more details.

Raises:

  • APILimitError – If the API limit is exceeded.

  • NotFoundError – If the dataset or release is not found.

  • NetworkError – If the request is not valid or if the server experienced an error.

  • TimeoutError – If the request times out.

  • MissingContextError – If the dataset property is not available, usually because the Release object was not fetched using the resource api.

Return type:

None