Merge pull request #5 from AdaptiveParticles/add_guide

Add guide

.github/workflows/test_and_deploy.yml

@@ -21,26 +21,23 @@ jobs:
     name: ${{ matrix.platform }} py${{ matrix.python-version }}
     runs-on: ${{ matrix.platform }}
     strategy:
+      fail-fast: false
       matrix:
         platform: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.7', '3.8', '3.9', '3.10']
+        python-version: ['3.8', '3.9', '3.10', '3.11']
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
       # these libraries, along with pytest-xvfb (added in the `deps` in tox.ini),
       # enable testing on Qt on linux
       - name: Install Linux libraries
-        if: runner.os == 'Linux'
-        run: |
-          sudo apt-get install -y libdbus-1-3 libxkbcommon-x11-0 libxcb-icccm4 \
-            libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
-            libxcb-xinerama0 libxcb-xinput0 libxcb-xfixes0
+        uses: tlambert03/setup-qt-libs@v1
 
       # strategy borrowed from vispy for installing opengl libs on windows
       - name: Install Windows OpenGL
@@ -65,7 +62,7 @@ jobs:
           PLATFORM: ${{ matrix.platform }}
 
       - name: Coverage
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v3
 
   deploy:
     # this will run when you have tagged a commit, starting with "v*"

README.md

@@ -7,22 +7,48 @@
 [![codecov](https://codecov.io/gh/AdaptiveParticles/napari-apr-viewer/branch/main/graph/badge.svg)](https://codecov.io/gh/AdaptiveParticles/napari-apr-viewer)
 [![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-apr-viewer)](https://napari-hub.org/plugins/napari-apr-viewer)
 
-A simple plugin to view APR images in napari
+A simple plugin to create and view APR images in napari
+
+## Usage
+
+To get started, open an image of your choice (2D or 3D grayscale) in napari and open the `convert_image_to_apr` panel. Select the image layer to convert, an appropriate data type, and hit `Run`. 
+
+**Note:** choosing a data type smaller than the input type may lead to overflow and thus erroneous results.
+
+Conversion parameters can often be left to their default values, thanks to the automatic parameter tuning. For very noisy images, it is sometimes useful to increase the `smoothing` parameter. In order to get a more (or less) aggressive adaptation, change the `relative error` parameter.
+
+![conversion.png](https://github.com/AdaptiveParticles/napari-apr-viewer/raw/main/docs/conversion.png)
+
+To save the result to file, simply save the newly created layer using the `File` menu. We use the extension `.apr`, although the file is actually written in `hdf5` format (and can be opened/explored as such). In this example, the APR is roughly 80 times smaller than the original image on disk. APR files can be opened directly in napari, e.g. by drag and drop.
+
+![apr_file.png](https://github.com/AdaptiveParticles/napari-apr-viewer/raw/main/docs/apr_file.png)
+
+To better understand the workings of the APR on your data, you can use the `APR Viewer` panel to change the `View mode` for a selected APR layer to `level`. This shows you a visualization of the adaptive resolution. Particles in the brightest regions correspond exactly to pixels (lossless), while each shade darker corresponds to downsampling by a factor of 2 in each dimension.
+
+![view_level.png](https://github.com/AdaptiveParticles/napari-apr-viewer/raw/main/docs/view_level.png)
+
+The `Downsample` slider can be used to reduce the resolution of the displayed data for the selected layer. This can be used to explore large volumes in 3D, where rendering the full data requires too much memory. 
+
+**Note:** We do not offer APR-native rendering at this time, so this step will reconstruct the entire pixel volume (at the selected resolution). Thus, for large volumes, be sure to increase the downsampling before toggling the 3D viewer. 
+
+![view_3D.png](https://github.com/AdaptiveParticles/napari-apr-viewer/raw/main/docs/view_3D.png)
+
+![view_3D_ds.png](https://github.com/AdaptiveParticles/napari-apr-viewer/raw/main/docs/view_3D_downsampled.png)
+
+_The data shown in these examples was taken from the Platynereis-ISH-Nuclei-CBG dataset available [here](https://github.com/juglab/EmbedSeg/releases)._
+
+ 
 
 ----------------------------------
 
 This [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.
 
-
 ## Installation
 
 You can install `napari-apr-viewer` via [pip]:
 
     pip install napari-apr-viewer
 
-
-
-
 ## Contributing
 
 Contributions are very welcome. Tests can be run with [tox], please ensure
@@ -53,4 +79,4 @@ If you encounter any problems, please [file an issue] along with a detailed desc
 [pip]: https://pypi.org/project/pip/
 [PyPI]: https://pypi.org/
 
-[file an issue]: https://github.com/AdaptiveParticles/napari-apr-viewer/issues
+[file an issue]: https://github.com/AdaptiveParticles/napari-apr-viewer/issues

pyproject.toml

@@ -1,5 +1,6 @@
 [build-system]
-requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2"]
+requires = ["setuptools>=64", "setuptools_scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
 
 [tool.setuptools_scm]
-write_to = "src/napari_apr_viewer/_version.py"
+version_file = "src/napari_apr_viewer/_version.py"

setup.cfg

@@ -14,17 +14,17 @@ classifiers =
     Topic :: Software Development :: Testing
     Programming Language :: Python
     Programming Language :: Python :: 3
-    Programming Language :: Python :: 3.7
     Programming Language :: Python :: 3.8
     Programming Language :: Python :: 3.9
     Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
     Operating System :: OS Independent
     License :: OSI Approved :: Apache Software License
 
 
 [options]
 packages = find:
-python_requires = >=3.7
+python_requires = >=3.8
 package_dir =
     =src
 

src/napari_apr_viewer/_APRViewer.py

@@ -74,7 +74,7 @@ def _changeMode(self, mode: [int, str]):
                 # set data type
                 if mode == 'level':
                     layer.data.dtype = np.uint8
-                    layer.contrast_limits = [0, layer.data.apr.level_max()]
+                    layer.contrast_limits = [0, layer.data.apr.level_max() + 1]
                 else:
                     layer.data.dtype = pyapr.utils.particles_to_type(layer.data.parts)
                     if old_mode == 'level':

src/napari_apr_viewer/_convert_image_to_apr.py

@@ -35,12 +35,12 @@ class DTypes(Enum):
                                                               'are ignored in this process.'},
                output_name={'tooltip': 'Name of the resulting napari image layer.'})
 def convert_image_to_apr(
-        layer: "napari.types.ImageData",
+        image: "napari.types.ImageData",
         data_type: DTypes,
         relative_error: float = 0.1,
-        voxel_size_dim0: float = 1.0,
-        voxel_size_dim1: float = 1.0,
-        voxel_size_dim2: float = 1.0,
+        voxel_size_z: float = 1.0,
+        voxel_size_y: float = 1.0,
+        voxel_size_x: float = 1.0,
         smoothing: float = 1.0,
         intensity_threshold: float = 0.0,
         sigma_threshold: float = 0.0,
@@ -52,18 +52,18 @@ def convert_image_to_apr(
     Convert a pixel image in a given layer to an APR.
     """
     par = pyapr.APRParameters()
-    par.dz = voxel_size_dim0
-    par.dx = voxel_size_dim1
-    par.dy = voxel_size_dim2
+    par.dz = voxel_size_z
+    par.dx = voxel_size_y
+    par.dy = voxel_size_x
     par.gradient_smoothing = smoothing
     par.Ip_th = intensity_threshold
     par.rel_error = relative_error
     par.sigma_th = sigma_threshold
     par.grad_th = grad_threshold
     par.auto_parameters = auto_find_sigma_and_grad_threshold
 
-    layer = layer.astype(data_type.value)
-    apr, parts = pyapr.converter.get_apr(layer, params=par, verbose=True)
+    image = image.astype(data_type.value)
+    apr, parts = pyapr.converter.get_apr(image, params=par, verbose=True)
 
     ldata = pyapr.reconstruction.APRSlicer(apr, parts)
     meta = {'name': output_name,

tox.ini

@@ -1,13 +1,13 @@
 # For more information about tox, see https://tox.readthedocs.io/en/latest/
 [tox]
-envlist = py{37,38,39,310}-{linux,macos,windows}
+envlist = py{38,39,310,311}-{linux,macos,windows}
 
 [gh-actions]
 python =
-    3.7: py37
     3.8: py38
     3.9: py39
     3.10: py310
+    3.11: py311
 
 [gh-actions:env]
 PLATFORM =
@@ -23,13 +23,14 @@ platform =
 passenv = 
     CI
     GITHUB_ACTIONS
-    DISPLAY XAUTHORITY
+    DISPLAY 
+    XAUTHORITY
     NUMPY_EXPERIMENTAL_ARRAY_FUNCTION
     PYVISTA_OFF_SCREEN
 deps = 
     pytest  # https://docs.pytest.org/en/latest/contents.html
     pytest-cov  # https://pytest-cov.readthedocs.io/en/latest/
-    pytest-xvfb ; sys_platform == 'linux'
+    pytest-xvfb #; sys_platform == 'linux'
     # you can remove these if you don't use them
     pyapr>=1.0.0rc1
     numpy