feat: bring back out_dtype (#89)

* feat: bring back out_dtype

This addresses Philipp's comments in #6.
He wants to write the inital CCL volume to a uint32 to avoid
needing to upscale the image for the next step.

* docs: show how to use out_dtype

README.md

@@ -61,6 +61,12 @@ labels_out = cc3d.connected_components(labels_in) # 26-connected
 connectivity = 6 # only 4,8 (2D) and 26, 18, and 6 (3D) are allowed
 labels_out = cc3d.connected_components(labels_in, connectivity=connectivity)
 
+# If you need a particular dtype you can specify np.uint16, np.uint32, or np.uint64
+# You can go bigger, not smaller, than the default which is selected
+# to be the smallest that can be safely used. This can save you the copy
+# operation needed by labels_out.astype(...).
+labels_out = cc3d.connected_components(labels_in, out_dtype=np.uint64)
+
 # If you're working with continuously valued images like microscopy
 # images you can use cc3d to perform a very rough segmentation. 
 # If delta = 0, standard high speed processing. If delta > 0, then

automated_test.py

@@ -241,6 +241,31 @@ def test_3d_all_different(order, connectivity):
   assert np.unique(output_labels).shape[0] == 100*99*98
   assert output_labels.shape == (100, 99, 98)
 
+@pytest.mark.parametrize("out_dtype", (None, np.uint16, np.uint32, np.uint64))
+def test_out_dtype_empty(out_dtype):
+  labels = np.zeros((512,512,512), dtype=np.uint8)
+  out = cc3d.connected_components(labels, out_dtype=out_dtype)
+  if out_dtype is None:
+    assert out.dtype == np.uint16
+  else:
+    assert out.dtype == out_dtype
+
+def test_out_dtype_invalid():
+  labels = np.zeros((512,512,512), dtype=np.uint8)
+  try:
+    out = cc3d.connected_components(labels, out_dtype=np.uint8)
+    assert False
+  except ValueError:
+    pass
+
+def test_out_dtype_too_small():
+  labels = np.arange(0, 41 ** 3).astype(np.uint32) + 1
+  try:
+    out = cc3d.connected_components(labels, out_dtype=np.uint16)
+    assert False
+  except ValueError:
+    pass  
+
 @pytest.mark.parametrize("dtype", TEST_TYPES)
 def test_3d_cross(dtype):
   def test(order, ground_truth):