add support to fetch scene from an item (#370)

Author: jean-lucas

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to the [Nucleus Python Client](https://github.com/scaleapi/n
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.26](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.14.26) - 2022-11-01
+
+### Added
+- Support for fetching scene from a `DatasetItem.reference_id`
+Example:
+```python
+dataset = client.get_dataset("<dataset_id>")
+assert dataset.is_scene  # only works on scene datasets
+some_item = dataset.iloc(0)
+dataset.get_scene_from_item_ref_id(some_item['item'].reference_id) 
+```
+
+
 ## [0.14.25](https://github.com/scaleapi/nucleus-python-client/releases/tag/v0.14.25) - 2022-10-20
 
 ### Updated

nucleus/dataset.py

@@ -116,6 +116,7 @@ def __init__(self, dataset_id, client, name=None):
         self._client = client
         # NOTE: Optionally set name on creation such that the property access doesn't need to hit the server
         self._name = name
+        self._is_scene = None
 
     def __repr__(self):
         if os.environ.get("NUCLEUS_DEBUG", None):
@@ -141,10 +142,13 @@ def name(self) -> str:
     @property
     def is_scene(self) -> bool:
         """Whether or not the dataset contains scenes exclusively."""
+        if self._is_scene is not None:
+            return self._is_scene
         response = self._client.make_request(
             {}, f"dataset/{self.id}/is_scene", requests.get
         )[DATASET_IS_SCENE_KEY]
-        return response
+        self._is_scene = response
+        return self._is_scene
 
     @property
     def model_runs(self) -> List[str]:
@@ -1375,6 +1379,25 @@ def get_scene(self, reference_id: str) -> Scene:
             return VideoScene.from_json(response)
         return LidarScene.from_json(response)
 
+    def get_scene_from_item_ref_id(
+        self, item_reference_id: str
+    ) -> Optional[Scene]:
+        """Given a dataset item reference ID, find the Scene it belongs to."""
+        if not self.is_scene:
+            print(
+                f"Dataset {self.id} is not a scene. Cannot call this endpoint."
+            )
+            return None
+
+        response = self._client.make_request(
+            payload=None,
+            route=f"dataset/{self.id}/scene/{item_reference_id}?from_item=1",
+            requests_command=requests.get,
+        )
+        if FRAME_RATE_KEY in response or VIDEO_URL_KEY in response:
+            return VideoScene.from_json(response)
+        return LidarScene.from_json(response)
+
     def export_predictions(self, model):
         """Fetches all predictions of a model that were uploaded to the dataset.
 

pyproject.toml

@@ -21,7 +21,7 @@ exclude = '''
 
 [tool.poetry]
 name = "scale-nucleus"
-version = "0.14.25"
+version = "0.14.26"
 description = "The official Python client library for Nucleus, the Data Platform for AI"
 license =  "MIT"
 authors = ["Scale AI Nucleus Team <nucleusapi@scaleapi.com>"]