Merge pull request #96 from scaleapi/implement_scene_class

Implement Scene class

Author: sasha-scale

nucleus/__init__.py

@@ -109,7 +109,7 @@
     UPDATE_KEY,
 )
 from .dataset import Dataset
-from .dataset_item import DatasetItem
+from .dataset_item import DatasetItem, CameraParams
 from .errors import (
     DatasetItemRetrievalError,
     ModelCreationError,
@@ -135,6 +135,7 @@
 )
 from .slice import Slice
 from .upload_response import UploadResponse
+from .scene import Frame, Scene, LidarScene
 
 # pylint: disable=E1101
 # TODO: refactor to reduce this file to under 1000 lines.

nucleus/annotation.py

@@ -2,7 +2,7 @@
 from dataclasses import dataclass
 from enum import Enum
 from typing import Dict, List, Optional, Sequence, Union
-from nucleus.dataset_item import is_local_path
+from urllib.parse import urlparse
 
 from .constants import (
     ANNOTATION_ID_KEY,
@@ -310,13 +310,8 @@ def to_payload(self) -> dict:
         }
 
 
-def check_all_frame_paths_remote(frames: List[str]):
-    for frame_url in frames:
-        if is_local_path(frame_url):
-            raise ValueError(
-                f"All paths must be remote, but {frame_url} is either "
-                "local, or a remote URL type that is not supported."
-            )
+def is_local_path(path: str) -> bool:
+    return urlparse(path).scheme not in {"https", "http", "s3", "gs"}
 
 
 def check_all_mask_paths_remote(

nucleus/constants.py

@@ -12,8 +12,11 @@
 ANNOTATION_UPDATE_KEY = "update"
 AUTOTAGS_KEY = "autotags"
 EXPORTED_ROWS = "exportedRows"
+CAMERA_PARAMS_KEY = "camera_params"
 CLASS_PDF_KEY = "class_pdf"
 CONFIDENCE_KEY = "confidence"
+CX_KEY = "cx"
+CY_KEY = "cy"
 DATASET_ID_KEY = "dataset_id"
 DATASET_ITEM_IDS_KEY = "dataset_item_ids"
 DATASET_ITEM_ID_KEY = "dataset_item_id"
@@ -30,16 +33,21 @@
 ERROR_CODES = "error_codes"
 ERROR_ITEMS = "upload_errors"
 ERROR_PAYLOAD = "error_payload"
-FRAMES = "frames"
+FRAMES_KEY = "frames"
+FX_KEY = "fx"
+FY_KEY = "fy"
 GEOMETRY_KEY = "geometry"
+HEADING_KEY = "heading"
 HEIGHT_KEY = "height"
 IGNORED_ITEMS = "ignored_items"
 IMAGE_KEY = "image"
+IMAGE_LOCATION_KEY = "image_location"
 IMAGE_URL_KEY = "image_url"
 INDEX_KEY = "index"
 ITEMS_KEY = "items"
 ITEM_ID_KEY = "item_id"
 ITEM_KEY = "item"
+ITEMS_KEY = "items"
 ITEM_METADATA_SCHEMA_KEY = "item_metadata_schema"
 JOB_ID_KEY = "job_id"
 KEEP_HISTORY_KEY = "keep_history"
@@ -57,13 +65,15 @@
 NEW_ITEMS = "new_items"
 NUCLEUS_ENDPOINT = "https://api.scale.com/v1/nucleus"
 ORIGINAL_IMAGE_URL_KEY = "original_image_url"
+POINTCLOUD_LOCATION_KEY = "pointcloud_location"
+POINTCLOUD_URL_KEY = "pointcloud_url"
 POSITION_KEY = "position"
 PREDICTIONS_IGNORED_KEY = "predictions_ignored"
 PREDICTIONS_PROCESSED_KEY = "predictions_processed"
 REFERENCE_IDS_KEY = "reference_ids"
 REFERENCE_ID_KEY = "reference_id"
 REQUEST_ID_KEY = "requestId"
-SCENES = "scenes"
+SCENES_KEY = "scenes"
 SEGMENTATIONS_KEY = "segmentations"
 SLICE_ID_KEY = "slice_id"
 STATUS_CODE_KEY = "status_code"
@@ -72,10 +82,11 @@
 TYPE_KEY = "type"
 UPDATED_ITEMS = "updated_items"
 UPDATE_KEY = "update"
-URL = "url"
+URL_KEY = "url"
 VERTICES_KEY = "vertices"
 WIDTH_KEY = "width"
 YAW_KEY = "yaw"
+W_KEY = "w"
 X_KEY = "x"
 Y_KEY = "y"
 Z_KEY = "z"

nucleus/dataset.py

@@ -13,7 +13,6 @@
 from .annotation import (
     Annotation,
     check_all_mask_paths_remote,
-    check_all_frame_paths_remote,
 )
 from .constants import (
     DATASET_ITEM_IDS_KEY,
@@ -23,22 +22,24 @@
     DATASET_SLICES_KEY,
     DEFAULT_ANNOTATION_UPDATE_MODE,
     EXPORTED_ROWS,
-    FRAMES,
     NAME_KEY,
     REFERENCE_IDS_KEY,
     REQUEST_ID_KEY,
-    SCENES,
     UPDATE_KEY,
-    URL,
 )
 from .dataset_item import (
     DatasetItem,
     check_all_paths_remote,
     check_for_duplicate_reference_ids,
 )
-from .payload_constructor import construct_model_run_creation_payload
+from .scene import LidarScene, check_all_scene_paths_remote
+from .payload_constructor import (
+    construct_append_scenes_payload,
+    construct_model_run_creation_payload,
+)
 
 WARN_FOR_LARGE_UPLOAD = 50000
+WARN_FOR_LARGE_SCENES_UPLOAD = 5
 
 
 class Dataset:
@@ -199,16 +200,16 @@ def ingest_tasks(self, task_ids: dict):
 
     def append(
         self,
-        dataset_items: List[DatasetItem],
+        items: Union[List[DatasetItem], List[LidarScene]],
         update: Optional[bool] = False,
         batch_size: Optional[int] = 20,
         asynchronous=False,
     ) -> Union[dict, AsyncJob]:
         """
-        Appends images with metadata (dataset items) to the dataset. Overwrites images on collision if forced.
+        Appends images with metadata (dataset items) or scenes to the dataset. Overwrites images on collision if forced.
 
         Parameters:
-        :param dataset_items: items to upload
+        :param items: items to upload
         :param update: if True overwrites images and metadata on collision
         :param batch_size: batch parameter for long uploads
         :param aynchronous: if True, return a job object representing asynchronous ingestion job.
@@ -220,6 +221,17 @@ def append(
             'ignored_items': int,
         }
         """
+        dataset_items = [
+            item for item in items if isinstance(item, DatasetItem)
+        ]
+        scenes = [item for item in items if isinstance(item, LidarScene)]
+        if dataset_items and scenes:
+            raise Exception(
+                "You must append either DatasetItems or Scenes to the dataset."
+            )
+        if scenes:
+            return self.append_scenes(scenes, update, asynchronous)
+
         check_for_duplicate_reference_ids(dataset_items)
 
         if len(dataset_items) > WARN_FOR_LARGE_UPLOAD and not asynchronous:
@@ -248,39 +260,51 @@ def append(
             batch_size=batch_size,
         )
 
-    def upload_scenes(
+    def append_scenes(
         self,
-        payload: dict,
+        scenes: List[LidarScene],
         update: Optional[bool] = False,
-        asynchronous: bool = False,
+        asynchronous: Optional[bool] = False,
     ) -> Union[dict, AsyncJob]:
         """
-        Uploads scenes with given frames to the dataset
+        Appends scenes with given frames (containing pointclouds and optional images) to the dataset
 
         Parameters:
-        :param payload: dictionary containing scenes to be uploaded
+        :param scenes: scenes to upload
         :param update: if True, overwrite scene on collision
-        :param aynchronous: if True, return a job object representing asynchronous ingestion job
+        :param asynchronous: if True, return a job object representing asynchronous ingestion job
         :return:
         {
             'dataset_id': str,
             'new_scenes': int,
+            'ignored_scenes': int,
+            'scenes_errored': int,
+            'errors': List[str],
         }
         """
+        for scene in scenes:
+            scene.validate()
+
+        if len(scenes) > WARN_FOR_LARGE_SCENES_UPLOAD and not asynchronous:
+            print(
+                "Tip: for large uploads, get faster performance by importing your data "
+                "into Nucleus directly from a cloud storage provider. See "
+                "https://dashboard.scale.com/nucleus/docs/api?language=python#guide-for-large-ingestions"
+                " for details."
+            )
+
         if asynchronous:
-            for scene in payload[SCENES]:
-                for frame in scene[FRAMES]:
-                    check_all_frame_paths_remote(frame[URL])
+            check_all_scene_paths_remote(scenes)
             request_id = serialize_and_write_to_presigned_url(
-                [payload], self.id, self._client
+                scenes, self.id, self._client
             )
             response = self._client.make_request(
                 payload={REQUEST_ID_KEY: request_id, UPDATE_KEY: update},
                 route=f"{self.id}/upload_scenes?async=1",
             )
             return AsyncJob.from_json(response, self._client)
 
-        # TODO: create client method for sync scene upload
+        payload = construct_append_scenes_payload(scenes, update)
         response = self._client.make_request(
             payload=payload,
             route=f"{self.id}/upload_scenes",