diff --git a/transforms/images/apply-flatfield-plugin/.bumpversion.cfg b/transforms/images/apply-flatfield-plugin/.bumpversion.cfg new file mode 100644 index 000000000..a0dda9006 --- /dev/null +++ b/transforms/images/apply-flatfield-plugin/.bumpversion.cfg @@ -0,0 +1,29 @@ +[bumpversion] +current_version = 2.0.0-dev8 +commit = False +tag = False +parse = (?P\d+)\.(?P\d+)\.(?P\d+)(\-(?P[a-z]+)(?P\d+))? +serialize = + {major}.{minor}.{patch}-{release}{dev} + {major}.{minor}.{patch} + +[bumpversion:part:release] +optional_value = _ +first_value = dev +values = + dev + _ + +[bumpversion:part:dev] + +[bumpversion:file:pyproject.toml] +search = version = "{current_version}" +replace = version = "{new_version}" + +[bumpversion:file:plugin.json] + +[bumpversion:file:VERSION] + +[bumpversion:file:README.md] + +[bumpversion:file:src/polus/plugins/transforms/images/apply_flatfield/__init__.py] diff --git a/transforms/images/apply-flatfield-plugin/README.md b/transforms/images/apply-flatfield-plugin/README.md new file mode 100644 index 000000000..8ac8366c9 --- /dev/null +++ b/transforms/images/apply-flatfield-plugin/README.md @@ -0,0 +1,49 @@ +# Apply Flatfield Plugin (v2.0.0-dev8) + +This WIPP plugin applies a flatfield operation on every image in a collection. +The algorithm used to apply the flatfield is as follows: + +![Corrected = \frac{Original - Darkfield}{Brightfield} - Photobleach + Offset](https://render.githubusercontent.com/render/math?math=Corrected%20%3D%20%5Cfrac%7BOriginal%20-%20Darkfield%7D%7BBrightfield%7D%20-%20Photobleach%20%2B%20Offset) + +A brief description of the variables: +1. ![Corrected](https://render.githubusercontent.com/render/math?math=Corrected) is the flatfield corrected image. +2. ![Darkfield](https://render.githubusercontent.com/render/math?math=Darkfield) is the darkfield image (sometimes referred to as offset, dark current, or dark noise). This is an image collected by the camera when the shutter is closed. +3. ![Brightfield](https://render.githubusercontent.com/render/math?math=Brightfield) is the normalized brightfield image. This is an image collected when the shutter is open and illumination is on. The image should contain single precision floating point values, where ![mean(Brightfield)=1](https://render.githubusercontent.com/render/math?math=mean(Brightfield)%3D1). +4. ![Photobleach](https://render.githubusercontent.com/render/math?math=Photobleach) is a scalar indicating how much the image has been photobleached. This is a per-image scalar offset. +5. ![Offset](https://render.githubusercontent.com/render/math?math=Offset) is a scalar applied to all images in the collection. If ![Photobleach](https://render.githubusercontent.com/render/math?math=Photobleach) is specified, then this plugin uses ![Offset=mean(Photobleach)](https://render.githubusercontent.com/render/math?math=Offset%3Dmean(Photobleach)). + +For more information on flatfielding, see the paper by [Young](https://currentprotocols.onlinelibrary.wiley.com/doi/full/10.1002/0471142956.cy0211s14). +This plugin specifically uses the formulation from [Peng et al](https://www.nature.com/articles/ncomms14836). + +For more information on WIPP, visit the +[official WIPP page](https://isg.nist.gov/deepzoomweb/software/wipp). + +## To Do + +Implement additional formulations of flatfield correction. Specifically, the formula specified by Young: + +![Corrected = \frac{Original - Darkfield}{Brightfield - Darkfield} ](https://render.githubusercontent.com/render/math?math=Corrected%20%3D%20%5Cfrac%7BOriginal%20-%20Darkfield%7D%7BBrightfield%20-%20Darkfield%7D%20) + +Additional formulations may also include reference image free algorithms for flatfield correction, such as the [rolling ball algorithm](https://www.computer.org/csdl/magazine/co/1983/01/01654163/13rRUwwJWBB). + +## Building + +To build the Docker image for the conversion plugin, run `./build-docker.sh`. + +## Install WIPP Plugin + +If WIPP is running, navigate to the plugins page and add a new plugin. +Paste the contents of `plugin.json` into the pop-up window and submit. + +## Options + +Command line options: + +| Name | Description | I/O | Type | +|------------------|-----------------------------------------------------------------------|--------|------------| +| `--darkPattern` | Filename pattern used to match darkfield files to image files | Input | string | +| `--ffDir` | Image collection containing flatfield and/or darkfield images | Input | collection | +| `--flatPattern` | Filename pattern used to match flatfield files to image files | Input | string | +| `--imgDir` | Input image collection to be processed by this plugin | Input | collection | +| `--imgPattern` | Filename pattern used to separate data and match with flatfield files | Input | string | +| `--outDir` | Output collection | Output | collection | diff --git a/transforms/images/apply-flatfield-plugin/VERSION b/transforms/images/apply-flatfield-plugin/VERSION new file mode 100644 index 000000000..e7940151c --- /dev/null +++ b/transforms/images/apply-flatfield-plugin/VERSION @@ -0,0 +1 @@ +2.0.0-dev8 diff --git a/transforms/images/apply-flatfield-plugin/plugin.json b/transforms/images/apply-flatfield-plugin/plugin.json new file mode 100644 index 000000000..871525457 --- /dev/null +++ b/transforms/images/apply-flatfield-plugin/plugin.json @@ -0,0 +1,94 @@ +{ + "name": "Apply Flatfield", + "version": "2.0.0-dev8", + "title": "Apply Flatfield", + "description": "Apply a flatfield algorithm to a collection of images.", + "author": "Nick Schaub (Nick.Schaub@nih.gov), Najib Ishaq (najib.ishaq@nih.gov)", + "institution": "National Center for Advancing Translational Sciences, National Institutes of Health", + "repository": "https://github.com/labshare/polus-plugins", + "website": "https://ncats.nih.gov/preclinical/core/informatics", + "citation": "", + "containerId": "polusai/apply-flatfield-plugin:2.0.0-dev8", + "baseCommand": [ + "python3", + "-m", + "polus.plugins.transforms.images.apply_flatfield" + ], + "inputs": [ + { + "name": "darkPattern", + "type": "string", + "description": "Filename pattern used to match darkfield files to image files", + "required": false + }, + { + "name": "ffDir", + "type": "collection", + "description": "Image collection containing flatfield and/or darkfield images", + "required": true + }, + { + "name": "brightPattern", + "type": "string", + "description": "Filename pattern used to match brightfield files to image files", + "required": true + }, + { + "name": "imgDir", + "type": "collection", + "description": "Input image collection to be processed by this plugin", + "required": true + }, + { + "name": "imgPattern", + "type": "string", + "description": "Filename pattern used to separate data and match with flatfied files", + "required": true + }, + { + "name": "photoPattern", + "type": "string", + "description": "Filename pattern used to match photobleach files to image files", + "required": true + } + ], + "outputs": [ + { + "name": "outDir", + "type": "collection", + "description": "Output collection" + } + ], + "ui": [ + { + "key": "inputs.imgDir", + "title": "Images to correct", + "description": "Input image collection to be processed by this plugin" + }, + { + "key": "inputs.imgPattern", + "title": "Image pattern", + "description": "Filename pattern used to separate data and match with flatfied files" + }, + { + "key": "inputs.ffDir", + "title": "Background images (flatfield/darkfield)", + "description": "Image collection containing flatfield and/or darkfield images" + }, + { + "key": "inputs.brightPattern", + "title": "Brightfield file pattern", + "description": "Filename pattern used to match brightfield files to image files" + }, + { + "key": "inputs.darkPattern", + "title": "Darkfield file pattern", + "description": "Filename pattern used to match darkfield files to image files" + }, + { + "key": "inputs.photoPattern", + "title": "Photobleach file pattern", + "description": "Filename pattern used to match photobleach files to image files" + } + ] +} diff --git a/transforms/images/apply-flatfield-plugin/pyproject.toml b/transforms/images/apply-flatfield-plugin/pyproject.toml index d4e72a227..69408fbb2 100644 --- a/transforms/images/apply-flatfield-plugin/pyproject.toml +++ b/transforms/images/apply-flatfield-plugin/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "polus-plugins-transforms-images-apply-flatfield" -version = "2.0.0-dev7" +version = "2.0.0-dev8" description = "" authors = [ "Nick Schaub ", diff --git a/transforms/images/apply-flatfield-plugin/src/polus/plugins/transforms/images/apply_flatfield/__init__.py b/transforms/images/apply-flatfield-plugin/src/polus/plugins/transforms/images/apply_flatfield/__init__.py index dd697c5a6..b23e1fea8 100644 --- a/transforms/images/apply-flatfield-plugin/src/polus/plugins/transforms/images/apply_flatfield/__init__.py +++ b/transforms/images/apply-flatfield-plugin/src/polus/plugins/transforms/images/apply_flatfield/__init__.py @@ -14,6 +14,8 @@ from . import utils +__version__ = "2.0.0-dev8" + logger = logging.getLogger(__name__) logger.setLevel(utils.POLUS_LOG)