copying good ideas from virtual fields

voxel51 · Aug 8, 2024 · 9ef797d · 9ef797d
1 parent 387f5e5
commit 9ef797d
Show file tree

Hide file tree

Showing 11 changed files with 452 additions and 250 deletions.
diff --git a/docs/source/user_guide/using_datasets.rst b/docs/source/user_guide/using_datasets.rst
@@ -1117,8 +1117,8 @@ New fields can be added to a |Sample| using item assignment:
     sample["integer_field"] = 51
     sample.save()
 
-If the |Sample| belongs to a |Dataset|, the dataset's field schema will be
-updated to reflect the new field:
+If the |Sample| belongs to a |Dataset|, the dataset's schema will automatically
+be updated to reflect the new field:
 
 .. code-block:: python
     :linenos:
@@ -1148,7 +1148,7 @@ A |Field| can be any primitive type, such as `bool`, `int`, `float`, `str`,
 .. code-block:: python
     :linenos:
 
-    sample["ground_truth"] = fo.Classification(label="alligator")
+    sample["animal"] = fo.Classification(label="alligator")
     sample.save()
 
 Whenever a new field is added to a sample in a dataset, the field is available

diff --git a/fiftyone/core/collections.py b/fiftyone/core/collections.py
@@ -1368,6 +1368,7 @@ def get_field_schema(
         read_only=None,
         include_private=False,
         flat=False,
+        mode=None,
     ):
         """Returns a schema dictionary describing the fields of the samples in
         the collection.
@@ -1386,9 +1387,14 @@ def get_field_schema(
                 read-only fields. By default, all fields are included
             flat (False): whether to return a flattened schema where all
                 embedded document fields are included as top-level keys
+            mode (None): whether to apply the above constraints before and/or
+                after flattening the schema. Only applicable when ``flat`` is
+                True. Supported values are ``("before", "after", "both")``.
+                The default is ``"after"``
 
         Returns:
-             a dictionary mapping field names to field types
+            a dict mapping field names to :class:`fiftyone.core.fields.Field`
+            instances
         """
         raise NotImplementedError("Subclass must implement get_field_schema()")
 
@@ -1399,9 +1405,10 @@ def get_frame_field_schema(
         read_only=None,
         include_private=False,
         flat=False,
+        mode=None,
     ):
-        """Returns a schema dictionary describing the fields of the frames of
-        the samples in the collection.
+        """Returns a schema dictionary describing the fields of the frames in
+        the collection.
 
         Only applicable for collections that contain videos.
 
@@ -1418,10 +1425,14 @@ def get_frame_field_schema(
                 ``_`` in the returned schema
             flat (False): whether to return a flattened schema where all
                 embedded document fields are included as top-level keys
+            mode (None): whether to apply the above constraints before and/or
+                after flattening the schema. Only applicable when ``flat`` is
+                True. Supported values are ``("before", "after", "both")``.
+                The default is ``"after"``
 
         Returns:
-            a dictionary mapping field names to field types, or ``None`` if
-            the collection does not contain videos
+            a dict mapping field names to :class:`fiftyone.core.fields.Field`
+            instances, or ``None`` if the collection does not contain videos
         """
         raise NotImplementedError(
             "Subclass must implement get_frame_field_schema()"
@@ -1441,16 +1452,16 @@ def get_dynamic_field_schema(self, fields=None, recursive=True):
                 embedded documents
 
         Returns:
-            a dictionary mapping field paths to field types or lists of field
-            types
+            a dict mapping field paths to :class:`fiftyone.core.fields.Field`
+            instances or lists of them
         """
         return self._get_dynamic_field_schema(
             fields=fields, recursive=recursive
         )
 
     def get_dynamic_frame_field_schema(self, fields=None, recursive=True):
         """Returns a schema dictionary describing the dynamic fields of the
-        frames of the samples in the collection.
+        frames in the collection.
 
         Dynamic fields are embedded document fields with at least one non-None
         value that have not been declared on the dataset's schema.
@@ -1462,8 +1473,9 @@ def get_dynamic_frame_field_schema(self, fields=None, recursive=True):
                 embedded documents
 
         Returns:
-            a dictionary mapping field paths to field types or lists of field
-            types, or ``None`` if the collection does not contain videos
+            a dict mapping field paths to :class:`fiftyone.core.fields.Field`
+            instances or lists of them, or ``None`` if the collection does not
+            contain videos
         """
         if not self._has_frame_fields():
             return None