Deploying to gh-pages from @ 14a02c9 🚀

_sources/usage.rst.txt

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

index.html

@@ -204,47 +204,90 @@ <h1>Welcome to affinder’s documentation!<a class="headerlink" href="#welcome-t
 </li>
 </ul>
 </div>
-<section id="affinder">
-<h2>affinder<a class="headerlink" href="#affinder" title="Permalink to this headline">#</a></h2>
-<p><a class="reference external" href="https://github.com/napari/affinder/raw/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/affinder.svg?color=green" /></a>
-<a class="reference external" href="https://pypi.org/project/affinder"><img alt="PyPI" src="https://img.shields.io/pypi/v/affinder.svg?color=green" /></a>
-<a class="reference external" href="https://python.org"><img alt="Python Version" src="https://img.shields.io/pypi/pyversions/affinder.svg?color=green" /></a>
-<a class="reference external" href="https://github.com/jni/affinder/actions"><img alt="tests" src="https://github.com/jni/affinder/workflows/tests/badge.svg" /></a>
-<a class="reference external" href="https://codecov.io/gh/jni/affinder"><img alt="codecov" src="https://codecov.io/gh/jni/affinder/branch/main/graph/badge.svg" /></a></p>
-<p>Quickly find the affine matrix mapping one image to another using manual correspondence points annotation</p>
-<section id="installation">
-<h3>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">#</a></h3>
-<p>You can install <code class="docutils literal notranslate"><span class="pre">affinder</span></code> via <a class="reference external" href="https://pypi.org/project/pip/">pip</a>:</p>
-<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install affinder
-</pre></div>
-</div>
+<section id="description">
+<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">#</a></h2>
+<p>This GUI plugin allows you to quickly find the affine matrix mapping
+one image to another using manual correspondence points annotation.</p>
+<p>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.</p>
+<video width="640" height="480" controls>
+    <source src="https://user-images.githubusercontent.com/17995243/120086403-f1d0b300-c121-11eb-8000-a44a2ac54339.mp4" type="video/mp4">
+Your browser does not support the video tag.
+</video>
 </section>
-<section id="documentation">
-<h3>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">#</a></h3>
-<p>The affinder documentation is available here: <a class="reference external" href="https://jni.github.io/affinder/">https://jni.github.io/affinder/</a></p>
+<section id="who-is-this-for">
+<h2>Who is This For?<a class="headerlink" href="#who-is-this-for" title="Permalink to this headline">#</a></h2>
+<p>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.</p>
+<p>No prior understanding of the transformation methods is required, as
+they perform in the background based on the reference points selected.</p>
 </section>
-<section id="contributing">
-<h3>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline">#</a></h3>
-<p>Contributions are very welcome. Tests can be run with <a class="reference external" href="https://tox.readthedocs.io/en/latest/">tox</a>, please ensure
-the coverage at least stays the same before you submit a pull request.</p>
+<section id="how-to-guide">
+<h2>How to Guide<a class="headerlink" href="#how-to-guide" title="Permalink to this headline">#</a></h2>
+<p>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.</p>
+<p><img alt="Affinder widget in the Plugins-&gt;Add Dock Widget menu" src="https://i.imgur.com/w7MCXQy.png" /></p>
+<p>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.</p>
+<p><img alt="Dropdowns allow you to select the reference and moving layers" src="https://i.imgur.com/Tdbm1sX.png" /></p>
+<p>Next, you can select the transformation model to use (affine is selected by default
+and is the least rigid transformation of those available). See <span class="xref myst">below</span> for a
+description of the different models.</p>
+<p>Finally, you can optionally select a path to a text file for saving out the
+resulting transformation matrix.</p>
+<p>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.</p>
+<p><img alt="Adding reference points to layer" src="https://i.imgur.com/WPzNtyy.png" /></p>
+<p>Once three points are added, affinder will switch focus to the moving image,
+and you should then proceed to select the corresponding three points.</p>
+<p><img alt="Adding corresponding points to newly focused layer" src="https://i.imgur.com/JVZCvmp.png" /></p>
+<p>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.</p>
+<p><img alt="The moving image is transformed once three points are added" src="https://i.imgur.com/NTne9fj.png" /></p>
+<p>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.</p>
+<p>Click Finish to exit affinder.</p>
+<section id="transformation-models">
+<h3>Transformation Models<a class="headerlink" href="#transformation-models" title="Permalink to this headline">#</a></h3>
+<p>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.</p>
+<ul class="simple">
+<li><p><a class="reference external" href="https://en.wikipedia.org/wiki/Affine_transformation"><strong>Affine Transform</strong></a>:
+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.</p></li>
+<li><p><a class="reference external" href="https://en.wikipedia.org/wiki/Similarity_(geometry)"><strong>Similarity Transform</strong></a>:
+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.</p></li>
+<li><p><a class="reference external" href="https://en.wikipedia.org/wiki/Rigid_transformation"><strong>Euclidean Transform</strong></a>:
+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.</p></li>
+</ul>
 </section>
-<section id="license">
-<h3>License<a class="headerlink" href="#license" title="Permalink to this headline">#</a></h3>
-<p>Distributed under the terms of the <a class="reference external" href="http://opensource.org/licenses/BSD-3-Clause">BSD-3</a> license,
-“affinder” is free and open source software</p>
 </section>
-<section id="issues">
-<h3>Issues<a class="headerlink" href="#issues" title="Permalink to this headline">#</a></h3>
-<p>If you encounter any problems, please <a class="reference external" href="https://github.com/jni/affinder/issues">file an issue</a> along with a detailed description.</p>
-<hr class="docutils" />
-<p>This <a class="reference external" href="https://github.com/napari/napari">napari</a> plugin was generated with <a class="reference external" href="https://github.com/audreyr/cookiecutter">Cookiecutter</a> using with <a class="reference external" href="https://github.com/napari">&#64;napari</a>’s <a class="reference external" href="https://github.com/napari/cookiecutter-napari-plugin">cookiecutter-napari-plugin</a> template.</p>
-<!--
-Don't miss the full getting started guide to set up your new package:
-https://github.com/napari/cookiecutter-napari-plugin#getting-started
-
-and review the napari docs for plugin developers:
-https://napari.org/docs/plugins/index.html
---></section>
+<section id="getting-help">
+<h2>Getting Help<a class="headerlink" href="#getting-help" title="Permalink to this headline">#</a></h2>
+<p>If you find a bug with affinder, or would like support with using it, please raise an
+issue on the <a class="reference external" href="https://github.com/jni/affinder">GitHub repository</a>.</p>
+</section>
+<section id="how-to-cite">
+<h2>How to Cite<a class="headerlink" href="#how-to-cite" title="Permalink to this headline">#</a></h2>
+<p>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.</p>
 </section>
 </section>
 <section id="indices-and-tables">
@@ -304,14 +347,14 @@ <h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Pe
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Welcome to affinder’s documentation!</a><ul>
-<li><a class="reference internal" href="#affinder">affinder</a><ul>
-<li><a class="reference internal" href="#installation">Installation</a></li>
-<li><a class="reference internal" href="#documentation">Documentation</a></li>
-<li><a class="reference internal" href="#contributing">Contributing</a></li>
-<li><a class="reference internal" href="#license">License</a></li>
-<li><a class="reference internal" href="#issues">Issues</a></li>
+<li><a class="reference internal" href="#description">Description</a></li>
+<li><a class="reference internal" href="#who-is-this-for">Who is This For?</a></li>
+<li><a class="reference internal" href="#how-to-guide">How to Guide</a><ul>
+<li><a class="reference internal" href="#transformation-models">Transformation Models</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#getting-help">Getting Help</a></li>
+<li><a class="reference internal" href="#how-to-cite">How to Cite</a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>