Add dicom converter

Author: hovnatan

docs/source/superannotate.sdk.rst

@@ -334,8 +334,17 @@ ________________________
 .. _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/tutorial.sdk.rst

@@ -415,3 +415,36 @@ Similarly aggregation of class attributes across multiple projects can be obtain
 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

setup.py

@@ -15,7 +15,7 @@
     Version = f.read()
 
 Version = Version.rstrip()
-Version = Version[11:-1]
+Version = Version[15:-1]
 
 setup(
     name='superannotate',

superannotate/__init__.py

@@ -63,7 +63,7 @@
     import_annotation_format
 )
 from .instance_filtering import filter_annotation_instances
-from .version import Version
+from .version import __version__
 
 formatter = logging.Formatter(fmt='SA-PYTHON-SDK - %(levelname)s - %(message)s')
 #formatter = logging.Formatter(fmt='%(asctime)s - %(levelname)s - %(module)s - %(message)s')
@@ -79,23 +79,23 @@
 def _check_version():
     _req = requests.get('https://pypi.python.org/pypi/superannotate/json')
     if _req.ok:
-        _Version = packaging.version.parse(Version)
+        _version = packaging.version.parse(__version__)
         _version_on_pip = packaging.version.parse('0')
         _j = _req.json()
         _releases = _j.get('releases', [])
         for _release in _releases:
             _ver = packaging.version.parse(_release)
             if not _ver.is_prerelease:
                 _version_on_pip = max(_version_on_pip, _ver)
-        if _version_on_pip.major > _Version.major:
+        if _version_on_pip.major > _version.major:
             logger.warning(
                 "There is a major upgrade of SuperAnnotate Python SDK available on PyPI. We recommend upgrading. Run 'pip install --upgrade superannotate' to upgrade from your version %s to %s.",
-                _Version, _version_on_pip
+                _version, _version_on_pip
             )
-        elif _version_on_pip > _Version:
+        elif _version_on_pip > _version:
             logger.info(
                 "There is a newer version of SuperAnnotate Python SDK available on PyPI. Run 'pip install --upgrade superannotate' to upgrade from your version %s to %s.",
-                _Version, _version_on_pip
+                _version, _version_on_pip
             )
 
 

superannotate/__main__.py

@@ -50,7 +50,7 @@ def main():
     elif command == "export-project":
         export_project(further_args)
     elif command == "version":
-        print(f"SuperAnnotate Python SDK version {sa.Version}")
+        print(f"SuperAnnotate Python SDK version {sa.__version__}")
     else:
         raise SABaseException(0, "Wrong command to superannotate CLI")
 

superannotate/api.py

@@ -8,7 +8,7 @@
 import urllib3
 
 from .exceptions import SABaseException
-from .version import Version
+from .version import __version__
 
 logger = logging.getLogger("superannotate-python-sdk")
 
@@ -48,26 +48,26 @@ def init(self, config_location=None):
             try:
                 self._token = self._api_config["token"]
             except KeyError:
-                logger.error(
-                    "'token' key is not present in the config file %s.",
-                    str(config_location)
+                raise SABaseException(
+                    0,
+                    "Incorrect config file: 'token' key is not present in the config file "
+                    + str(config_location)
                 )
-                raise SABaseException(0, "Incorrect config file.")
             try:
                 self.team_id = int(self._token.split("=")[1])
             except Exception:
-                logger.error(
-                    "token key is not valid in the config file %s.",
-                    str(config_location)
+                raise SABaseException(
+                    0,
+                    "Incorrect config file: 'token' key is not valid in the config file "
+                    + str(config_location)
                 )
-                raise SABaseException(0, "Incorrect config file.")
 
             self._default_headers = {'Authorization': self._token}
             self._default_headers["authtype"] = "sdk"
             if "authtype" in self._api_config:
                 self._default_headers["authtype"] = self._api_config["authtype"]
             self._default_headers['User-Agent'] = requests_toolbelt.user_agent(
-                'superannotate', Version
+                'superannotate', __version__
             )
 
             self._main_endpoint = "https://api.annotate.online"

superannotate/dicom_converter.py

@@ -15,26 +15,36 @@ def dicom_to_rgb_sequence(
     :type input_dicom_file: str or Pathlike
     :param output_dir: path to output directory
     :type output_dir: str or Pathlike
+    :param output_image_quality: output JPEG quality setting in percents
+    :type output_image_quality: int
+
+    :return: paths to output images
+    :rtype: list of strs
 
     """
+    input_dicom_file = Path(input_dicom_file)
     ds = pydicom.dcmread(str(input_dicom_file))
     # interp = ds.PhotometricInterpretation
     # print(interp)
 
-    input_dicom_file = Path(input_dicom_file)
-    output_dir = Path(output_dir)
     arr = ds.pixel_array
     if "NumberOfFrames" in ds:
         number_of_frames = ds.NumberOfFrames
     else:
         number_of_frames = 1
         arr = arr[np.newaxis, :]
     # print(arr.shape)
+    output_dir = Path(output_dir)
+    output_paths = []
     for i in range(number_of_frames):
         image = Image.fromarray(arr[i])
         image = image.convert("RGB")
+        path = output_dir / (input_dicom_file.stem + f"_{i:05}.jpg")
         image.save(
-            output_dir / (input_dicom_file.stem + f"_{i:05}.jpg"),
+            path,
             subsampling=0 if output_image_quality > 80 else 2,
             quality=output_image_quality
         )
+        output_paths.append(str(path))
+
+    return output_paths

superannotate/version.py

@@ -1 +1 @@
-Version = "2.1.1"
+__version__ = "2.1.2"

tests/test_dicom.py

@@ -4,6 +4,7 @@
 
 
 def test_dicom_convesion(tmpdir):
-    sa.dicom_to_rgb_sequence(
+    paths = sa.dicom_to_rgb_sequence(
         pydicom.data.get_testdata_file("CT_small.dcm"), tmpdir
     )
+    assert len(paths) == 1