Merge pull request #296 from Labelbox/develop

3.6.0

Author: msokoloff1

CHANGELOG.md

@@ -1,4 +1,18 @@
 # Changelog
+# Version 3.6.0 (2021-04-10)
+## Added
+* Bulk export metadata with `DataRowMetadataOntology.bulk_export()`
+* Add docstring examples of annotation types and a few helper methods
+
+## Updated
+* Update metadata notebook under examples/basics to include bulk_export.
+* Allow color to be a single integer when constructing Mask objects
+* Allow users to pass int arrays to RasterData and attempt coercion to uint8
+
+## Removed
+* data_row.metadata was removed in favor of bulk exports.
+
+
 # Version 3.5.0 (2021-15-09)
 ## Added
 * Diagnostics custom metrics

examples/basics/data_row_metadata.ipynb

@@ -55,9 +55,10 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
-    "!pip install --upgrade tensorflow-hub scikit-learn\n",
-    "!pip install --upgrade \"labelbox[data]\""
+    "!pip install -q --upgrade tensorflow-hub \\\n",
+    "                 scikit-learn \\\n",
+    "                 seaborn \\\n",
+    "                 \"labelbox[data]\""
    ]
   },
   {
@@ -90,12 +91,13 @@
     ")\n",
     "from sklearn.random_projection import GaussianRandomProjection\n",
     "import seaborn as sns\n",
-    "import datetime\n",
+    "from datetime import datetime\n",
     "from pprint import pprint\n",
     "import tensorflow_hub as hub\n",
     "from tqdm.notebook import tqdm\n",
     "import requests\n",
-    "import tensorflow as tf"
+    "import tensorflow as tf\n",
+    "from pprint import pprint"
    ]
   },
   {
@@ -361,7 +363,7 @@
     "        split = \"cko8sbscr0003h2dk04w86hof\"\n",
     "    \n",
     "    embeddings.append(list(model(processor(response.content), training=False)[0].numpy()))\n",
-    "    dt = datetime.datetime.utcnow() \n",
+    "    dt = datetime.utcnow() \n",
     "    message =\"my-new-message\"\n",
     "\n",
     "    uploads.append(\n",
@@ -525,7 +527,7 @@
    },
    "outputs": [],
    "source": [
-    "metadata = mdo.parse_metadata([datarow.metadata])"
+    "metadata = mdo.bulk_export([datarow.uid])[0]"
    ]
   },
   {
@@ -584,7 +586,7 @@
    },
    "outputs": [],
    "source": [
-    "len(client.get_data_row(deletes.data_row_id).metadata[\"fields\"])"
+    "len(mdo.bulk_export(deletes.data_row_id)[0].fields)"
    ]
   },
   {
@@ -608,7 +610,7 @@
    },
    "outputs": [],
    "source": [
-    "len(client.get_data_row(deletes.data_row_id).metadata[\"fields\"])"
+    "len(mdo.bulk_export(deletes.data_row_id)[0].fields)"
    ]
   },
   {

examples/model_diagnostics/custom_metrics_basics.ipynb

@@ -96,12 +96,11 @@
    "metadata": {},
    "source": [
     "## Custom Metrics\n",
-    "* Users can provide metrics to provide metric information at different levels of granularity.\n",
-    "    * Users can provide metrics for \n",
-    "        1. data rows\n",
-    "        2. features\n",
-    "        3. subclasses\n",
-    "    * Additionally, metrics can be given custom names to best describe what they are measuring.\n",
+    "* Users can provide metrics at the following levels of granularity:\n",
+    "    1. data rows\n",
+    "    2. features\n",
+    "    3. subclasses\n",
+    "* Additionally, metrics can be given custom names to best describe what they are measuring.\n",
     "    \n",
     "* Limits and Behavior:\n",
     "    * At a data row cannot have more than 20 metrics\n",

labelbox/__init__.py

@@ -1,11 +1,11 @@
 name = "labelbox"
-__version__ = "3.5.0"
+__version__ = "3.6.0"
 
 from labelbox.schema.project import Project
 from labelbox.client import Client
 from labelbox.schema.model import Model
 from labelbox.schema.bulk_import_request import BulkImportRequest
-from labelbox.schema.annotation_import import MALPredictionImport, MEAPredictionImport
+from labelbox.schema.annotation_import import MALPredictionImport, MEAPredictionImport, LabelImport
 from labelbox.schema.dataset import Dataset
 from labelbox.schema.data_row import DataRow
 from labelbox.schema.label import Label

labelbox/data/annotation_types/annotation.py

@@ -1,47 +1,92 @@
+import abc
 from typing import Any, Dict, List, Union
 
 from .classification import Checklist, Dropdown, Radio, Text
 from .feature import FeatureSchema
-from .geometry import Geometry
+from .geometry import Geometry, Rectangle, Point
 from .ner import TextEntity
 
 
-class BaseAnnotation(FeatureSchema):
+class BaseAnnotation(FeatureSchema, abc.ABC):
     """ Base annotation class. Shouldn't be directly instantiated
     """
     extra: Dict[str, Any] = {}
 
 
 class ClassificationAnnotation(BaseAnnotation):
-    """Class representing classification annotations (annotations that don't have a location) """
+    """Classification annotations (non localized)
+
+    >>> ClassificationAnnotation(
+    >>>     value=Text(answer="my caption message"),
+    >>>     feature_schema_id="my-feature-schema-id"
+    >>> )
+
+    Args:
+        name (Optional[str])
+        feature_schema_id (Optional[Cuid])
+        value (Union[Text, Checklist, Radio, Dropdown])
+        extra (Dict[str, Any])
+     """
 
     value: Union[Text, Checklist, Radio, Dropdown]
 
 
 class ObjectAnnotation(BaseAnnotation):
-    """Class representing objects annotations (non classifications or annotations that have a location)
+    """Generic localized annotation (non classifications)
+
+    >>> ObjectAnnotation(
+    >>>     value=Rectangle(
+    >>>        start=Point(x=0, y=0),
+    >>>        end=Point(x=1, y=1)
+    >>>     ),
+    >>>     feature_schema_id="my-feature-schema-id"
+    >>> )
+
+    Args:
+        name (Optional[str])
+        feature_schema_id (Optional[Cuid])
+        value (Union[TextEntity, Geometry]): Localization of the annotation
+        classifications (Optional[List[ClassificationAnnotation]]): Optional sub classification of the annotation
+        extra (Dict[str, Any])
     """
     value: Union[TextEntity, Geometry]
     classifications: List[ClassificationAnnotation] = []
 
 
 class VideoObjectAnnotation(ObjectAnnotation):
-    """
-    Class for video objects annotations
+    """Video object annotation
+
+    >>> VideoObjectAnnotation(
+    >>>     keyframe=True,
+    >>>     frame=10,
+    >>>     value=Rectangle(
+    >>>        start=Point(x=0, y=0),
+    >>>        end=Point(x=1, y=1)
+    >>>     ),
+    >>>     feature_schema_id="my-feature-schema-id"
+    >>>)
 
     Args:
-        frame: The frame index that this annotation corresponds to
-        keyframe: Whether or not this annotation was a human generated or interpolated annotation
+        name (Optional[str])
+        feature_schema_id (Optional[Cuid])
+        value (Geometry)
+        frame (Int): The frame index that this annotation corresponds to
+        keyframe (bool): Whether or not this annotation was a human generated or interpolated annotation
+        classifications (List[ClassificationAnnotation]) = []
+        extra (Dict[str, Any])
     """
     frame: int
     keyframe: bool
 
 
 class VideoClassificationAnnotation(ClassificationAnnotation):
-    """
-    Class for video classification annotations
+    """Video classification
 
     Args:
-        frame: The frame index that this annotation corresponds to
+        name (Optional[str])
+        feature_schema_id (Optional[Cuid])
+        value (Union[Text, Checklist, Radio, Dropdown])
+        frame (int): The frame index that this annotation corresponds to
+        extra (Dict[str, Any])
     """
     frame: int

labelbox/data/annotation_types/data/raster.py

@@ -1,34 +1,53 @@
-from typing import Callable, Optional
-from io import BytesIO
 from abc import ABC
-
+from io import BytesIO
+from typing import Callable, Optional, Union
+from typing_extensions import Literal
 import numpy as np
-from pydantic import BaseModel
 import requests
+from PIL import Image
 from google.api_core import retry
-from typing_extensions import Literal
+from pydantic import BaseModel
 from pydantic import root_validator
-from PIL import Image
 
 from .base_data import BaseData
 from ..types import TypedArray
 
 
 class RasterData(BaseModel, ABC):
-    """
-    Represents an image or segmentation mask.
+    """Represents an image or segmentation mask.
     """
     im_bytes: Optional[bytes] = None
     file_path: Optional[str] = None
     url: Optional[str] = None
     arr: Optional[TypedArray[Literal['uint8']]] = None
 
     @classmethod
-    def from_2D_arr(cls, arr: TypedArray[Literal['uint8']], **kwargs):
+    def from_2D_arr(cls, arr: Union[TypedArray[Literal['uint8']],
+                                    TypedArray[Literal['int']]], **kwargs):
+        """Construct from a 2D numpy array
+
+        Args:
+            arr: uint8 compatible numpy array
+
+        Returns:
+            RasterData
+        """
+
         if len(arr.shape) != 2:
             raise ValueError(
-                f"Found array with shape {arr.shape}. Expected two dimensions ([W,H])"
+                f"Found array with shape {arr.shape}. Expected two dimensions [H, W]"
+            )
+
+        if not np.issubdtype(arr.dtype, np.integer):
+            raise ValueError("Array must be an integer subtype")
+
+        if np.can_cast(arr, np.uint8):
+            arr = arr.astype(np.uint8)
+        else:
+            raise ValueError(
+                "Could not cast array to uint8, check that values are between 0 and 255"
             )
+
         arr = np.stack((arr,) * 3, axis=-1)
         return cls(arr=arr, **kwargs)
 
@@ -153,10 +172,10 @@ def validate_args(cls, values):
 
     def __repr__(self) -> str:
         symbol_or_none = lambda data: '...' if data is not None else None
-        return  f"{self.__class__.__name__}(im_bytes={symbol_or_none(self.im_bytes)}," \
-                f"file_path={self.file_path}," \
-                f"url={self.url}," \
-                f"arr={symbol_or_none(self.arr)})"
+        return f"{self.__class__.__name__}(im_bytes={symbol_or_none(self.im_bytes)}," \
+               f"file_path={self.file_path}," \
+               f"url={self.url}," \
+               f"arr={symbol_or_none(self.arr)})"
 
     class Config:
         # Required for sharing references
@@ -166,7 +185,25 @@ class Config:
 
 
 class MaskData(RasterData):
-    ...
+    """Used to represent a segmentation Mask
+
+    All segments within a mask must be mutually exclusive. At a
+    single cell, only one class can be present. All Mask data is
+    converted to a [H,W,3] image. Classes are
+
+    >>> # 3x3 mask with two classes and back ground
+    >>> MaskData.from_2D_arr([
+    >>>    [0, 0, 0],
+    >>>    [1, 1, 1],
+    >>>    [2, 2, 2],
+    >>>])
+
+    Args:
+        im_bytes: Optional[bytes] = None
+        file_path: Optional[str] = None
+        url: Optional[str] = None
+        arr: Optional[TypedArray[Literal['uint8']]] = None
+    """
 
 
 class ImageData(RasterData, BaseData):

labelbox/data/annotation_types/geometry/geometry.py

@@ -8,8 +8,7 @@
 
 
 class Geometry(BaseModel, ABC):
-    """
-    Base class for geometry objects.
+    """Abstract base class for geometry objects
     """
     extra: Dict[str, Any] = {}
 

labelbox/data/annotation_types/geometry/line.py

@@ -9,6 +9,12 @@
 
 
 class Line(Geometry):
+    """Line annotation
+
+    Args:
+        points (List[Point]): A list of `Point` geometries
+
+    """
     points: List[Point]
 
     @property