塗りつぶし画像を読み書きする関数を作成しました (#588)

* 関数の作成

* update document

* update settings

.devcontainer/devcontainer.json

@@ -31,15 +31,19 @@
 		"CONTAINER_WORKSPACE": "${containerWorkspaceFolder}",
 		"LOCAL_WORKSPACE": "${localWorkspaceFolder}"
 	},
-	"postStartCommand": "poetry install",
-	"extensions": [
-		"mosapride.zenkaku",
-		"ms-python.python",
-		"ms-python.vscode-pylance",
-		"streetsidesoftware.code-spell-checker",
-		"bungcip.better-toml",
-		"njpwerner.autodocstring",
-		"dawhite.mustache",
-		"lextudio.restructuredtext"
-	]
+	"postStartCommand": "poetry install --all-extras",
+	"customizations":{
+		"vscode":{
+			"extensions": [
+				"mosapride.zenkaku",
+				"ms-python.python",
+				"ms-python.vscode-pylance",
+				"streetsidesoftware.code-spell-checker",
+				"bungcip.better-toml",
+				"njpwerner.autodocstring",
+				"dawhite.mustache",
+				"lextudio.restructuredtext"
+			]
+		}
+	}
 }

.travis.yml

@@ -10,7 +10,7 @@ python:
 install:
   - pip install pip --upgrade
   - pip install "poetry<1.5"
-  - travis_retry poetry install --only main,linter,test
+  - travis_retry poetry install --only main,linter,test --all-extras
 
 script:
    - make lint

.vscode/cspell.json

@@ -23,9 +23,12 @@
         "clazz",
         "csvfile",
         "dateutil",
+        "dtype",
         "favicon",
+        "fromarray",
         "giveup",
         "kurusugawa",
+        "ndarray",
         "netrc",
         "pydata",
         "pylint",

README.md

@@ -202,6 +202,15 @@ print(simple_annotation)
 
 ```
 
+### 塗りつぶし画像の読み込み
+`annofabapi.segmentation` には、アノテーションZIPに格納されている塗りつぶし画像を扱うための関数が用意されています。
+利用する場合は、以下のコマンドを実行してください。
+
+```
+$ pip install annofabapi[segmentation]
+```
+
+
 
 ## DataClass
 `annofabapi.dataclass`に、データ構造用のクラスがあります。
@@ -218,6 +227,8 @@ print(task.status)
 ```
 
 
+
+
 ## 備考
 
 ### `annofabapi`のログを出力する方法（サンプル）

annofabapi/segmentation.py

@@ -0,0 +1,36 @@
+import numpy
+import numpy.typing as npt
+from PIL import Image
+
+
+def read_binary_image(fp) -> numpy.ndarray:
+    """
+    アノテーションZIP(ディレクトリ)に格納されている塗りつぶし画像を読み込みます。
+
+    Args:
+        fp: A filename (string), pathlib.Path object or file object.
+
+    Returns:
+        numpyの2次元配列。`dtype`はbool。
+        各要素の値は、塗られている部分([255,255,255,255])はTrue, 塗られていない部分([0,0,0,0])はFalseです。
+    """
+    image = Image.open(fp, formats=("PNG",)).convert("1")
+    return numpy.array(image, dtype=bool)
+
+
+def write_binary_image(array: npt.ArrayLike, fp) -> None:
+    """
+    booleanの2次元配列から、Annofab用の塗りつぶし画像を書き出します。
+
+    Args:
+        array: 2次元配列。各要素はboolean。
+            Trueは[255,255,255,255], Falseは[0,0,0,0]で塗りつぶされます。
+        fp: A filename (string), pathlib.Path object or file object.
+
+    """
+    mask_array = numpy.array(array, dtype=bool)
+    height, width = mask_array.shape
+    channel = 4  # RGBAの4チャンネル
+    data = numpy.zeros((height, width, channel), dtype=numpy.uint8)
+    data[mask_array] = [255, 255, 255, 255]
+    Image.fromarray(data, mode="RGBA").save(fp, format="PNG")

docs/user_guide/advanced_usage.rst

@@ -224,9 +224,9 @@ JSONファイルの中身については、https://annofab.com/docs/api/#tag/x-a
 
 
 
-塗りつぶし画像を読み込む
+塗りつぶし画像を開く
 --------------------------------------------------
-``SimpleAnnotationParser.open_outer_file()`` メソッドを実行すると、塗りつぶし画像を読み込みます。
+``SimpleAnnotationParser.open_outer_file()`` メソッドを実行すると、塗りつぶし画像ファイルを開きます。
 
 .. code-block:: python
 
@@ -236,12 +236,11 @@ JSONファイルの中身については、https://annofab.com/docs/api/#tag/x-a
     # 塗りつぶし画像の相対パス
     data_uri = detail.data["data_uri"]
 
-    # 塗りつぶし画像を読み込む
+    # 塗りつぶし画像を開く
     with parser.open_outer_file(data_uri) as f:
         pass
 
 
-
 アノテーションzip内のすべてのJSONを読み込む
 --------------------------------------------------
 
@@ -346,3 +345,33 @@ JSONファイルの中身については、https://annofab.com/docs/api/#tag/x-a
         print("タスクは未完了状態")
 
 
+
+
+
+``annofabapi.segmentation``
+=============================================
+
+``annofabapi.segmentation`` には、アノテーションZIPに格納されている塗りつぶし画像を扱うための関数が用意されています。
+
+このモジュールは ``numpy`` , ``pillow`` に依存しています。
+利用する場合は、以下のコマンドを実行してください。
+
+.. code-block::
+    
+    $ pip install annofabapi[segmentation]
+
+
+``read_binary_image`` 関数は、塗られている部分がTrue、塗られていない部分がFalseである2次元配列(numpy.ndarray)を返します。
+
+
+.. code-block:: python
+
+    from annofabapi.segmentation import read_binary_image
+
+    # 塗りつぶし画像を読み込む
+    with parser.open_outer_file(data_uri) as f:
+        segmentation_data = read_binary_image(f)
+        print(segmentation_data)
+        # array([[ True, False, ....],
+        
+