Merge pull request #817 from thewtex/itkwasm-python-docs

Itkwasm python docs

packages/core/python/itkwasm/docs/index.md

@@ -32,6 +32,8 @@ This site provides the Python documentation. There is also [C++ and JavaScript/T
 ```{toctree}
 :hidden:
 introduction.md
+numpy.md
+itk_python.md
 ```
 
 ```{toctree}

packages/core/python/itkwasm/docs/introduction.md

@@ -63,7 +63,7 @@ compressed = compress_stringify(data)
 from itkwasm_compress_stringify import compress_stringify_async
 
 data = bytes([33,44,55])
-compressed = await compress_stringify(data)
+compressed = await compress_stringify_async(data)
 ```
 :::
 

packages/core/python/itkwasm/docs/itk_python.md

@@ -0,0 +1,64 @@
+# ITK Python interop
+
+`itkwasm` can be used with native [`itk` Python bindings](https://itkpythonpackage.readthedocs.io/en/master/Quick_start_guide.html).
+
+Both packages support common Python dictionary representations of the data structures used on interfaces. The non-dictionary types are more convenient to work with directly and provide strong typing for function calls.
+
+## Convert from `itkwasm` to `itk`
+
+To convert from an `itkwasm` dataclass interface type to a native `itk` Python type, first convert the `itkwasm` type to a dictionary, then use the `itk.<type>_from_dict` function. Example:
+
+```python
+from itkwasm import Image
+from dataclasses import asdict
+itkwasm_image = Image()
+image_dict = asdict(itkwasm_image)
+
+import itk
+itk_image = itk.image_from_dict(image_dict)
+```
+
+## Convert from `itk` to `itkwasm`
+
+To convert from a native `itk` Python type to an `itkwasm` dataclass interface type, first convert the `itkwasm` type to a dictionary the `itk.<type>_from_dict`, then pass the dictionary as keyword arguments to `itkwasm` constructor with the `**` operator. Example:
+
+
+```python
+import itk
+# Create an itk.Image
+itk_image = itk.Image.New()
+itk_image.SetRegions([8,8])
+itk_image.Allocate()
+image_dict = itk.dict_from_image(itk_image)
+
+from itkwasm import Image
+itkwasm_image = Image(**image_dict)
+```
+
+## itkwasm file formats
+
+`itkwasm` provides file formats corresponding to its interface types. These file formats keep wasm module sizes tiny, enable efficient and one-to-one serialization, assist with debugging, and bridge with [Web3 technologies](https://en.wikipedia.org/wiki/Web3).
+
+The file extensions for these formats are `.iwi` and `.iwm` for images and mesh-like data, respectively. When written, these will output directories with an `index.json` file and raw binary files. When `.iwi.cbor` or `.iwm.cbor` extensions are used, a single [CBOR](https://en.wikipedia.org/wiki/CBOR) file is created.
+
+These file formats can also be used with native ITK Python.
+
+Install the binary Python package:
+
+```shell
+pip install itk-webassemblyinterface
+```
+
+Then use with `itk.imread`, `itk.imwrite`, `itk.meshread`, `itk.meshwrite`. Example:
+
+```python
+import itk
+
+image = itk.imread('cthead1.png')
+itk.imwrite(image, 'cthead1.iwi')
+itk.imwrite(image, 'cthead1.iwi.cbor')
+
+mesh = itk.meshread('cow.vtk')
+itk.meshwrite(mesh, 'cow.iwm')
+itk.meshwrite(mesh, 'cow.iwm.cbor')
+```

packages/core/python/itkwasm/docs/numpy.md

@@ -0,0 +1,26 @@
+# Python, NumPy interop
+
+`itkwasm` interface types, used in function calls, are standard [Python `dataclasses`](https://docs.python.org/3/library/dataclasses.html). These interface types are composed of standard Python datatypes, `dict`, `list`, `float`, `int`, and [NumPy](https://numpy.org/) arrays.
+
+## Convert from `itkwasm` to `dict`
+
+To convert from an `itkwasm` dataclass interface type to a Python dictionary, use [`asdict`](https://docs.python.org/3/library/dataclasses.html#dataclasses.asdict) from the Python standard library.
+
+An example with [`itkwasm.Image`](#itkwasm.image.Image):
+
+```python
+from itkwasm import Image
+image = Image()
+
+from dataclasses import asdict
+image_dict = asdict(image)
+```
+
+## Convert from `dict` to `itkwasm`
+
+To convert back to an `itkwasm` interface type, use the `**` Python operator to expand the dictionary into keyword arguments for the dataclass constructor.
+
+```python
+from itkwasm import Image
+image = Image(**image_dict)
+```