diff --git a/packages/core/python/itkwasm/docs/index.md b/packages/core/python/itkwasm/docs/index.md index 8c7396009..f0945829b 100644 --- a/packages/core/python/itkwasm/docs/index.md +++ b/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} diff --git a/packages/core/python/itkwasm/docs/introduction.md b/packages/core/python/itkwasm/docs/introduction.md index 39e028f61..5ad6f6913 100644 --- a/packages/core/python/itkwasm/docs/introduction.md +++ b/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) ``` ::: diff --git a/packages/core/python/itkwasm/docs/itk_python.md b/packages/core/python/itkwasm/docs/itk_python.md new file mode 100644 index 000000000..c5f735f63 --- /dev/null +++ b/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._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._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') +``` \ No newline at end of file diff --git a/packages/core/python/itkwasm/docs/numpy.md b/packages/core/python/itkwasm/docs/numpy.md new file mode 100644 index 000000000..e5aad0995 --- /dev/null +++ b/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) +``` \ No newline at end of file