Merge pull request #88 from imcf/devel

Final changes for the `imcflibs-1.5.0` release

Author: ehrenfeu

.github/workflows/build.yml

@@ -1,4 +1,4 @@
-name: 🚚🌍 Publish to 🔬☕ SciJava and 🎪 PyPI
+name: "Packages: SciJava 🔬☕ + PyPI 🎪"
 
 on:
 

.github/workflows/dispatch-deploy-pages.yml

@@ -1,4 +1,4 @@
-name: 🚀 Dispatch foreign workflows
+name: Dispatch foreign workflows 🚀🌖
 
 on:
   workflow_dispatch:

.github/workflows/lint.yml

@@ -1,4 +1,4 @@
-name: 🔎 Code Linting ⚡
+name: Code Linting 🔎⚡
 
 on:
   push:

.github/workflows/pytest-poetry.yml

@@ -1,19 +1,18 @@
 ## action file inspired by https://jacobian.org/til/github-actions-poetry/
 
-name: 🧪 pytest (via 🎭 Poetry)
+name: Pytest-Poetry 🧪🎭
 
 on:
+  workflow_dispatch:
   push:
     branches:
-    - master
+      - master
     tags:
-      - run-pytest*
-      - py3-pytest*
       - "*-[0-9]+.*"
   pull_request:
     branches:
-    - master
-    - devel
+      - master
+      - devel
 
 jobs:
   pytest-poetry:

.github/workflows/pytest-python2.yml

@@ -1,17 +1,16 @@
-name: 🧪 pytest (using 🐍 Python2)
+name: Pytest-Python2 🧪🐍
 
 on:
+  workflow_dispatch:
   push:
     branches:
-    - master
+      - master
     tags:
-      - run-pytest*
-      - py2-pytest*
       - "*-[0-9]+.*"
   pull_request:
     branches:
-    - master
-    - devel
+      - master
+      - devel
 
 env:
     PY_VERSION: 2.7.18

.gitignore

@@ -1,6 +1,5 @@
 # VS Code files
 *.code-workspace
-.vscode/
 
 # maven / release generated files
 target/
@@ -9,7 +8,6 @@ pom.xml.releaseBackup
 # bytecode created when importing directly in Jython:
 *py.class
 
-
 *.py[cod]
 
 # C extensions

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+    "markdownlint.config": {
+        "emphasis-style": {
+            "style": "asterisk"
+        },
+        "line-length": {
+            "line_length": 80,
+            "stern": true,
+            "code_blocks": false,
+            "tables": false
+        }
+    },
+}

.vscode/tasks.json

@@ -0,0 +1,27 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "verify",
+            "type": "shell",
+            "command": "mvn -B verify",
+            "group": "build"
+        },
+        {
+            "label": "test",
+            "type": "shell",
+            "command": "mvn -B test",
+            "group": "test"
+        },
+        {
+            "label": "deploy",
+            "type": "shell",
+            "command": "mvn -Dscijava.app.directory=/opt/Fiji.app",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "problemMatcher": []
+        }
+    ]
+}

CHANGELOG.md

@@ -1,5 +1,4 @@
 <!-- markdownlint-disable MD024 (no-duplicate-header) -->
-<!-- markdownlint-configure-file { "emphasis-style": { "style": "asterisk" } } -->
 
 # Changelog 🧾
 

DEVELOPMENT.md

@@ -31,7 +31,7 @@ git push origin $RELEASE_TAG
 ```
 
 **IMPORTANT 2**: in case a **pre-releaes** was created, the last commit needs to
-be discarded as the _release-script_ places a wrong version / snapshot
+be discarded as the *release-script* places a wrong version / snapshot
 combination in the `pom.xml`:
 
 ```bash
@@ -43,7 +43,7 @@ git reset --hard HEAD~1
 Building and deploying the package can be greatly simplified using "tasks" in
 [Visual Studio Code][www_vscode]. By adding the following settings to the
 `.vscode/tasks.json` file, you can simply press `Ctrl+Shift+B` in VS Code and
-select the _deploy_ task for running Maven and have the resulting JAR file being
+select the *deploy* task for running Maven and have the resulting JAR file being
 placed in `/opt/fiji-packaging/Fiji.app/jars/` (adjust to your path as
 necessary):
 
@@ -80,7 +80,7 @@ necessary):
 ## Linting Python 2.7 with VS Code
 
 For being able to lint the old Python code properly, you'll need to set up an
-appropriate _virtualenv_ with `pylint` being installed.
+appropriate *virtualenv* with `pylint` being installed.
 
 Using [`fish`][www_fish] and [virtualfish][www_vf], this can be done as follows:
 

README.md

@@ -1,8 +1,12 @@
 
 # IMCFlibs 🐍 ☕ 🔩 🔧 🪛
 
-[![Build Status](https://github.com/imcf/python-imcflibs/actions/workflows/build.yml/badge.svg)][build]
 [![Linting ⚡](https://github.com/imcf/python-imcflibs/actions/workflows/lint.yml/badge.svg)](https://github.com/imcf/python-imcflibs/actions/workflows/lint.yml)
+[![Pytest-Python2 🧪🐍](https://github.com/imcf/python-imcflibs/actions/workflows/pytest-python2.yml/badge.svg)](https://github.com/imcf/python-imcflibs/actions/workflows/pytest-python2.yml)
+[![Pytest-Poetry 🧪🎭](https://github.com/imcf/python-imcflibs/actions/workflows/pytest-poetry.yml/badge.svg)](https://github.com/imcf/python-imcflibs/actions/workflows/pytest-poetry.yml)
+[![codecov](https://codecov.io/github/imcf/python-imcflibs/branch/devel/graph/badge.svg?token=JTDK74OT79)](https://codecov.io/github/imcf/python-imcflibs)
+
+[![Build Status](https://github.com/imcf/python-imcflibs/actions/workflows/build.yml/badge.svg)][build]
 [![DOI](https://zenodo.org/badge/156891364.svg)][doi]
 
 This package contains a diverse collection of Python functions dealing with

TESTING.md

@@ -7,7 +7,7 @@ be tested via [`pytest`][pytest] up to a certain level, some (most?) of them
 should even work in a Python 3 environment.
 
 To perform those tests, the packges otherwise provided by ImageJ need to be
-mocked using the `imcf-fiji-mocks` package. For seting up a _venv_ use the steps
+mocked using the `imcf-fiji-mocks` package. For seting up a *venv* use the steps
 described here:
 
 ```bash
@@ -37,7 +37,7 @@ pip install --upgrade \
 pip install -e .
 ```
 
-Using this _venv_, tests can be triggered just the usual way. To run only
+Using this *venv*, tests can be triggered just the usual way. To run only
 specific tests, use e.g.
 
 ```bash
@@ -48,12 +48,12 @@ pytest tests/bdv/test_processingoptions.py
 
 For running [`pytest`][pytest] in a C-Python 2 environment, things are slightly
 more complicated than the approach described for Python 3 above as `pip` for
-Python 2 cannot install a project in _editable_ mode unless it has a `setup.py`
+Python 2 cannot install a project in *editable* mode unless it has a `setup.py`
 file (which we don't have and don't want).
 
 Therefore, a wheel needs to be built (e.g. using [`poetry`][poetry]) and
 installed (every time) into the corresponding virtualenv when performing the
-tests. Assuming you're having a working _poetry_ setup on your machine, you can
+tests. Assuming you're having a working *poetry* setup on your machine, you can
 simply use the provided `scripts/py2-pytest.sh` wrapper that will create the
 virtualenv, build and install the `imcflibs` wheel and launch `pytest` with the
 parameters specified, e.g.
@@ -68,35 +68,35 @@ Unfortunately there is nothing like `pytest` available for the parts that are
 running exclusively in a ImageJ2 / Fiji context. So in order to provide at least
 some basic, semi-interactive tests the following conventions are being used:
 
-* Each _**function**_ in any of the `imcflibs.imagej` submodules should have its
+* Each ***function*** in any of the `imcflibs.imagej` submodules should have its
   own directory underneath `/tests/interactive-imagej/`, using their fully
   qualified name as the path (only skipping the `imcflibs.` prefix). For example
   test scripts for `imcflibs.imagej.bioformats.import_image()` will be placed in
   the directory `/tests/interactive-imagej/bioformats/import_image/`.
 * The scripts inside those directories are intended to be run interactively /
   manually in a (freshly started) Fiji instance. Yes, really. Any other
   suggestions are highly welcome!
-* To facilitate this, a collection of _test images_ (and possibly other input
+* To facilitate this, a collection of *test images* (and possibly other input
   data) should be cloned to the local file system. Currently this `sample-data`
-  repository is _NOT_ publicly available due to legal ⚖ uncertainties. A repo
+  repository is *NOT* publicly available due to legal ⚖ uncertainties. A repo
   containing test data 🗞 that can be published should be assembled over time
   though!
-* Any _interactive_ test script should start with a header similar to the one
-  described below. Paths to input data _inside_ the test scripts **has** to be
+* Any *interactive* test script should start with a header similar to the one
+  described below. Paths to input data *inside* the test scripts **has** to be
   relative to the location of the `sample-data` repository mentioned above. This
   will allow for a fairly okayish testing workflow like this:
   * Make your changes in VS Code, then trigger a build by pressing `Shift` +
-  `Ctrl` + `B`. If things are configured as described in the _DEVELOPMENT_
+  `Ctrl` + `B`. If things are configured as described in the *DEVELOPMENT*
   document, the resulting `.jar` file will be automatically placed in Fiji's
   `jars/` folder.
   * Next, start a fresh instance of the Fiji that received the newly built JAR.
   * After Fiji has started, simply drag and drop the desired test script onto
-    the main window. This will open the _Script Editor_, then press `Ctrl` + `R`
+    the main window. This will open the *Script Editor*, then press `Ctrl` + `R`
     to launch the script.
   * Only on the first run on the machine being used you will have to select the
     base location of the `sample-data` repository.
-  * All subsequent runs of _**any**_ test script using the defined _Script
-    Parameter_ `IMCF_TESTDATA` will remember this selection, so it will be
+  * All subsequent runs of ***any*** test script using the defined *Script
+    Parameter* `IMCF_TESTDATA` will remember this selection, so it will be
     sufficient to just confirm the dialog by pressing `Enter`.
 
 ### Quick Workflow Summary

poetry.lock.md

@@ -3,8 +3,7 @@ authors = [
   "Niko Ehrenfeuchter <[email protected]>",
   "Laurent Guerard <[email protected]>",
   "Kai Schleicher <[email protected]>",
-  "Sébastien Herbert <[email protected]>",
-  "Rohan Girish <[email protected]>",
+  "Rohan Girish <[email protected]>",
 ]
 description = "Mostly ImageJ/Fiji-related Python helper functions."
 documentation = "https://imcf.one/apidocs/imcflibs/imcflibs.html"
@@ -41,22 +40,17 @@ exclude = [
 ]
 
 select = [
-    "D",
-    # summary lines have to be placed on the first physical line of the docstring
-    "D212",
-    # imperative mood for all docstrings
-    "D401",
-    # summary line has to end in a punctuation mark
-    "D415",
-    # require documentation for _all_ function parameters
-    "D417",
+    "D",     # enable "pydocstyle" rules
+    "D212",  # summary lines must be on the first physical line of the docstring
+    "D401",  # imperative mood for all docstrings
+    "D415",  # summary line has to end in a punctuation mark
+    "D417",  # require documentation for *all* function parameters
+
 ]
 
 ignore = [
-    # no blank lines allowed after function docstring
-    "D202",
+    "D202",  # no blank lines allowed after function docstring
 ]
 
-
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"

pyproject.toml

@@ -23,12 +23,35 @@ def debug_mode():
 def set_default_ij_options():
     """Configure ImageJ default options for consistency.
 
-    Set the following options:
-    - Ensure ImageJ appearance settings are default values.
+    Will set the following options to ensure consistent behaviour independent of
+    how ImageJ is configured on a specific machine.
+
+    - Ensure ImageJ appearance settings are the default values.
     - Set foreground color to white and background to black.
-    - Set black background for binary images.
     - Set default file saving format to .txt files.
-    - Ensure images are scaled appropriately when converting between different bit depths.
+    - Ensure intensities are being scaled when converting between bit depths.
+    - Options on binary images:
+        - Set background to black.
+        - Enable padding to prevent eroding from image edges.
+        - Enforce defaults on iterations and count for *erosion*, *dilation*,
+          *opening* and *closing* operations.
+
+    References
+    ----------
+    The ImageJ User Guide is providing detailed explanations of the options
+    configured by this function:
+
+    - [Edit > Options > Appearance][ijo_app]
+    - [Edit > Options > Colors][ijo_col]
+    - [Edit > Options > Conversions][ijo_cnv]
+    - [Edit > Options > Input/Output][ijo_i_o]
+    - [Process > Binary > Options][ijo_bin]
+
+    [ijo_app]: https://imagej.net/ij/docs/guide/146-27.html#sub:Appearance...
+    [ijo_cnv]: https://imagej.net/ij/docs/guide/146-27.html#sub:Conversions...
+    [ijo_col]: https://imagej.net/ij/docs/guide/146-27.html#sub:Colors...
+    [ijo_i_o]: https://imagej.net/ij/docs/guide/146-27.html#sub:Input/Output...
+    [ijo_bin]: https://imagej.net/ij/docs/guide/146-29.html#sub:BinaryOptions...
     """
 
     # Set all appearance settings to default values (untick all options)
@@ -37,11 +60,22 @@ def set_default_ij_options():
     # Set foreground color to be white and background black
     IJ.run("Colors...", "foreground=white background=black selection=red")
 
-    # Set black background for binary images and set pad edges to true to prevent eroding from image edge
+    # Options regarding binary images:
+    # - `black`: set background for binary images to be black.
+    # - `pad`: enable padding of edges to prevent eroding from image edge.
+    # - `iterations=1`: number of times erosion (dilation, opening, closing) is
+    #   performed
+    # - `count=1`: number of adjacent background pixels necessary before a pixel
+    #   is removed from the edge of an object during erosion and the number of
+    #   adjacent foreground pixels necessary before a pixel is added to the edge
+    #   of an object during dilation.
+    # https://imagej.net/ij/docs/menus/process.html#options
+    # https://imagej.net/ij/docs/guide/146-29.html#sub:BinaryOptions...
     IJ.run("Options...", "iterations=1 count=1 black pad")
 
     # Set default saving format to .txt files
     IJ.run("Input/Output...", "file=.txt save_column save_row")
 
-    # Scale when converting = checked
+    # Enable "scale when converting".
+    # https://imagej.net/ij/docs/menus/edit.html#options
     IJ.run("Conversions...", "scale")