Merge branch 'master' of https://github.com/superannotateai/superannotate-python-sdk

Author: agyurjin

Makefile

@@ -10,11 +10,11 @@ all: coverage tests
 	$(PYTHON) setup.py build_ext --inplace
 
 tests:
-	$(PYTESTS)
+	$(PYTESTS) -n 8
 
 stress-tests: AO_TEST_LEVEL=stress
 stress-tests: tests
-	$(PYTESTS)
+	$(PYTESTS) -n 8
 
 clean:
 	rm -rf superannotate.egg-info

docs/source/attribute_distribution.png

@@ -318,8 +318,8 @@ _____________________________________________________________
 
 ----------
 
-Editing annotations
-____________________
+Working with annotations
+________________________
 
 .. _ref_add_annotation_bbox_to_json:
 .. autofunction:: superannotate.add_annotation_bbox_to_json
@@ -329,9 +329,22 @@ ____________________
 .. autofunction:: superannotate.add_annotation_ellipse_to_json
 .. autofunction:: superannotate.add_annotation_template_to_json
 .. autofunction:: superannotate.add_annotation_cuboid_to_json
+.. autofunction:: superannotate.aggregate_annotations_as_df
+.. autofunction:: superannotate.df_to_annotations
+.. _ref_filter_annotation_instances:
+.. autofunction:: superannotate.filter_annotation_instances
+
+----------
 
 Aggregating class distribution from annotations
 _____________________________________________________________
 
 .. autofunction:: superannotate.class_distribution
-.. autofunction:: superannotate.attribute_distribution
+.. autofunction:: superannotate.attribute_distribution
+
+----------
+
+Utility functions
+--------------------------------
+
+.. autofunction:: superannotate.dicom_to_rgb_sequence

docs/source/class_distribution.png

@@ -342,25 +342,109 @@ project with the found contributor as an QA:
 
    sa.share_project(project, "hovnatan@superannotate.com", user_role="QA")
 
+
+
+----------
+
+
+pandas DataFrame out of project annotations and annotation instance filtering
+_____________________________________________________________________________
+
+
+To create a `pandas DataFrame <https://pandas.pydata.org/>`_ from project
+SuperAnnotate format annotations:
+
+.. code-block:: python
+
+   df = sa.aggregate_annotations_as_df("<path_to_project_folder>")
+
+The created DataFrame will have columns :code:`imageName`, :code:`instanceId`,
+:code:`className`, :code:`attributeGroupName`, :code:`attributeName`, :code:`type`, :code:`error`, :code:`locked`, :code:`visible`, :code:`trackingId`, :code:`probability`, :code:`pointLabels`, :code:`meta` (geometry information as string), :code:`commentResolved`, :code:`classColor`, :code:`groupId`.
+
+Example of created DataFrame:
+
+.. image:: pandas_df.png
+
+Each row represents annotation information. One full annotation with multiple
+attribute groups can be grouped under :code:`instanceId` field.
+
+A helper function :ref:`filter_annotation_instances <ref_filter_annotation_instances>` to annotation instances by their class or attribute from the DataFrame is available. E.g., to get annotations that have annotation class :code:`Human` and attribute  :code:`"height" : "tall"`  that are **not** of type :code:`polygon`:
+
+.. code-block:: python
+
+   filtered_df = sa.filter_annotation_instances(df, include=[{"className" : "Human",
+                                                              "attributes" : [{"groupName" : "height",
+                                                                              "name" : "tall"}]
+                                                            }],
+                                                    exclude=[{"type" : "polygon"}])
+
+To transform back pandas DataFrame annotations to SuperAnnotate format annotation:
+
+.. code-block:: python
+
+   sa.df_to_annotations(filtered_df, "<path_to_output_folder>")
+
+
+----------
+
+
 Aggregating class distribution across multiple projects
-______________________________
+_______________________________________________________
 
 After exporting annotations from multiple projects, it is possible to aggregate class distribution of annotated instances as follows
 
 .. code-block:: python
 
    df = sa.class_distribution("<path_to_export_folder>", [project_names])
 
-Aggregated distribution is returned as pandas dataframe with columns class_name and count. Enabling visualize flag plots histogram of obtained distribution.
+Aggregated distribution is returned as pandas dataframe with columns className and count. Enabling visualize flag plots histogram of obtained distribution.
 
 .. code-block:: python
 
    df = sa.class_distribution("<path_to_export_folder>", [project_names], visualize = True)
 
+.. image:: class_distribution.png
+
+
 Similarly aggregation of class attributes across multiple projects can be obtained with
 
 .. code-block:: python
 
    df = sa.attribute_distribution("<path_to_export_folder>", [project_names], visualize = True)
 
-Here pandas dataframe with columns identifying attribute and corresponding instance count is returned. Within visualized histogram attributes of the same class are grouped by color and sorted accordingly.
+Here pandas DataFrame with columns identifying attribute and corresponding instance count is returned. Within visualized histogram attributes of the same class are grouped by color and sorted accordingly.
+
+.. image:: attribute_distribution.png
+
+----------
+
+
+Working with DICOM files
+_______________________________________________________
+
+
+To convert DICOM file images to JPEG images:
+
+
+.. code-block:: python
+
+   df = sa.dicom_to_rgb_sequence("<path_to_dicom_file>", "<path_to_output_dir>")
+
+JPEG images with names :file:`<dicom_file_name>_<frame_num>.jpg` will be created
+in :file:`<path_to_output_dir>`. Those JPEG images can be uploaded to
+SuperAnnotate platform using the regular:
+
+.. code-block:: python
+
+   sa.upload_images_from_folder_to_project(project, "<path_to_output_dir>")
+
+Some DICOM files can have image frames that are compressed. To load them, `GDCM :
+Grassroots DICOM library <http://gdcm.sourceforge.net/wiki/index.php/Main_Page>`_ needs to be installed:
+
+.. code-block:: bash
+
+   # using conda
+   conda install -c conda-forge gdcm
+
+   # or on Ubuntu with versions above 19.04
+   sudo apt install python3-gdcm

docs/source/pandas_df.png

@@ -1,3 +1,4 @@
+pydicom>=2.0.0
 boto3>=1.14.53
 requests>=2.23.0
 requests-toolbelt>=0.9.1