Update metadata

.github/workflows/test_and_deploy.yml

@@ -79,7 +79,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -U setuptools setuptools_scm wheel twine
+          pip install -U setuptools setuptools_scm wheel twine build
       - name: Build and publish
         env:
           TWINE_USERNAME: __token__

README.md

@@ -1,61 +1,99 @@
-# affinder
+# Description
 
-[![License](https://img.shields.io/pypi/l/affinder.svg?color=green)](https://github.com/napari/affinder/raw/main/LICENSE)
-[![PyPI](https://img.shields.io/pypi/v/affinder.svg?color=green)](https://pypi.org/project/affinder)
-[![Python Version](https://img.shields.io/pypi/pyversions/affinder.svg?color=green)](https://python.org)
-[![tests](https://github.com/jni/affinder/workflows/tests/badge.svg)](https://github.com/jni/affinder/actions)
-[![codecov](https://codecov.io/gh/jni/affinder/branch/main/graph/badge.svg)](https://codecov.io/gh/jni/affinder)
+This GUI plugin allows you to quickly find the affine matrix mapping
+one image to another using manual correspondence points annotation.
 
-Quickly find the affine matrix mapping one image to another using manual correspondence points annotation
+More simply, this plugin allows you to select corresponding points
+on an image, and a second image you wish to transform. It computes 
+the requisite transformation matrix using Affine Transform, Euclidean Transform, 
+or Similarity Transform, and performs this transformation on the
+moving image, aligning it to the reference image.
 
-## Installation
+https://user-images.githubusercontent.com/17995243/120086403-f1d0b300-c121-11eb-8000-a44a2ac54339.mp4
 
-You can install `affinder` via [pip]:
 
-    pip install affinder
+# Who is This For?
 
-## Documentation
+This is a simple plugin which can be used on any 2D images, provided
+they can be loaded as layers into napari. The images need not be the same
+file format and this plugin also works with labels layers.
 
-The affinder documentation is available here: [https://jni.github.io/affinder/](https://jni.github.io/affinder/)
+No prior understanding of the transformation methods is required, as
+they perform in the background based on the reference points selected.
 
-## Contributing
+# How to Guide
 
-Contributions are very welcome. Tests can be run with [tox], please ensure
-the coverage at least stays the same before you submit a pull request.
+You will need a combination of two or more 2D image and/or labels layers 
+loaded into napari. Once you have installed affinder, you can find it in
+the dock widgets menu.
 
-## License
+![Affinder widget in the Plugins->Add Dock Widget menu](https://i.imgur.com/w7MCXQy.png)
 
-Distributed under the terms of the [BSD-3] license,
-"affinder" is free and open source software
+The first two dropdown boxes will be populated with the layers currently
+loaded into napari. Select a layer to use as reference, and another to
+transform.
 
-## Issues
+![Dropdowns allow you to select the reference and moving layers](https://i.imgur.com/Tdbm1sX.png)
 
-If you encounter any problems, please [file an issue] along with a detailed description.
+Next, you can select the transformation model to use (affine is selected by default
+and is the least rigid transformation of those available). See [below](#transformation-models) for a
+description of the different models.
 
-[napari]: https://github.com/napari/napari
-[Cookiecutter]: https://github.com/audreyr/cookiecutter
-[@napari]: https://github.com/napari
-[MIT]: http://opensource.org/licenses/MIT
-[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
-[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt
-[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt
-[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0
-[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt
-[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin
-[file an issue]: https://github.com/jni/affinder/issues
-[napari]: https://github.com/napari/napari
-[tox]: https://tox.readthedocs.io/en/latest/
-[pip]: https://pypi.org/project/pip/
-[PyPI]: https://pypi.org/
+Finally, you can optionally select a path to a text file for saving out the
+resulting transformation matrix.
 
-----------------------------------
+When you click Start, affinder will add two points layers to napari. 
+The plugin will also bring your reference image in focus, and its associated points
+layer. You can then start adding reference points by clicking on your image.
 
-This [napari] plugin was generated with [Cookiecutter] using with [@napari]'s [cookiecutter-napari-plugin] template.
+![Adding reference points to layer](https://i.imgur.com/WPzNtyy.png)
 
-<!--
-Don't miss the full getting started guide to set up your new package:
-https://github.com/napari/cookiecutter-napari-plugin#getting-started
+Once three points are added, affinder will switch focus to the moving image,
+and you should then proceed to select the corresponding three points.
 
-and review the napari docs for plugin developers:
-https://napari.org/docs/plugins/index.html
--->
+![Adding corresponding points to newly focused layer](https://i.imgur.com/JVZCvmp.png)
+
+affinder will immediately transform the moving image to align the points you've
+selected when you add your third corresponding point to your moving image.
+
+![The moving image is transformed once three points are added](https://i.imgur.com/NTne9fj.png)
+
+From there, you can continue iteratively adding points until you 
+are happy with the alignment. Affinder will switch focus between
+reference and moving image with each point.
+
+Click Finish to exit affinder.
+
+## Transformation Models
+
+There are three transformation models available for use with affinder.
+They are listed here in order of increasing rigidity in the types of
+transforms they will allow. The eponymous Affine Transform is the 
+least rigid and is the default choice.
+
+- [**Affine Transform**](https://en.wikipedia.org/wiki/Affine_transformation): 
+the least rigid transformation, it preserves
+lines and parallelism, but not necessarily distance and angles. Translation,
+scaling, similarity, reflection, rotation and shearing are all valid
+affine transformations.
+
+- [**Similarity Transform**](https://en.wikipedia.org/wiki/Similarity_(geometry)): 
+this is a "shape preserving" transformation, producing objects which are 
+geometrically similar. Translation, rotation, reflection and uniform scaling are 
+valid similarity transforms. Shearing is not.
+
+- [**Euclidean Transform**](https://en.wikipedia.org/wiki/Rigid_transformation):
+Also known as a rigid transformation, this transform preserves the Euclidean
+distance between each pair of points on the image. This includes rotation,
+translation and reflection but not scaling or shearing.
+
+# Getting Help
+
+If you find a bug with affinder, or would like support with using it, please raise an
+issue on the [GitHub repository](https://github.com/jni/affinder).
+
+# How to Cite
+
+Many plugins may be used in the course of published (or publishable) research, as well as
+during conference talks and other public facing events. If you'd like to be cited in
+a particular format, or have a DOI you'd like used, you should provide that information here.

docs/replace_description_text.py

@@ -1,6 +1,6 @@
 """
-for ../.napari/DESCRIPTION.md
-find URLs ending in .mp4 and replace URL wrapped in HTML video tag 
+for README.md
+find URLs ending in .mp4 and replace it with URL wrapped in HTML video tag.
 """
 
 replacement_url = '<video width="640" height="480" controls>\n\
@@ -9,7 +9,7 @@
 </video>\n'
 new_text = ""
 
-with open(".napari/DESCRIPTION.md", 'r+') as desc_file:
+with open("README.md", 'r+') as desc_file:
     for line in desc_file:
         if line.strip().startswith("https://user-images.githubusercontent") and line.strip().endswith(".mp4"):
             line = replacement_url.format(line.strip())

docs/usage.rst

@@ -1,5 +1,5 @@
 Using affinder
 ==============
 
-.. include:: ../.napari/DESCRIPTION.md
+.. include:: ../README.md
    :parser: myst_parser.sphinx_

setup.cfg

@@ -51,6 +51,7 @@ testing =
     pytest-qt
     scikit-image[data]
     napari[pyqt5]!=0.4.18
+    pygments!=2.16
     zarr
 docs = 
     furo

src/affinder/napari.yaml

@@ -1,5 +1,7 @@
 name: affinder
 display_name: affinder
+categories:
+  - Transformations
 contributions:
   commands:
   - id: affinder.start_affinder

tox.ini

@@ -32,5 +32,6 @@ deps =
     pytest-qt
     scikit-image[data]
     napari[pyqt5]!=0.4.18
+    pygments!=2.16
     zarr
 commands = pytest -v --color=yes --cov=affinder --cov-report=xml