scale-nucleus 0.11b2__tar.gz → 0.12b9__tar.gz

{scale-nucleus-0.11b2 → scale-nucleus-0.12b9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: scale-nucleus
-Version: 0.11b2
+Version: 0.12b9
 Summary: The official Python client library for Nucleus, the Data Platform for AI
 Home-page: https://scale.com/nucleus
 License: MIT
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Provides-Extra: shapely
-Requires-Dist: Pillow (>=8.3.1)
+Requires-Dist: Pillow (>=7.1.2)
 Requires-Dist: Shapely (>=1.8.0); extra == "shapely"
 Requires-Dist: aiohttp (>=3.7.4,<4.0.0)
 Requires-Dist: click (>=7.1.2,<9.0)

{scale-nucleus-0.11b2 → scale-nucleus-0.12b9}/nucleus/__init__.py

@@ -841,6 +841,10 @@ class NucleusClient:
         if payload is None:
             payload = {}
         if requests_command is requests.get:
+            if payload:
+                print(
+                    "Received defined payload with GET request! Will ignore payload"
+                )
             payload = None
         return self._connection.make_request(payload, route, requests_command)  # type: ignore
 

{scale-nucleus-0.11b2 → scale-nucleus-0.12b9}/nucleus/annotation_uploader.py

@@ -1,4 +1,5 @@
 import json
+from collections import Counter
 from typing import TYPE_CHECKING, Iterable, List, Optional, Sequence
 
 from nucleus.annotation import Annotation, SegmentationAnnotation
@@ -8,6 +9,7 @@ from nucleus.async_utils import (
     make_many_form_data_requests_concurrently,
 )
 from nucleus.constants import MASK_TYPE, SERIALIZED_REQUEST_KEY
+from nucleus.errors import DuplicateIDError
 from nucleus.payload_constructor import (
     construct_annotation_payload,
     construct_segmentation_payload,
@@ -208,6 +210,26 @@ class AnnotationUploader:
 
         return fn
 
+    @staticmethod
+    def check_for_duplicate_ids(annotations: Iterable[Annotation]):
+        """Do not allow annotations to have the same (annotation_id, reference_id) tuple"""
+
+        # some annotations like CategoryAnnotation do not have annotation_id attribute, and as such, we allow duplicates
+        tuple_ids = [
+            (ann.reference_id, ann.annotation_id)  # type: ignore
+            for ann in annotations
+            if hasattr(ann, "annotation_id")
+        ]
+        tuple_count = Counter(tuple_ids)
+        duplicates = {key for key, value in tuple_count.items() if value > 1}
+        if len(duplicates) > 0:
+            raise DuplicateIDError(
+                f"Duplicate annotations with the same (reference_id, annotation_id) properties found.\n"
+                f"Duplicates: {duplicates}\n"
+                f"To fix this, avoid duplicate annotations, or specify a different annotation_id attribute "
+                f"for the failing items."
+            )
+
 
 class PredictionUploader(AnnotationUploader):
     def __init__(

{scale-nucleus-0.11b2 → scale-nucleus-0.12b9}/nucleus/dataset.py

@@ -389,6 +389,9 @@ class Dataset:
 
             Otherwise, returns an :class:`AsyncJob` object.
         """
+        uploader = AnnotationUploader(dataset_id=self.id, client=self._client)
+        uploader.check_for_duplicate_ids(annotations)
+
         if asynchronous:
             check_all_mask_paths_remote(annotations)
             request_id = serialize_and_write_to_presigned_url(
@@ -399,7 +402,7 @@ class Dataset:
                 route=f"dataset/{self.id}/annotate?async=1",
             )
             return AsyncJob.from_json(response, self._client)
-        uploader = AnnotationUploader(dataset_id=self.id, client=self._client)
+
         return uploader.upload(
             annotations=annotations,
             update=update,
@@ -1004,6 +1007,45 @@ class Dataset:
 
         return response
 
+    def get_image_indexing_status(self):
+        """Gets the primary image index progress for the dataset.
+
+        Returns:
+            Response payload::
+
+                {
+                    "embedding_count": int
+                    "image_count": int
+                    "percent_indexed": float
+                    "additional_context": str
+                }
+        """
+        return self._client.make_request(
+            {"image": True},
+            f"dataset/{self.id}/indexingStatus",
+            requests_command=requests.post,
+        )
+
+    def get_object_indexing_status(self, model_run_id=None):
+        """Gets the primary object index progress of the dataset.
+        If model_run_id is not specified, this endpoint will retrieve the indexing progress of the ground truth objects.
+
+        Returns:
+            Response payload::
+
+                {
+                    "embedding_count": int
+                    "object_count": int
+                    "percent_indexed": float
+                    "additional_context": str
+                }
+        """
+        return self._client.make_request(
+            {"image": False, "model_run_id": model_run_id},
+            f"dataset/{self.id}/indexingStatus",
+            requests_command=requests.post,
+        )
+
     def create_image_index(self):
         """Creates or updates image index by generating embeddings for images that do not already have embeddings.
 
@@ -1405,6 +1447,14 @@ class Dataset:
                     "predictions_ignored": int,
                 }
         """
+        uploader = PredictionUploader(
+            model_run_id=None,
+            dataset_id=self.id,
+            model_id=model.id,
+            client=self._client,
+        )
+        uploader.check_for_duplicate_ids(predictions)
+
         if asynchronous:
             check_all_mask_paths_remote(predictions)
 
@@ -1416,21 +1466,15 @@ class Dataset:
                 route=f"dataset/{self.id}/model/{model.id}/uploadPredictions?async=1",
             )
             return AsyncJob.from_json(response, self._client)
-        else:
-            uploader = PredictionUploader(
-                model_run_id=None,
-                dataset_id=self.id,
-                model_id=model.id,
-                client=self._client,
-            )
-            return uploader.upload(
-                annotations=predictions,
-                batch_size=batch_size,
-                update=update,
-                remote_files_per_upload_request=remote_files_per_upload_request,
-                local_files_per_upload_request=local_files_per_upload_request,
-                local_file_upload_concurrency=local_file_upload_concurrency,
-            )
+
+        return uploader.upload(
+            annotations=predictions,
+            batch_size=batch_size,
+            update=update,
+            remote_files_per_upload_request=remote_files_per_upload_request,
+            local_files_per_upload_request=local_files_per_upload_request,
+            local_file_upload_concurrency=local_file_upload_concurrency,
+        )
 
     def predictions_iloc(self, model, index):
         """Fetches all predictions of a dataset item by its absolute index.

{scale-nucleus-0.11b2 → scale-nucleus-0.12b9}/nucleus/errors.py

@@ -72,3 +72,9 @@ class NoAPIKey(Exception):
     ):
         self.message = message
         super().__init__(self.message)
+
+
+class DuplicateIDError(Exception):
+    def __init__(self, message):
+        self.message = message
+        super().__init__(self.message)

{scale-nucleus-0.11b2 → scale-nucleus-0.12b9}/nucleus/metrics/__init__.py

@@ -5,6 +5,8 @@ from .filtering import (
     FieldFilter,
     ListOfOrAndFilters,
     MetadataFilter,
+    SegmentFieldFilter,
+    SegmentMetadataFilter,
     apply_filters,
 )
 from .polygon_metrics import (
@@ -16,6 +18,15 @@ from .polygon_metrics import (
     PolygonRecall,
 )
 from .segmentation_metrics import (
+    SegmentationAveragePrecision,
+    SegmentationFWAVACC,
+    SegmentationIOU,
+    SegmentationMAP,
+    SegmentationMaskMetric,
+    SegmentationPrecision,
+    SegmentationRecall,
+)
+from .segmentation_to_poly_metrics import (
     SegmentationMaskToPolyMetric,
     SegmentationToPolyAveragePrecision,
     SegmentationToPolyIOU,

{scale-nucleus-0.11b2 → scale-nucleus-0.12b9}/nucleus/metrics/filtering.py

@@ -2,7 +2,16 @@ import enum
 import functools
 import logging
 from enum import Enum
-from typing import Callable, Iterable, List, NamedTuple, Sequence, Set, Union
+from typing import (
+    Callable,
+    Iterable,
+    List,
+    NamedTuple,
+    Sequence,
+    Set,
+    Tuple,
+    Union,
+)
 
 from nucleus.annotation import (
     BoxAnnotation,
@@ -11,6 +20,7 @@ from nucleus.annotation import (
     LineAnnotation,
     MultiCategoryAnnotation,
     PolygonAnnotation,
+    Segment,
     SegmentationAnnotation,
 )
 from nucleus.prediction import (
@@ -40,10 +50,14 @@ class FilterType(str, enum.Enum):
     Attributes:
         FIELD: Access the attribute field of an object
         METADATA: Access the metadata dictionary of an object
+        SEGMENT_FIELD: Filter segments of a segmentation mask to be considered on segment fields
+        SEGMENT_METADATA: Filter segments of a segmentation mask based on segment metadata
     """
 
     FIELD = "field"
     METADATA = "metadata"
+    SEGMENT_FIELD = "segment_field"
+    SEGMENT_METADATA = "segment_metadata"
 
 
 FilterableBaseVals = Union[str, float, int, bool]
@@ -100,7 +114,8 @@ class FieldFilter(NamedTuple):
 
     Examples:
         FieldFilter("x", ">", 10) would pass every :class:`BoxAnnotation` with `x` attribute larger than 10
-        FieldFilter("label", "in", [) would pass every :class:`BoxAnnotation` with `x` attribute larger than 10
+        FieldFilter("label", "in", ["car", "truck"]) would pass every :class:`BoxAnnotation` with `label`
+            in ["car", "truck"]
 
     Attributes:
         key: key to compare with value
@@ -129,7 +144,7 @@ class MetadataFilter(NamedTuple):
             with value field
         value: bool, str, float or int to compare the field with key or list of the same values for 'in' and 'not in'
             ops
-        allow_missing: Allow missing metada values. Will REMOVE the object with the missing field from the selection
+        allow_missing: Allow missing metadata values. Will REMOVE the object with the missing field from the selection
         type: DO NOT USE. Internal type for serialization over the wire. Changing this will change the `NamedTuple`
             type as well.
     """
@@ -141,7 +156,60 @@ class MetadataFilter(NamedTuple):
     type: FilterType = FilterType.METADATA
 
 
-Filter = Union[FieldFilter, MetadataFilter, AnnotationOrPredictionFilter]
+class SegmentMetadataFilter(NamedTuple):
+    """Filter on customer provided metadata associated with Segments of a SegmentationAnnotation or
+    SegmentationPrediction
+
+    Attributes:
+        key: key to compare with value
+        op: :class:`FilterOp` or one of [">", ">=", "<", "<=", "=", "==", "!=", "in", "not in"] to define comparison
+            with value field
+        value: bool, str, float or int to compare the field with key or list of the same values for 'in' and 'not in'
+            ops
+        allow_missing: Allow missing metadata values. Will REMOVE the object with the missing field from the selection
+        type: DO NOT USE. Internal type for serialization over the wire. Changing this will change the `NamedTuple`
+            type as well.
+    """
+
+    key: str
+    op: Union[FilterOp, str]
+    value: FilterableTypes
+    allow_missing: bool = False
+    type: FilterType = FilterType.SEGMENT_METADATA
+
+
+class SegmentFieldFilter(NamedTuple):
+    """Filter on standard field of Segment(s) of SegmentationAnnotation and SegmentationPrediction
+
+    Examples:
+        SegmentFieldFilter("label", "in", ["grass", "tree"]) would pass every :class:`Segment` of a
+            :class:`SegmentationAnnotation or :class:`SegmentationPrediction`
+
+    Attributes:
+        key: key to compare with value
+        op: :class:`FilterOp` or one of [">", ">=", "<", "<=", "=", "==", "!=", "in", "not in"] to define comparison
+            with value field
+        value: bool, str, float or int to compare the field with key or list of the same values for 'in' and 'not in'
+            ops
+        allow_missing: Allow missing field values. Will REMOVE the object with the missing field from the selection
+        type: DO NOT USE. Internal type for serialization over the wire. Changing this will change the `NamedTuple`
+            type as well.
+    """
+
+    key: str
+    op: Union[FilterOp, str]
+    value: FilterableTypes
+    allow_missing: bool = False
+    type: FilterType = FilterType.SEGMENT_FIELD
+
+
+Filter = Union[
+    FieldFilter,
+    MetadataFilter,
+    AnnotationOrPredictionFilter,
+    SegmentFieldFilter,
+    SegmentMetadataFilter,
+]
 OrAndDNFFilters = List[List[Filter]]
 OrAndDNFFilters.__doc__ = """\
 Disjunctive normal form (DNF) filters.
@@ -182,11 +250,15 @@ ListOfAndFilters = Union[
     ListOfAndJSONSerialized,
 ]
 
+DNFFieldOrMetadataFilters = List[
+    List[Union[FieldFilter, MetadataFilter, AnnotationOrPredictionFilter]]
+]
+
 
 def _attribute_getter(
     field_name: str,
     allow_missing: bool,
-    ann_or_pred: Union[AnnotationTypes, PredictionTypes],
+    ann_or_pred: Union[AnnotationTypes, PredictionTypes, Segment],
 ):
     """Create a function to get object fields"""
     if allow_missing:
@@ -224,7 +296,7 @@ class AlwaysFalseComparison:
 def _metadata_field_getter(
     field_name: str,
     allow_missing: bool,
-    ann_or_pred: Union[AnnotationTypes, PredictionTypes],
+    ann_or_pred: Union[AnnotationTypes, PredictionTypes, Segment],
 ):
     """Create a function to get a metadata field"""
     if isinstance(
@@ -259,7 +331,7 @@ def _metadata_field_getter(
 
 def _filter_to_comparison_function(  # pylint: disable=too-many-return-statements
     filter_def: Filter,
-) -> Callable[[Union[AnnotationTypes, PredictionTypes]], bool]:
+) -> Callable[[Union[AnnotationTypes, PredictionTypes, Segment]], bool]:
     """Creates a comparison function from a filter configuration to apply to annotations or predictions
 
     Parameters:
@@ -276,6 +348,10 @@ def _filter_to_comparison_function(  # pylint: disable=too-many-return-statement
         getter = functools.partial(
             _metadata_field_getter, filter_def.key, filter_def.allow_missing
         )
+    else:
+        raise NotImplementedError(
+            f"Unhandled filter type: {filter_def.type}. NOTE: Segmentation filters are handled elsewhere."
+        )
     op = FilterOp(filter_def.op)
     if op is FilterOp.GT:
         return lambda ann_or_pred: getter(ann_or_pred) > filter_def.value
@@ -303,13 +379,16 @@ def _filter_to_comparison_function(  # pylint: disable=too-many-return-statement
         )
 
 
-def apply_filters(
-    ann_or_pred: Union[Sequence[AnnotationTypes], Sequence[PredictionTypes]],
-    filters: Union[ListOfOrAndFilters, ListOfAndFilters],
+def _apply_field_or_metadata_filters(
+    filterable_sequence: Union[
+        Sequence[AnnotationTypes], Sequence[PredictionTypes], Sequence[Segment]
+    ],
+    filters: DNFFieldOrMetadataFilters,
 ):
-    """Apply filters to list of annotations or list of predictions
+    """Apply filters to list of annotations or list of predictions or to a list of segments
+
     Attributes:
-        ann_or_pred: Prediction or Annotation
+        filterable_sequence: Prediction or Annotation or Segment sequence
         filters: Filter predicates. Allowed formats are:
             ListOfAndFilters where each Filter forms a chain of AND predicates.
             or
@@ -320,11 +399,6 @@ def apply_filters(
             is interpreted as a conjunction (AND), forming a more selective `and` multiple column predicate.
             Finally, the most outer list combines these filters as a disjunction (OR).
     """
-    if filters is None or len(filters) == 0:
-        return ann_or_pred
-
-    filters = ensureDNFFilters(filters)
-
     dnf_condition_functions = []
     for or_branch in filters:
         and_conditions = [
@@ -333,18 +407,136 @@ def apply_filters(
         dnf_condition_functions.append(and_conditions)
 
     filtered = []
-    for item in ann_or_pred:
+    for item in filterable_sequence:
         for or_conditions in dnf_condition_functions:
             if all(c(item) for c in or_conditions):
                 filtered.append(item)
                 break
+
+    return filtered
+
+
+def _split_segment_filters(
+    dnf_filters: OrAndDNFFilters,
+) -> Tuple[OrAndDNFFilters, OrAndDNFFilters]:
+    """We treat Segment* filters differently -> this splits filters into two sets, one containing the
+    standard field, metadata branches and the other the segment filters.
+    """
+    normal_or_branches = []
+    segment_or_branches = []
+    for and_branch in dnf_filters:
+        normal_filters = []
+        segment_filters = []
+        for filter_statement in and_branch:
+            if filter_statement.type in {
+                FilterType.SEGMENT_METADATA,
+                FilterType.SEGMENT_FIELD,
+            }:
+                segment_filters.append(filter_statement)
+            else:
+                normal_filters.append(filter_statement)
+        normal_or_branches.append(normal_filters)
+        segment_or_branches.append(segment_filters)
+    return normal_or_branches, segment_or_branches
+
+
+def _filter_segments(
+    anns_or_preds: Union[
+        Sequence[SegmentationAnnotation], Sequence[SegmentationPrediction]
+    ],
+    segment_filters: OrAndDNFFilters,
+):
+    """Filter Segments of a SegmentationAnnotation or Prediction
+
+    We have to treat this differently as metadata and labels are on nested Segment objects
+    """
+    if len(segment_filters) == 0 or len(segment_filters[0]) == 0:
+        return anns_or_preds
+
+    # Transform segment filter types to field and metadata to iterate over annotation sub fields
+    transformed_or_branches = (
+        []
+    )  # type: List[List[Union[MetadataFilter, FieldFilter]]]
+    for and_branch in segment_filters:
+        transformed_and = []  # type: List[Union[MetadataFilter, FieldFilter]]
+        for filter_statement in and_branch:
+            if filter_statement.type == FilterType.SEGMENT_FIELD:
+                transformed_and.append(
+                    FieldFilter(
+                        filter_statement.key,
+                        filter_statement.op,
+                        filter_statement.value,
+                        filter_statement.allow_missing,
+                    )
+                )
+            elif filter_statement.type == FilterType.SEGMENT_METADATA:
+                transformed_and.append(
+                    MetadataFilter(
+                        filter_statement.key,
+                        filter_statement.op,
+                        filter_statement.value,
+                        filter_statement.allow_missing,
+                    )
+                )
+            else:
+                raise RuntimeError("Encountered a non SEGMENT_* filter type")
+
+        transformed_or_branches.append(transformed_and)
+
+    segments_filtered = []
+    for ann_or_pred in anns_or_preds:
+        if isinstance(
+            ann_or_pred, (SegmentationAnnotation, SegmentationPrediction)
+        ):
+            ann_or_pred.annotations = _apply_field_or_metadata_filters(
+                ann_or_pred.annotations, transformed_or_branches  # type: ignore
+            )
+            segments_filtered.append(ann_or_pred)
+
+    return segments_filtered
+
+
+def apply_filters(
+    ann_or_pred: Union[Sequence[AnnotationTypes], Sequence[PredictionTypes]],
+    filters: Union[ListOfOrAndFilters, ListOfAndFilters],
+):
+    """Apply filters to list of annotations or list of predictions
+    Attributes:
+        ann_or_pred: Prediction or Annotation
+        filters: Filter predicates. Allowed formats are:
+            ListOfAndFilters where each Filter forms a chain of AND predicates.
+            or
+            ListOfOrAndFilters where Filters are expressed in disjunctive normal form (DNF), like
+            [[MetadataFilter("short_haired", "==", True), FieldFilter("label", "in", ["cat", "dog"]), ...].
+            DNF allows arbitrary boolean logical combinations of single field
+            predicates. The innermost structures each describe a single column predicate. The list of inner predicates
+            is interpreted as a conjunction (AND), forming a more selective `and` multiple column predicate.
+            Finally, the most outer list combines these filters as a disjunction (OR).
+    """
+    if filters is None or len(filters) == 0:
+        return ann_or_pred
+
+    dnf_filters = ensureDNFFilters(filters)
+    filters, segment_filters = _split_segment_filters(dnf_filters)
+    filtered = _apply_field_or_metadata_filters(ann_or_pred, filters)  # type: ignore
+    filtered = _filter_segments(filtered, segment_filters)
+
     return filtered
 
 
 def ensureDNFFilters(filters) -> OrAndDNFFilters:
     """JSON encoding creates a triple nested lists from the doubly nested tuples. This function creates the
     tuple form again."""
-    if isinstance(filters[0], (MetadataFilter, FieldFilter)):
+    if isinstance(
+        filters[0],
+        (
+            MetadataFilter,
+            FieldFilter,
+            AnnotationOrPredictionFilter,
+            SegmentFieldFilter,
+            SegmentMetadataFilter,
+        ),
+    ):
         # Normalize into DNF
         filters: ListOfOrAndFilters = [filters]  # type: ignore