DUALALIGN LLC

Tutorials on how to use

i2k Command-line
Executable
For i2k Align and i2k Retina, both STD and PRO

Gary Yang and Chuck Stewart

6/2/2015
Table of Contents
Introduction .............................................................................................................................. 3
Syntax and Help ........................................................................................................................ 3
Montaging and Align ................................................................................................................. 4
Example 1. Montage of four images. ............................................................................... 4
Example 2. Montage of four retinal images. ................................................................... 4
Example 3. Montage using a list file ................................................................................ 4
Example 4. Montage with a layout choice ....................................................................... 4
Example 5. Align a set of images. The result will be a set of output images ................... 4
Example 6. Specifying the output location. ..................................................................... 4
Example 7. Align a set of images with higher aggressive value. ...................................... 4
Example 8. Montaging thermal images ........................................................................... 5
Summary of switches ........................................................................................................ 5
License Status............................................................................................................................ 5
Example 1. Show current license status .......................................................................... 6
Example 2. Activate license............................................................................................... 7
Example 3. Manual activation........................................................................................... 7
Example 4. Deactivation ................................................................................................... 8
Summary of switches ........................................................................................................ 8
Advanced Switches ................................................................................................................... 8
-target [image file name] .................................................................................................. 9
-save_xforms ..................................................................................................................... 9
Surrogate Image................................................................................................................ 9
Process Multi-band images ............................................................................................... 9
Illumination Correction for Aligned Images Output ....................................................... 10
Supply Region of Interest ................................................................................................ 10
Multi-row Mode .............................................................................................................. 11
Utility Switches ....................................................................................................................... 13
-thread [integer] ............................................................................................................. 13
-mem [integer] ................................................................................................................ 13
-log_level [integer] .......................................................................................................... 13
-log_folder [folder path] ................................................................................................. 13
-log_cout [file name] ....................................................................................................... 13
-loop [integer] ................................................................................................................. 14
-monitor_time [interger] ................................................................................................ 14

DualAlign LLC 2008-2014 ©

Final Notes .............................................................................................................................. 14

DualAlign LLC 2008-2014 ©

Introduction
This document was written to assist readers to understand how to use the command line
executable of i2k Align and i2k Retina.
The Command Line Interface (CLI) is da_i2k_align_exec_v2 for i2k Align and
da_i2k_retina_exec_v2 for i2k Retina. Both use the same syntax. On Windows the full
executable name is da_i2k_align_exec_v2.exe, but the “.exe” extension is not always needed
when typing a command. We simply use da_i2k_align_exec_v2 in our tutorials. Reader may
safely replace it with da_i2k_retina_exec_v2.

Syntax and Help

On a command-line the name of the executable is usually followed by a number of
argument (“command-line arguments”), separated by white spaces. There are two different
kinds of arguments. Both appear in the following example:
da_i2k_align_exec_v2 a.jpg b.jpg -ext tiff c.jpg -save_alpha

 A positioned argument is one that is placed in a specific order on the command-line

without a leading “-“ dash mark. On the example, these are a.jpg, b.jpg and c.jpg.
They are often typed at the very beginning (but after the name of the executable) or
at the end, but as this example shows, this is not necessary. Positioned arguments
are usually used to supply image file names to the executable.
 An optional switch is a name-and-value pair, with the name started with “-“ (dash
sign). A name is almost always immediately followed by a value. A switch is usually
used to modify program’s behavior, for instance, “-ext tiff” will force the output
image type to be TIFF. The type of value depends on the switch, with common
types being Boolean, integer, floating point value, and string. In this tutorial, we use
“[]” to indicate the value type that a switch can take, for instance “-subset [integer]”
means “-subset” accepts only integer values.

It is worth noting the Boolean switch has no value. The presence of switch is True
and the absence is False. For instance, “-save_alpha” specifies true values for
saving alpha channel.

A call to the executable may include both positioned arguments and switches. The latter can be
given in any order and at any position. Positioned arguments are ordered, but may be
separated by one or more switches. All arguments and switches must be separated by white
spaces.

To see the full list of switches available, one can invoke

da_i2k_align_exec_v2

or
da_i2k_align_exec_v2 –h

DualAlign LLC 2008-2014 ©

Montaging and Align

Example 1. Montage of four images.

Montaging a set of images is very simple. The following will generate a montage of four
images:
da_i2k_align_exec_v2 img0001.jpg img0002.jpg img0003.jpg img0004.jpg

Example 2. Montage of four retinal images.

Users of i2k Retina may want to specify the use of retinal image type, which can be done by
adding a switch:
da_i2k_retina_exec_v2 –image_type 0 img0001.jpg img0002.jpg img0003.jpg
img0004.jpg

Again, the switch “-image_type 0” can be placed at any position, or even at the end of the
command.

Example 3. Montage using a list file

Alternatively, we can first create a text file that contains all image file names, one per line:
img0001.jpg
img0002.jpg
img0003.jpg
img0004.jpg

We can then use the switch “-list [text file name]”. The command line will look like:
da_i2k_align_exec_v2 -list image-list.txt

Example 4. Montage with a layout choice

To specify the use of planar layout, we just need to add a switch:
da_i2k_align_exec_v2 -list image-list.txt –layout 1

Example 5. Align a set of images. The result will be a set of output images
The align output produces a set of transformed/warped images, each corresponding to one
of the input images, and all aligned in the same coordinate system.
Using the image list file shown in Example 2, the command line will look like:

da_i2k_align_exec_v2 image-list.txt -output_type 1

Example 6. Specifying the output location.

da_i2k_align_exec_v2 image-list.txt -dir hawaii/results

Example 7. Align a set of images with higher aggressive value.

The aggressive setting controls the tradeoff between speed and completeness. The default
value is 1, which is the fastest setting and mostly suitable to images taken at one time. If there
is small overlap, moving objects or substantial appearance differences between images, higher
values are recommended so that the program will conduct more complete search for the

DualAlign LLC 2008-2014 ©

correct alignment. The value 10 is the most aggressive value, which means it will be most time
consuming as well.
Thus, if we want to align a set of images with Homography transform as much as possible,
we can use
da_i2k_align_exec_v2 image-list.txt –aggressive 10 -output_type 1 –
layout 6

Example 8. Montaging thermal images

To mosaic a set of thermal images with affine layout option:
da_i2k_align_exec -list thermal/thermal.list -output_type 0 -
image_type 2 -layout 5

Summary of switches
We introduced three switches in this section:
 -image_type [integer]: Use this to specify the image type to use. The default value
is 1, which represents photographic image type. Value 0 represents retinal images, 2
indicates single-modality images (but typically not retinal, and not photographic),
and 3 says the images are of mixed modality (“multi-modality”), such as IR and
photographic, or different wave-length IR images.
 -layout [integer]: It specifies the layout type to use. The default value is 0, which
represents auto layout, which means i2k Align figures it out automatically. The
value can be in the range of 0 to 7: 1 is planar, 2 is cylindrical, 3 is reposition, 4 is
similarity, 5 is affine, 6 is homography, and 7 is quadratic. Please note that each
image type may allow only a subset of these layout types. For instance, retinal
image type allows only affine and quadratic1.
 -aggressive [integer]: It specifies the aggressive value to use during image
registration. The default value is 1 and the range is from 1 to 10. 10 is the most
aggressive setting. In other words, the program will try to search more hypotheses
and use relaxed acceptance criteria.
 -list [text file name]: Use this to tell i2k Align the name of the text file that provides
image names. Each line of the text file is treated as one image name. If the line
starts with “#” sign, the line is treated as comment line and is ignored.
 -output_type [integer]: specify the output type. The default value is 0, which
represents a mosaic. Value 1 is a set of aligned images, 2 is Montage Sequence, 3 is
Synchronized mode, and 4 is no graphic output. Note that 2 and 3 are only available
in the Pro version of the software.
 -dir [path]: specify the output location.

License Status
Both i2k Align and i2k Retina need to find the license in order to function correctly.
Normally the software installer creates a license folder and it is shared and used by both the GUI
program and the command-line executable.

1
Auto layout is treated as quadratic layout in retinal image type.

DualAlign LLC 2008-2014 ©

 The default license folder on Mac is /Users/Shared/i2kAlign (or /Users/Shared/i2kRetina for
i2k Retina). On Linux the license folder is $HOME/.i2k (notice there is a dot).

On Windows if 32-bit software is used, the license folder is located at “%APPDATA%\i2k

Align” (or “%APPDATA%\i2k Retina” for i2k Retina). If the 64-bit software is used on a 64-bit
Windows the folder is located as “%APPDATA%\i2k Align x64” (or “%APPDATA%\i2k Retina x64”
for i2k Retina). “%APPDATA%” is a Windows environment variable and on a Windows Vista/7/8,
it is usually expanded to “C:\Users\user_name\AppData\Roaming”.

If not specified, the default license folder will be used. One can choose a difference license
folder by adding the "-license [folder path]" to the command. The search of license folder is
carried out by the software in the following descending order:

1) If a license folder is specified, use it.

2) If not specified, use a key in Window's registry to locate the folder on Windows.
3) Use the default folder on other non-Windows platforms.
4) If the above fails, try to use the current working folder.

When integrating i2k Retina library or working with the command-line executable, it is
recommended that the same license folder shall be used in all situations, whether it is
mosaicking, license activation, deactivation or license query. Otherwise, different or even
conflicting behaviors may be observed.

Example 1. Show current license status

da_i2k_align_exec_v2 -license_status –license /my/path/to/license

The command will show the current license status without running on any images. The
output looks similar to the following during the trial:
…
i2k Align Trial 2.1.6Build426 library is initialized.
i2k library is initialized.
After calling available_functions(): return code=0
state=InTrial
license_type=Trial
num_days_remaining=15
num_runs_remaining=75
product_name=i2k Align Trial
customer_name=
company_name=
functions=Register:Montage:Align:AlignSeq:ProFunctions:MultiBand:
Sync:MemFunctions
image_types=Retinal:Photographic:NonPhotographic:MultiModal
are_retinal_images_allowed=1

Number_simlutaneous_sessions_allowed=1
Quitting after license status is shown.

Or the output may look similar to the following if a license is in place:

…
i2k Align Pro 2.1.6Build426 library is initialized.
i2k library is initialized.
After calling available_functions(): return code=0
state=Activated
license_type=Perpetual
num_days_remaining=-1

DualAlign LLC 2008-2014 ©

 num_runs_remaining=-1
product_name=i2k Align Pro
customer_name=John Stewart
company_name=My Company
functions=Register:Montage:Align:AlignSeq:ProFunctions:Sync:Transform
image_types=Retinal:Photographic:NonPhotographic:MultiModal
are_retinal_images_allowed=1

Number_simlutaneous_sessions_allowed=2
Quitting after license status is shown.

The license_type can have the value of Trial, Perpetual, Subscription, or Token. The state
represents the current state of the license. It can have value of InTrial (during trial), Expired,
Activated (a license is in place). Both the num_days_remaining and num_runs_remaining can
be -1, 0, or positive integers. -1 represents unlimited value (as in the case of perpetual license).
0 represents no value left and usually results in license expiration. Positive integers represent
the remaining value.

The values of customer_name and company_name are extracted from the license. These
values will be empty during trial.

The image_types represents the image types allowed to be used and the functions
represents the functionalities allowed to be used. The multiple values are separated by ‘:’ mark.

The Number_simlutaneous_sessions_allowed (misspelled) represents the number of

sessions and processes of i2k Align that can be launched concurrently on one computer.

Example 2. Activate license

da_i2k_align_exec_v2 -activate 1234-5678-1234-5678

To use this, simply substitute in the 16-digit activation code that you received. The code
1234-1234-1234-1234 shown in the command is for demonstration purpose only and will not
work. Remember to supply the license folder with -license /my/path/to/license if a
different one is used.

Example 3. Manual activation

If Internet connection is not available or is blocked, users may activate the i2k Align license
using a manual process that requires sending information from a different, internet-accessible.
This requires three steps to exchange the necessary information with the DualAlign team:

a) Obtain machine id
da_i2k_align_exec_v2 -machine_id

The command will produce output like

...
i2k library is initialized.
Please email the following machine id to support@dualalign.com:
FgAAAAAAAABzZXJpYWxpemF0aW9uOjphcmNoaXZlCQAEBAQIAQAAAAAAAAAAAAAAAAABA
AAAAAADAAAAAAAAAAAAAAAAAAAAAAUAAAAAAAAAACcTjrgFAAAAAAAAAAAmgnDwBQAAAA
AAAABwcbxhWwAAAAACAAAA/wIAAAAIAFYAAAAAAAAASUQ6R2VudWluZUludGVsIFN0cDo
1IE1kbDoxMCBGbWw6NiBCZDpJbnRlbChSKSBDb3JlKFRNKSBpNyBDUFUgICAgICAgICA5
MzAgIEAgMi44MEdIeiA=

DualAlign LLC 2008-2014 ©

 b) Email the machine id.
Simply copy the above machine id into an email that contains your activation code, and send
it to support@dualalign.com.

c) Final Activation
You will receive the license file back in a return email. Since this is done manually, it may
take a bit of time. Save the license file from the email, copy it to the machine running i2k Align,
and apply the following command:
da_i2k_align_exec_v2 -activate 1234-5678-1234-5678 -manual_file
c:\abc\license.txt –license /my/path/to/license

Replace c:\abc\license.txt with the path to the saved license file. The activation code must
be supplied as well. The program will validate the activation code and the license file, write in
the license folder, and the print a message saying that the activation is successful. The “-
license /my/path/to/license” is needed when using a non-default license folder. If this
switch is not present, the license file will be written in the default license folder.

Example 4. Deactivation
The command to deactivate a license is
da_i2k_align_exec_v2 -deactivate

Note that it requires the Internet connection to complete the deactivation procedure.
Please remember to supply the license folder with -license /my/path/to/license if a
different one is used.

This command is particularly useful to transfer license to a new computer. To do so, first
deactivate from the current computer. Then activate again on a new computer. The
deactivation step essentially returns the license to DualAlign’s licensing server and makes it
available to be used again.

Summary of switches
We introduced three switches in this section:
 -license [path to license folder]: look for license file in the given license folder.
 -license_status: show the licensing status if the switch is present. The program will
quit after the status is shown.
 -activate [activation code]: activate the software with the given 16-digit activation
code. It requires Internet connection.
 -machine_id [Boolean]: show the machine ID and quit if the switch is present.
 -manual_file [path to the license file]: Supply the license file during manual
activation.
 -deactivate [Boolean]: deactivate the license and quit if the value is 1.

Advanced Switches

DualAlign LLC 2008-2014 ©

 In this section, we will go through some of the more advanced switches.

-target [image file name]

This switch is used to specify a target (or anchor) image whose coordinate system will
become the output coordinate system. This target image must be one of the input images
supplied to the software. If we want one of the images to be fixed, i.e., same as the original
image, this is the switch to use.
Please note that the top-left corner of mosaic / aligned images does not correspond to the
top-left corner of the chosen target image in order to accommodate other images warped in this
coordinate system.

-save_xforms
This switch turns on saving of the transform and matches files. The format of these two files
is described in xforms-and-matches.pdf.

The file names will have appendix of xform- and matches-, followed by the phrase as in the
mosaic image file.

Surrogate Image

-replace_list [file name]

This switch is to specify surrogate images. A surrogate image is used to replace an input
image for the output purpose. The file is a plain-text file that has image file names in
pairs with each name occupying a line. Within a pair, the first name is one of the input
images and the second is the surrogate image. Here is an example:
a1.tiff
a2.tiff

b1.tiff
b2.tiff

a1.tiff and b1.tiff must have been specified in the input images. a2.tiff will replace a1.tiff
and b2.tiff will replace b1.tiff for the final output, such as in mosaic or in aligned
images. The warping of images is still based on the registration results which was
computed from the input images.

Process Multi-band images

-num_bands [integer]
i2k Align Pro is capable of processing multi-band images. It will first align different
band images from the same viewpoint and then align different viewpoints by matching
the same bands. To make use of this feature, you will need to specify number of bands
first using this switch.

In the presence of switch, i2k Align Pro assumes the input images are first grouped by
bands. For instance, if there are 3 bands and 6 input images, e.g., 1.tiff to 6.tiff, software

DualAlign LLC 2008-2014 ©

assumes there are 2 groups, each of which contains 3 band images. 1.tiff will be assigned
to band1, 2.tiff to band2, and 3.tiff to band3. The next image, 4.tiff, will start from the
first band again.

-band_names [file name]

This switch specifies a plain-text file that contains the names of bands, one name per line.
The number of bands is derived from the total of non-blank lines in this file.

Please see -num_bands for the details. The band names will be used in the output of
Mosaic Sequence.

Illumination Correction for Aligned Images Output

-align_illum
This switch turns on illumination correction when the output is a set of aligned images (-
output_type 1). The default is not to applied illumination correction and preserves the original
appearance. But there are cases, for instance, between retinal fundus color images, where the
comparison is more meaningful with the illumination correction.
This switch does not affect other output types, including mosaic output.

Supply Region of Interest

We can use two switches to specify Region of Interest (ROI) within i2k Align/Retina Pro. The
first switch “-roi [file name]” specifies the ROI prior to image registration. The effect lasts
throughout the program or until the ROI is changed by the switch “-roi_output [file name]”.

-roi [file name]

This switch takes a text file name as the argument. The text file consists of a number of ROI
specifications, with each specification composed of two lines: the first line is the image file name
(must match one of the input image names) and the second is the ROI description. Blank lines
will be ignored. There are a few methods of describing an ROI:
 NONE: do not use any ROI. In other words, the ROI is the whole image.
 AUTO: detect ROI automatically. When image type is retinal, the software will
automatically detect the fundus mask and use it as the ROI.
 IMAGE [image file name]: the ROI is specified by the given image. It must be a gray
scale image with the same resolution as the corresponding input image. Pixels with
non-zero intensities (e.g., 255) are inside the ROI.
 RECT x1 y1 x2 y2: ROI is the rectangle given by the two corners in the 0-based image
coordinate system. (x1, y1) is the upper-left corner and (x2, y2) is the bottom right
corner. They must satisfy x1 < x2 and y1 < y2.
 CIRCLE x y r: ROI is the circle given by the center, (x,y) and radius, r. These values
shall be in the image coordinate system.
 BACKGROUND_INTENSITY value: eliminate peripheral homogenous region using
the given background intensity value. The remaining area(s) are the ROI. This
method is particularly useful for geo-referenced / satellite images in remote sensing
where peripheral areas are usually black.

DualAlign LLC 2008-2014 ©

 If all images fall into the same method (not necessarily the same ROI), we can also use the
keyword “ALL” as the file name.

All ROI specifications are carried out in the order they are listed. In other words, a latter
entry overwrites a former one.

Here is an example of the roi text file:

ALL
BACKGROUND_INTENSITY 0

b.tiff
IMAGE b_mask.png

c.jpg
NONE

d.jpg
RECT 0 0 400 300

In this example, all images other than b.tiff, c.jpg and d.jpg will have the ROI detected based
on the background intensity. The ROI detection is carried out on individual images. Thus,
different images may have different ROI.

-roi_output [file name]

In some cases, we would like to generate output (e.g., mosaic or aligned images) with a
different ROI. For example, we can register images using a custom ROI and then generate output
using the full image. Thus, we can use “-roi [file name]” switch to specify the ROI used in image
registration and then use “-roi_output [file name]” switch to overwrite the ROI for generation of
the mosaic/align output.

“-roi_output [file name]” takes a text file in the same format. It is applied after image
registration and prior to output generation.

Multi-row Mode
When registering a large number of images, prior information such as image acquisition
pattern can help i2k Align Pro to quickly identify image pairs that need to be registered and thus
have the advantage of time saving and robustness.
One particular image acquisition pattern is what we call “Multi-row Mode” where images
are acquired by sweeping along a row and then another.

-use_multirow
This Boolean switch instructs i2k Align Pro to enter Multi-row Mode. In other words, the
software will first register consecutive images in a row and then register images between rows.
This switch shall be used with “-list [file name]” switch where the list file can contain the row
separation information.
Taking the following images as an example:

DualAlign LLC 2008-2014 ©

 08200306.JPG 08200307.JPG 08200308.JPG 08200309.JPG 08200310.JPG

08200315.JPG 08200314.JPG 08200313.JPG 08200312.JPG 08200311.JPG

Table 1 Input images for Multi-row Mode

First we create an image list file as list.txt:

08200306.JPG
08200307.JPG
08200308.JPG
08200309.JPG
08200310.JPG

08200311.JPG
08200312.JPG
08200313.JPG
08200314.JPG
08200315.JPG

Notice the extra blank line between image 08200310.JPG and 08200311.JPG. This blank line
informs the software the end of a row and starting of a second row. The software assumes the
beginning of a row overlaps with the beginning of a second row (or its neighboring rows, see
switch -multirow_max_index_offset) and the end of a row overlaps with the end of a second
row. The direction can be changed by using –multirow_serpentine switch.
Then we can simply run the command as:
da_i2k_align_exec_v2 -use_multirow -multirow_serpentine -list
list.txt -layout 1

At the end of the run, the software creates a mosaic that looks like the one below:

Table 2 Mosaic created from images in Table 1

-multirow_serpentine

DualAlign LLC 2008-2014 ©

 This switch applies to images acquired in lawn-mower / serpentine pattern. In other words,
the beginning of a second row has overlap with the end of the first row, such as the images
shown in Table 1.

-multirow_max_index_offset [integer]
This switch instructs the software how to match between rows. The default value is 0. In
other words, it assumes images are taken in grid-like pattern --- an image on a second row is
only matched to the corresponding image on the first row. The actual correspondence, whether
the beginning or the end of the first row, depends on whether -multirow_serpentine switch is
used.
Increasing this value will enlarge the range where images are matched between rows. For
instance, if this value is 2, an image on a second row will be matched to the corresponding
image on the first row, its left two neighbors, and its right two neighbors.

Utility Switches

-thread [integer]
This switch specifies number of threads to use during the computation. The default value
corresponds to the number of physical processor units available. On Intel-based platforms, it is
the number of cores.

-mem [integer]
This switch specifies the maximum amount of memory to be used in the unit of mega-bytes. It
shall be noted that specifying a number larger than the amount of physical memory may lead to
abortion caused by running out of memory.

It shall also be noted that on 32-bit Windows, this value shall not be larger than 1300 (i.e.,
1.3Gb). 32-bit Windows has a hard limit the each process can use maximum 2GB memory space.
But because of the kernel and separate memory pools for each dll, the practical amount is much
less and 1.3Gb is a reasonable number to use.

-log_level [integer]
This switch specifies the log level of the run and shall be used for problem diagnosis. The
default value is 0, which turns of logging. The maximum number is 10. The value of 3 or greater
will substantially slow the program due to output of log and associated intermediate images.

-log_folder [folder path]

This switch specifies the log folder. See -log_level for details.

-log_cout [file name]

DualAlign LLC 2008-2014 ©

This switch redirects the terminal output to the given file. It is equivalent to piping the output
with “>file_name” appended at the end of command.

-loop [integer]
This switch specifies the number of iterations. The default is one (1). In other words, the
operation is carried out once and then quit. As the program behavior is deterministic, there is
rarely any chance to use this switch other than monitoring the memory consumption.

-monitor_time [interger]
This switch specifies the time interval, in the number of millisecond, to poll the current status.
The progress output will be written to the standard error channel of the terminal.

Final Notes
Sometimes a file name may contain one or more white spaces. To supply such a file to the
executable and to prevent OS breaking it into multiple arguments, one needs to quote the
complete file name, for instance, “my image.png”. Otherwise, the executable will receive two
separate arguments from the operating system, one is “my” and the other is “image.png”.

DualAlign LLC 2008-2014 ©