Merge pull request #47 from lucas-diedrich/faq

[Docs] FAQ

docs/faq.md

@@ -0,0 +1,78 @@
+# FAQ
+
+## Current scope of the package
+
+Please raise an [issue](https://github.com/lucas-diedrich/dvp-io/issues) to request support for additonal data formats.
+
+### Images (Tested)
+
+| Type  |                                        | Function         | Supported channels | Wrapped library                    |
+| ----- | -------------------------------------- | ---------------- | ------------------ | ---------------------------------- |
+| .czi  | Fluorescence Microscopy Single-Channel | `read_czi`       | Grayscale          | pylibczirw                         |
+| .czi  | Fluorescence Microscopy Multi-channel  | `read_czi`       | Grayscale          | pylibczirw                         |
+| .czi  | Whole Slide Image                      | `read_czi`       | RGB(A)             | pylibczirw                         |
+| .mrxs | Whole Slide Images                     | `read_openslide` | RGB(A)             | openslide                          |
+| .tiff | -                                      | `read_custom`    | grayscale          | dask.array.image/skimage.io.imread |
+
+### Images (supported, in principle)
+
+| Type  |                             | Function         | Supported channels | Wrapped library                    |
+| ----- | --------------------------- | ---------------- | ------------------ | ---------------------------------- |
+| .svs  | Whole Slide Images (Aperio) | `read_openslide` | RGB(A)             | openslide                          |
+| .dcm  | Whole Slide Images (DICOM)  | `read_openslide` | RGB(A)             | openslide                          |
+| .ndpi | Hamamatsu                   | `read_openslide` | RGB(A)             | openslide                          |
+| .svs  | Whole Slide Images          | `read_openslide` | RGB(A)             | openslide                          |
+| .jpeg | -                           | `read_custom`    | RGB(A), grayscale  | dask.array.image/skimage.io.imread |
+| .png  | -                           | `read_custom`    | RGB(A), grayscale  | dask.array.image/skimage.io.imread |
+| .tiff | -                           | `read_custom`    | RGB(A)             | dask.array.image/skimage.io.imread |
+
+### Shapes
+
+| Type |     | Function                     | Wrapped library |
+| ---- | --- | ---------------------------- | --------------- |
+| .xml | LMD | `dvpio.read.shapes.read_lmd` | py-lmd          |
+
+## How to...
+
+### ... open spatialdata in Napari?
+
+This requires you to have `napari_spatialdata` installed in the respective environment
+In a **jupyter notebook**, you can use the following snippet:
+
+```python
+import spatialdata
+from napari_spatialdata import Interactive
+
+sdata = spatialdata.read_zarr("/path/to/sdata.zarr")
+session = Interactive(sdata)
+session.run()
+```
+
+You can also **import it directly from the napari viewer**.
+Open the napari viewer, e.g. from the commandline.
+
+```bash
+> conda activate <my_env>
+> napari
+```
+
+In napari, go to `File > Open Directory` (or use the shortcut `Cmd+Shift+O`) and go to the storage location of your spatialdata object. Select the `napari spatialdata` reader in the pop up menu.
+
+## Known Issues
+
+Please raise an [issue](https://github.com/lucas-diedrich/dvp-io/issues) to report bugs.
+
+### Import of `napari-spatialdata` fails
+
+Importing `napari_spatialdata` might initially fail due to missing non-python dependencies. If you get the following error:
+
+```python
+import napari_spatialdata
+> qtpy.PythonQtError: No Qt bindings could be found
+```
+
+Try to install the `pyqt5-tools` binaries in your environment
+
+```bash
+pip install pyqt5-tools
+```

docs/index.md

@@ -8,6 +8,7 @@
 
 api.md
 tutorials.md
+faq.md
 changelog.md
 contributing.md
 references.md

docs/tutorials/002_read-dvpio.ipynb

@@ -728,7 +728,7 @@
     "\n",
     "1. Create a new `points` layer in the napari viewer. \n",
     "2. *Recommended*: Rename the layer to a more expressive name, e.g. `calibration_points_image`\n",
-    "3. Select the 3 calibration points. **Currently, you have to pick them in the correct order. 1. bottom left, 2. top left, 3. top right**\n",
+    "3. Select the 3 calibration points. **Currently, you have to pick them in the correct order, as they are defined in the lmd/.xml file.** (Here: _1. bottom left, 2. top left, 3. top right_)\n",
     "4. Save the layer by clicking `Shift+E`\n",
     "5. Leave the napari viewer.\n",
     "\n",