Name

swim — Fourier-based image aligner

Synopsis

  1. swim size [options] target source
  2. swim size [options] target xtgt ytgt source
  3. swim size [options] target xtgt ytgt source xsrc ysrc
  4. swim size [options] target xtgt ytgt source xsrc ysrc φsrc
  5. swim size [options] target xtgt ytgt source xsrc ysrc M00 M01 M10 M11
  6. swim size [options] target xtgt ytgt source A00 A-101 A-102 A-110 A-111 A-112 -
  7. swim size [options] target xtgt ytgt source A00 A01 A02 A10 A11 A12 x
  8. swim size

Description

swim aligns a subsection of the image file source with a subsection of the image file target using the SWiFT-IR algorithm described in Wetzel et al. (2016).

size specifies the size of the subsection to use and may be specified as a single number or in the form WxH.

In general, we need to have a point ptgt = (xtgt, ytgt) and a corresponding point psrc = (xsrc, ysrc). These can be explicitly given, or psrc can be inferred from an affine transformation psrc = M ptgt + b.

In form (1), ptgt and psrc are the center of the respective images.

In form (2), xsrc is implicitly the same is xtgt and ysrc the same as ytgt. The transformation matrix M = [1 0; 0 1] with zero translation.

In form (3), the transformation matrix M = [1 0; 0 1], and the translation b is taken from ptgt and psrc.

In form (4), the transformation matrix M is set to [cos(φ) sin(φ); -sin(φ) cos(φ)], where φ is the angle specified (in degrees).

In form (5), the transformation matrix is specified explicitly.

In forms (6) and (7), an affine transformation matrix A is specified. There must a final argument after the number. If that argument starts with a hyphen, psrc = A-1 ptgt and the transformation matrix M is likewise taken from A-1. Otherwise, psrc = A ptgt.

(Note that A p := M p + b if A = [ M00 M01 b0; M10 M11 b1].)

In form (8), commands are read from stdin. Lines starting with hash (“#”) are ignored.

Options

-A
Disable apodization. (Apodization is blending the edges to gray to avoid false spectral content.)
-H
Do not optimize horizontal translation.
-k str
Keep image. This causes apodized and transformed images to be saved to disk.
-i expr
Specify number of iterations. Default is one. Three may be a good choice.
-m expr
Specify multiplier applied to -x and -y arguments.
-r
Reverse video
-t snrthr,xthr,ythr
Set rejection thresholds for SNR value and for shifts in pixels. Values are separated by commas. xthr and ythr are applied to coordinates that have been multiplied by the value given with -m. Arithmetic is not allowed.
-V
Do not optimize vertical translation.

-w expr: Specify whitening exponent. If set to zero, whitening is disabled.

-x expr: Specify additional shift for x-coordinate of center of patch

-y expr: Specifiy additional shift for y-coordinate of center of path

-$ n: Specify debug level

Expressions may contain addition, subtraction, multiplication, division, and exponentiation. Parentheses are supported. Variables are not supported. Note that unlike for mir, there must be a space between the option name and the option value.

The translation specified by the -x and -y command line options are applied directly to ptgt. Transformed by M they are applied to psrc. The multiplier specified by -m is applied to all coordinates.

Output

swim outputs a line of the form

SNR: target xtgt ytgt source xsrc ysrc φsrcx Δy m0 flags)

Here:

SNR
is the signal to noise value of the match.
target
is the file name of the target image copied from the command line
xtgt ytgt
are the coordinates of ptgt modified by the -x and -y command line options.
source
is the file name of the source image copied from the command line
xsrc ysrc
are the optimized coordinates of psrc that match ptgt.
φsrc
is the optimized rotation.

Information in parentheses is somewhat redundant. Δx and Δy are the pixel shifts applied to psrc andm0 := √(Δx2 + Δy2). The flags can indicate bad matches in x (“dx”), in y (“dy”), in both (“dxy”) if any shift is greater than a quarter of the window size. It can also indicate that a threshold has been exceeded (“dreset”)

Usage note

Note that mir uses output and input coordinates to place a source image in a target space and returns a “forward” transform that maps source to target as well as an “inverse” transform that maps target back to source. It is this inverse transform that can be fed to swim as the M transformation matrix on a refinement pass.

Reference

Wetzel AW, Bakal J, Dittrich M, Hildebrand DGC, Morgan JL, Lichtman JW, 2016. Registering large volume serial-section electron microscopy image sets for neural circuit reconstruction using FFT signal whitening. arXiv:1612.04787. https://arxiv.org/abs/1612.04787.

Author

swim was written by Tom Wetzel. This page was written by Daniel Wagenaar.