Improved documentation, fixed #15, fixed #18

doc/_static/examples/03-bad.txt

@@ -2,4 +2,4 @@
 scale: 1.242347 +-0.00798002
 angle: -30.150000 +-0.225
 shift: 35, 73 +-0.5
-Success: 0.620303
+Success: 0.62

doc/_static/examples/05-extend.txt

@@ -2,4 +2,4 @@
 scale: 1.253436 +-0.00749545
 angle: 150.136364 +-0.204545
 shift: -100, -8 +-0.5
-Success: 0.0797744
+Success: 0.0798

doc/_static/examples/07-resample.txt

@@ -2,4 +2,4 @@
 scale: 1.248983 +-0.00323727
 angle: -30.000000 +-0.075
 shift: 35, 73 +-0.166667
-Success: 0.228771
+Success: 0.229

doc/_static/examples/08-resample2.txt

@@ -2,4 +2,4 @@
 scale: 1.250941 +-0.00311977
 angle: -30.000000 +-0.0714286
 shift: 35, 72 +-0.166667
-Success: 0.218368
+Success: 0.218

doc/_static/examples/09-output.txt

@@ -2,4 +2,4 @@
 scale: 1.242347 +-0.00798002
 angle: -30.150000 +-0.225
 shift: 35, 73 +-0.5
-Success: 0.510836
+Success: 0.511

doc/_static/examples/11-constraints.txt

@@ -3,4 +3,4 @@
 scale: 1.007261 +-0.00365677
 angle: 170.089629 +-0.115237
 shift: -12, -39 +-0.5
-Success: 0.192809
+Success: 0.193

doc/_static/examples/12-difficult.txt

@@ -1,6 +1,6 @@
 [user@linuxbox examples]$ cd cells
 [user@linuxbox cells]$ ird big-fluo.jpg small-dhm.jpg --tile --filter-pcorr 4 --scale 1.0,0.1 --angle 0,20 --lowpass 0.7,0.8 --print-result
-scale: 1.001425 +-0.00463218
-angle: 0.000597 +-0.141732
-shift: 31.8039, 25.9477 +-0.5
-Success: 0.0202402
+scale: 1.001432 +-0.00463218
+angle: 0.000579 +-0.141732
+shift: 31.8047, 25.9485 +-0.5
+Success: 0.0202

doc/changelog.rst

@@ -3,7 +3,11 @@ User-centric changelog
 
 **1.0.5 --- TBA**
 
- * Fixed project documentation typos.
+ * Fixed project documentation typos, added the ``AUTHORS`` file.
+ * Added support for ``pyfftw`` for increased performance.
+ * Improved integration with MS Windows.
+ * Fixed an install bug #18 that occured when dependencies were not met at install-time.
+ * Added documentation for Python constraint interface #15
 
 **1.0.4 --- 2015-03-03**
 

doc/cli-advanced.rst

@@ -105,6 +105,8 @@ So, a warning for those who skip the ordinary text:
     However, when using it, be sure to start off with (let's say) ``--extend 10`` and ``--lowpass 0.9,1.1`` to exploit it.
     Then, experiment with the settings until the results look best.
 
+.. _constraints:
+
 Using constraints
 -----------------
 

doc/devel.rst

@@ -22,6 +22,30 @@ They are used mainly by the ``ird`` tool.
    :members:
    :undoc-members:
 
+How to release
+--------------
+
+The build process in Python is not straightforward (as of 2014).
+Generally, you want this to be taken care of:
+
+- The version mentioned in ``src/imreg_dft/__init__.py`` is the right one.
+- Documentation can be generated (after make clean) and tests run OK too.
+- The source tree is tagged (this is obviously the last step).
+
+For this, there is a ``bash`` script ``tests/release.sh``.
+It accepts one argument --- the version string.
+It runs everything and although it doesn't do anything, it helps you to keep track of what is OK and what still needs to be worked on.
+
+You can execute it from anywhere, for example from the project root:
+
+.. code-block:: shell-session
+
+   [user@linuxbox imreg_dft]$ bash tests/release.sh 1.0.5
+
+The output should be self-explanatory.
+The script is not supposed to rewrite anything important; however, it may run the documentation generation and tests.
+Those, however, can.
+
 Become part of it!
 ------------------
 
@@ -78,3 +102,10 @@ most likely
          0002-BF-added-fix-for-Funny-bug.patch
 
       Send these files to the current project maintainer.
+
+  .. note::
+
+     If you hack the code, remember these things:
+
+      * Add yourself into the ``AUTHORS`` file and briefly describe your contribution.
+      * If your contribution affects how ``imreg_dft`` works (this is *very* likely), mention this in the documentation.

src/imreg_dft/__init__.py

@@ -6,7 +6,7 @@
 try:
     from imreg_dft.imreg import *
 except ImportError as exc:
-    print("Unable to import the main package: %s" % exc.message)
+    print("Unable to import the main package: %s" % exc)
 
 
 __version__ = "1.0.5-pre"

src/imreg_dft/cli.py

@@ -173,7 +173,7 @@ def create_parser():
     parser.add_argument(
         '--print-format', default="scale: %(scale)f +-%(Dscale)g\n"
         "angle: %(angle)f +-%(Dangle)g\n"
-        "shift: %(tx)g, %(ty)g +-%(Dt)g\nSuccess: %(success)g\n", type=outmsg,
+        "shift: %(tx)g, %(ty)g +-%(Dt)g\nSuccess: %(success).3g\n", type=outmsg,
         help="Print a string (to stdout) in a given format. A dictionary "
         "containing the 'scale', 'angle', 'tx', 'ty', 'Dscale', 'Dangle', "
         "'Dt' and 'success' keys will be passed for string interpolation")

src/imreg_dft/imreg.py

@@ -176,6 +176,20 @@ def similarity(im0, im1, numiter=1, order=3, constraints=None,
             Refer to the docs for a thorough explanation. Generally, pass "inf"
             when feeling conservative. Otherwise, experiment, values below 5
             are not even supposed to work.
+        constraints (dict or None): Specify preference of seeked values.
+            Pass None (default) for no constraints, otherwise pass a dict with
+            keys ``angle``, ``scale``, ``tx`` and/or ``ty`` (i.e. you can pass
+            all, some of them or none of them, all is fine). The value of a key
+            is supposed to be a mutable 2-tuple (e.g. a list), where the first
+            value is related to the constraint center and the second one to
+            softness of the constraint (the higher is the number,
+            the more soft a constraint is).
+
+            More specifically, constraints may be regarded as weights
+            in form of a shifted Gaussian curve.
+            However, for precise meaning of keys and values,
+            see the documentation section :ref:`constraints`.
+            Names of dictionary keys map to names of command-line arguments.
 
     Returns:
         dict: Contains following keys: ``scale``, ``angle``, ``tvec`` (Y, X),
@@ -198,8 +212,14 @@ def similarity(im0, im1, numiter=1, order=3, constraints=None,
     angle = 0.0
     im2 = im1
 
+    constraints_default = dict(angle=[0, None], scale=[1, None])
     if constraints is None:
-        constraints = dict(angle=[0, None], scale=[1, None])
+        constraints = constraints_default
+
+    # We guard against case when caller passes only one constraint key.
+    # Now, the provided ones just replace defaults.
+    constraints_default.update(constraints)
+    constraints = constraints_default
 
     # During iterations, we have to work with constraints too.
     # So we make the copy in order to leave the original intact
@@ -297,6 +317,10 @@ def translation(im0, im1, filter_pcorr=0, constraints=None):
         im1 (2D numpy array): The second (subject) image
         filter_pcorr (int): Radius of a spectrum filter for translation
             detection
+        constraints (dict or None): Specify preference of seeked values.
+            For more detailed documentation, refer to :func:`similarity`.
+            The only difference is that here, only keys ``tx`` and/or ``ty``
+            (i.e. both or any of them or none of them) are used.
 
     Returns:
         tuple: The translation vector and success number: ((Y, X), success)

tests/release.sh

@@ -16,10 +16,13 @@ TAGNAME="v$VER"
 git tag | grep "^$TAGNAME$" > /dev/null || failure "The version is not tagged (tag '$TAGNAME' missing)"
 
 # Check that Python has the same version string
-PYTHONPATH="../src" $PYTHON -c "import sys; from imreg_dft import __version__ as ver; sys.exit(0) if ver == '$VER' else sys.exit(1)" || failure "The version of package doesn't match"
+PYTHONPATH="$PROOT/src" $PYTHON -c "import sys; from imreg_dft import __version__ as ver; sys.exit(0) if ver == '$VER' else sys.exit(1)" || failure "The version of package doesn't match"
 
+echo "Trying to generate documentation"
 (cd "$PROOT/doc" && make clean > /dev/null && make html > /dev/null) || failure "Error(s) (re)generating HTML documentation, check that out"
 
+echo "Trying to run tests"
+(cd "$PROOT/tests" && make check > /dev/null) || failure "Error(s) running tests, check that out"
 
 test $SUCCESS == "yes" && { echo "All is OK for version '$VER'"; exit 0; }