mauro/ale
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
Mauro Torrez
2022-07-30 14:46:04 -03:00
commit 47650131de
312 changed files with 212465 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
doc/user/3d/index.xml Normal file
View File

@@ -0,0 +1,210 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<appendix id="user-3d"><title>3D Scene Reconstruction (Experimental)</title>
<p>In general, 3D modeling of scenes may allow handling of cases that per-frame
projective transformations do not allow, such as registering frames having
different viewpoints over a non-flat or specular scene, or recovery of depth
from frames having different viewpoints. ALE's implementation of 3D scene
reconstruction is considered experimental in versions prior to 0.8.3.</p>
<s><t>Models</t>
<p>The method of modeling used in 0.8.2 and later is spatial subdivision based on
regions of interest, followed by iterative update of the estimated occupancy
and color of each region of interest. (For a general discussion of occupancy,
see Hans Moravec's work on depth recovery.) In 0.8.1, the method of modeling
is decomposition and deformation of a surface. In earlier versions, a
per-frame, per-pixel model of depth is used.</p>
</s><s><t>Recovered Color and Depth Output</t>
<p>The color and depth output options provide a reconstruction of the scene as
viewed from a particular frame's vantage point, or from an arbitrary camera
view [0.8.2 and later]. In 0.8.2 and later, normalization of output values by
accumulated occupancy can optionally be disabled for unfiltered views. Version
0.8.3 adds support for options --et and --3dpx, which can be useful for 3D
cropping applications. --et specifies the minimum accumulated weight required
for a pixel to be defined, allowing refinements of crops based on clip planes
(<code>--rc</code> and <code>--fc</code>) established prior to scene
reconstruction, whereas --3dpx specifies a region of space to be removed
after scene reconstruction. 0.8.3 uses depth image pixels to determine such spatial regions,
leaving the pixels undefined, whereas 0.8.4 removes scene geometry prior to
rendering, allowing rendering of background objects after the foreground has been removed.</p>
<pre>
--3dv &lt;n> &lt;o> Render, to file &lt;o>, colors as viewed from frame &lt;n>.
--3dd &lt;n> &lt;o> Render, to file &lt;o>, depths as viewed from frame &lt;n>.
--3dvp &lt;args> &lt;o> Render, to file &lt;o>, colors viewed with projective &lt;args>. [0.8.2 and later]
--3ddp &lt;args> &lt;o> Render, to file &lt;o>, depths viewed with projective &lt;args>. [0.8.2 and later]
&lt;args> are W H V x y z P Y R:
W image width.
H image height.
V camera view angle.
x translation x component.
y translation y component.
z translation z component.
P rotation around x-axis.
Y rotation around y-axis.
R rotation around z-axis.
--occ-norm Normalize output with accumulated occupancy. [default] [0.8.2 and later]
--occ-nonorm Don't normalize output with accumulated occupancy. [0.8.2 and later]
--et &lt;x> Set encounter threshold &lt;x> for defined pixels. [default is 0] [0.8.3 and later]
--3dpx &lt;args> Exclude a specified spatial volume following full-scene [0.8.3]
reconstruction, assuming a single depth at each point
in the output. &lt;args> are:
&lt;xmin> &lt;xmax> &lt;ymin> &lt;ymax> &lt;zmin> &lt;zmax>
--3dpx &lt;args> Exclude a specified spatial volume following full-scene [0.8.4 and later]
reconstruction. &lt;args> are:
&lt;xmin> &lt;xmax> &lt;ymin> &lt;ymax> &lt;zmin> &lt;zmax>
</pre>
</s><s><t>Filtering [0.8.4 and later]</t>
<p>Version 0.8.4 adds support for filtering color values from the inputs to
produce final color renderings. This is now the default. Determining surface
depth and gradient for filtering the inputs draws from a set of depth pixels
within a disc whose radius can be specified with the --3d-dmr and --3d-fmr
options.</p>
<p>Filtering color from views distributed on a disc (about the camera origin) of
specified aperture allows simulation of focus effects; such effects can be
controlled with the --focus option.</p>
<pre>
--3d-filter Use filtering for 3D color output. [default]
--3d-nofilter Don't use filtering for 3D color output.
--3d-dmr &lt;x> Set radius for filtering median depth to &lt;x> [default 0]
--3d-fmr &lt;x> Set radius for filtering median diff to &lt;x> [default 0]
--focus &lt;ft> &lt;op> Create focus region with type &lt;ft> and options &lt;op>:
Focus type:
d &lt;d> focus at distance &lt;d>
p &lt;x> &lt;y> focus at point (x, y)
Space-separated options may include zero or more of:
ci=&lt;ci> camera index [default 0]
fr=&lt;fr> focal range [default 0]
ht=&lt;ht> horizontal tilt gradient [default 0]
vt=&lt;vt> vertical tilt gradient [default 0]
ap=&lt;ap> aperture diameter [default 3]
sc=&lt;sc> sample count [default 3]
sx=&lt;sx> start x coordinate [default -Inf]
ex=&lt;ex> end x coordinate [default Inf]
sy=&lt;sy> start y coordinate [default -Inf]
ey=&lt;ey> end y coordinate [default Inf]
sd=&lt;sd> start depth [default 0]
ed=&lt;ed> end depth [default Inf]
sr=&lt;sr> view sample randomization:
aperture per aperture [default]
pixel per pixel
fs=&lt;fs> focal statistic, one of:
mean mean of views [default]
median median of views
</pre>
</s><s><t>Camera parameter adjustment</t>
<p>In versions 0.8.1 and later, camera parameters can be adjusted according to
control points to decrease the error between points in different frames.
Perturbation bounds for adjustment can be specified, including an additional
upper bound on view angle perturbation, and a stereo threshold can be set for
discarding control points after adjustment is complete. An initial camera view
angle can also be specified. Versions 0.8.2 and later allow calculation of
error by median rather than mean, and also allow disabling of adjustment of
orientation and/or position.</p>
<pre>
--view-angle &lt;x> Set the initial diagonal view angle to &lt;x> degrees.
(Default is 43.7 degrees or device-specific.)
--cpp-upper=&lt;x> Set upper bound &lt;x> for camera parameter perturbation, [0.8.1 and later]
in pixels or degrees [default is 32]
--cpp-lower=&lt;x> Set lower bound &lt;x> for camera parameter perturbation, [0.8.1 and later]
in pixels or degrees [default is 0.125]
--va-upper=&lt;x> View-angle perturbation upper bound in degrees [default is 32] [0.8.1 and later]
--st &lt;x> Control point stereo threshold is &lt;x> pixels. [default is 4] [0.8.1 and later]
--cpp-err-mean Use RMS error to determine camera parameters. [default] [0.8.2 and later]
--cpp-err-median Use median error to determine camera parameters. [0.8.2 and later]
--vp-adjust Adjust the view point [default] [0.8.2 and later]
--vp-noadjust Do not adjust the view point [0.8.2 and later]
--vo-adjust Adjust the view orientation [default] [0.8.2 and later]
--vo-noadjust Do not adjust the view orientation [0.8.2 and later]
</pre>
</s><s><t>Transformation data files [0.8.2 and later]</t>
<p>Transformation data file options allow reading and writing of camera position,
orientation, and view angle information.</p>
<pre>
--3d-trans-load=x Load initial transformation settings from file x [0.8.2 and later]
--3d-trans-save=x Save final transformation data in file x [0.8.2 and later]
</pre>
</s><s><t>Transformation data file format [0.8.2 and later]</t>
<p>The transformation data file uses the following format, starting with a version
command, and then describing view angle and euclidean transformation of each
frame in turn:</p>
<pre>
W 0
V &lt;view angle>
E &lt;width> &lt;height> &lt;X> &lt;Y> &lt;Z> &lt;P> &lt;Y> &lt;R>
V &lt;view angle>
E &lt;width> &lt;height> &lt;X> &lt;Y> &lt;Z> &lt;P> &lt;Y> &lt;R>
.
.
.
V &lt;view angle>
E &lt;width> &lt;height> &lt;X> &lt;Y> &lt;Z> &lt;P> &lt;Y> &lt;R>
</pre>
</s><s><t>Model costs [0.8.1 only]</t>
<p>After the cameras are adjusted, a 2D surface is decomposed and deformed to
reduce local cost measures, calculated from angles between neighboring
triangles, edge lengths, and differences in color between different views.
Multipliers for edge length and angle costs can be specified on the
command line.</p>
<pre>
--ecm &lt;x> Set edge length cost multiplier &lt;x>. [default is 0.001] [0.8.1 only]
--acm &lt;x> Set angle cost multiplier &lt;x>. [default is 0.001] [0.8.1 only]
</pre>
</s><s><t>Model rules [0.8.2 and later]</t>
<p>In versions 0.8.2 and later, clip planes can be specified, and a color falloff
exponent for pairwise occupancy estimation can be specified. Larger exponents
are more forgiving of color differences between pixels in different frames.
In versions 0.8.3 and later, error contributions from cameras outside of the
generating pair can be assigned non-zero multipliers (<code>--tcem</code>), the
number of occupancy and color update iterations can be specified
(<code>--oui</code>), the number of points in space generated for each pixel
pair can be specified (<code>--pa</code>), and the type of frame pairings can
be specified (<code>--pc</code>).</p>
<pre>
--di-upper &lt;x> Decimate primary input resolution by at most 2^x [default is 0] [0.8.4 and later]
--di-lower &lt;x> Decimate input resolutions by at least 2^x [default is 0] [0.8.4 and later]
--do-try &lt;x> Decimate output resolution by 2^x if possible [default is 0] [0.8.4 and later]
--oc Clip scene to output regions. [0.8.4 and later]
--no-oc Do not clip scene to output regions. [default] [0.8.4 and later]
--fc &lt;x> Set front-clip to &lt;x> (0 &lt; x &lt; 1) [default is 0] [0.8.2 and later]
--rc &lt;x> Set rear-clip to &lt;x> (1 &lt; x &lt; inf) [default is inf] [0.8.2 and later]
--fx &lt;x> Set falloff exponent to &lt;x> [default is 0] [0.8.2 and later]
--tcem &lt;x> Set third-camera error multiplier to &lt;x> [default is 0] [0.8.3 and later]
--oui &lt;x> Set occupancy update iterations to &lt;x> [default is 10] [0.8.3 and later]
--pa &lt;x> Set pairwise ambiguity to &lt;x> [default is 3] [0.8.3 and later]
--pc &lt;type> Set the type of pairwise comparisons: [0.8.3 and later]
auto Determine comparisons automatically. [default]
all Perform all comparisons.
</pre>
</s>
</appendix>

264
doc/user/alignment/index.xml Normal file
View File

@@ -0,0 +1,264 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-alignment"><title>Alignment</title>
<p>Alignment compares each supplemental frame in the sequence with an intermediate
incremental rendering known as the alignment reference image. Based on this
comparison, a transformation is assigned to the supplemental frame. Many
different transformations can be assigned before alignment of the frame is
complete.</p>
<p>This manual page offers an overview of alignment options; see also <xref
linkend="user-tdf"/>.</p>
<s><t>Transformations</t>
<p>The variables used to adjust alignment are called transformations; they map
points from the source image coordinate system to a target coordinate system
(the rendering coordinate system).</p>
<p>ALE supports three transformation classes -- translational, euclidean, and
projective -- as well as barrel/pincushion distortion correction. The
translational class applies only translations to the inputs, changing only the
positions of images; the Euclidean class applies translations and rotations;
and the projective class applies general projective transformations.
Additionally, barrel/pincushion distortion correction can be applied to each
frame. The Euclidean class is most appropriate for use with scanners, or as a
first pass for projective transformations. The projective class and
barrel/pincushion distortion correction are most appropriate for use with
cameras. Except when capturing flat scenes, ALE does not correct perspective
changes, so movement of cameras should ideally be constrained so that no large
translations occur.</p>
<s><t>Transformation Class Options</t>
<ll>--translation Only adjust the position of images
--euclidean Adjust the position and orientation of images [default]
--projective Use projective transformations. Best quality, but slow.
</ll>
<p>For more information on barrel distortion correction, see <xref linkend="user-tdf"/>.</p>
</s><s><t>Transformation data file options</t>
<p>Transformations used in alignment can be loaded from, or saved to, a
transformation data file.. This can be useful when performing alignment in
several passes, or when refining rendering options. A transformation data file
is required for barrel/pincushion distortion correction. For more information,
see <xref linkend="user-tdf"/>.</p>
<ll>--trans-load=x Load initial transformation settings from file x
--trans-save=x Save final transformation data in file x
</ll>
</s><s><t>Alignment following</t>
<p>The --follow option hints that frames tend to be more closely aligned with
adjacent frames in the sequence than with the original frame. --identity
indicates that frames tend to closely align with the original frame. These hints can be
useful even when initial alignment information is loaded from a file.</p>
<ll>--follow Frames align closely with their predecessor. [default]
--identity Frames align closely with the original frame.
</ll>
</s></s><s><t>Match statistics</t>
<p>The match statistic indicates how well a transformed frame aligns with the
alignment reference image; it is used to select or reject transformations
during alignment. After alignment of a particular frame is complete, ALE
displays the corresponding final match statistic. If the value is close to
100%, then the frames are well aligned; very low values can indicate
misalignment; but even frames that are very well aligned typically do not
achieve 100% alignment. For improving image quality, ALE works most
effectively when match values are lower than 100%.</p>
<s><t>Match threshold</t>
<p>A match threshold can be specified; no images with final match statistics
falling below this threshold will contribute to the final output.</p>
<ll>--threshold=x Min. match threshold; a perfect match is 100. (0 is default)
</ll>
</s><s><t>Alignment failure</t>
<p>When an image fails to meet the match threshold, a transformation is still
assigned to the frame (e.g., for writing to a <link
linkend="user-tdf">transformation data file</link>). The assigned
transformation can be either the optimal alignment found (this is default) or
the default transformation.</p>
<ll>--fail-optimal Frames beneath threshold are aligned optimally. [default]
--fail-default Frames beneath threshold keep their default alignment.
</ll>
</s><s><t>Alignment error metric exponent</t>
<p>The function calculated at each pixel to determine the match statistic is of
the form <i>(a-b)<sup>x</sup></i>. The exponent value <i>x</i>
is 2 by default. Larger numbers give greater influence to smaller image
features.</p>
<ll>--metric=x Set the alignment error metric exponent. (2 is default)
</ll>
</s><s><t>Alignment Channel Options</t>
<p>In calculating the per-pixel error metric, there are three ways in which ALE
can handle color channels. By default, ALE adds the channels before
calculating the match, but it can also be configured to rely solely on the
green color channel, or to use all three channels separately.</p>
<ll>--align-all Align images using all color channels
--align-green Align images using the green channel
--align-sum Align images using a sum of channels [default]
</ll>
</s><s><t>Monte Carlo Alignment</t>
<p>As aligning large images can take a long time if all pixels are examined, it
is often desirable to examine a smaller subset of pixels. The Monte Carlo
alignment option samples a subset of pixels, specified as a percentage of the
total pixel count, with smaller numbers providing faster, but less precise,
alignment. For defaults, see <xref linkend="user-defaults"/>.</p>
<ll>--mc &lt;x&gt; Align using, on average, x% of available pixels (0 &lt; x &lt; 100)
--no-mc Align using all pixels.
</ll>
</s><s><t>Alignment weight map</t>
<p>Typically, measured differences at each pixel in the alignment reference
image contribute equally to the match statistic. To weight pixels differently,
a weight map can be used. The scale of the map should correspond with that of
the alignment reference image, and if the upper-left corner of the map does not
coincide with the upper-left corner of the first frame in the sequence, then a
non-zero offset should be specified to indicate the difference. See also <xref linkend="user-exclusion"/>.</p>
<ll>--wm &lt;f&gt; &lt;x&gt; &lt;y&gt; Use weight map image &lt;f&gt; at offset (&lt;x&gt;, &lt;y&gt;)
</ll>
</s><s><t>Frequency weighting</t>
<p>If ALE is compiled with FFTW support, then a high-pass-filtered version of
the alignment reference image can be used to weight reference image pixels'
contributions to the match statistic. Frequency limiting can occur as a
fraction of the highest horizontal frequency, the highest vertical frequency,
or the highest average frequency. Limit values should range between 0 (pass
all) and 1 (pass none). If any limit is assigned a value of 1, no alignment
will occur, since all frequencies will have been excluded. An output file can
optionally be specified for high-pass filtered data.</p>
<ll>--fl &lt;h&gt; &lt;v&gt; &lt;a&gt; High-pass filters: horizontal &lt;h&gt;, vertical &lt;v&gt;, average &lt;a&gt;.
--flshow &lt;o&gt; Write high-pass filtered data to file &lt;o&gt;.
</ll>
</s><s><t>Certainty weighting</t>
<p>Certainty weighting causes contributions to alignment error to be weighted
by certainty values.</p>
<ll>--cw Weight alignment error by certainty.
--no-cw Don't weight alignment error by certainty. [default]
</ll>
</s><s><t>Algorithmic weighting</t>
<p>This option writes the current alignment reference image and definition map
to specified files, executes a specified program with these arguments, and then
reads back alignment weights. This option requires POSIX libraries, and
requires that ALE have been built with POSIX support enabled.</p>
<ll>--wmx &lt;e&gt; &lt;r&gt; &lt;d&gt; Write reference &lt;r&gt;, definition &lt;d&gt;, execute `&lt;e&gt; &lt;f&gt; &lt;d&gt;`,
read weights &lt;r&gt; back.
</ll>
</s></s><s><t>Perturbation</t>
<p>The perturbation size determines the magnitude by which alignment parameters
are changed. The size is initially set to be large, allowing large changes in
alignment to be evaluated, and is reduced as the locally optimal alignment is
found for each size. When this size drops below a specified lower bound, the
frame is considered to be aligned.</p>
<s><t>Perturbation bounds</t>
<p>These options determine the upper and lower bounds for perturbation size. The
perturb-upper and perturb-lower bounds apply to rotation (in arclength),
translation (in pixels), and the movement of the boundaries of a projected
frame (in pixels). By appending the '%' character, values may optionally be
specified as a percentage of the number of pixels in the smallest image
dimension. The rot-upper bound disables rotational perturbation above a
certain perturbation size (in degrees). To disable alignment, set
perturb-upper to zero.</p>
<ll>--perturb-upper=x Perturbation upper bound pixels/arclength (14% is default)
('x%' uses a fraction of the smallest image dimension.)
--perturb-lower=x Perturbation lower bound pixels/arclength (.125 is default)
('x%' uses a fraction of the smallest image dimension.)
--rot-upper=x Rotation-specific upper bound in degrees (32.0 is default)
</ll>
</s><s><t>Barrel/pincushion distortion adjustment multiplier and rate</t>
<p>When using barrel/pincushion distortion parameters, any frame-to-frame
adjustments to these parameters are made in a manner dependent on the
perturbation size. A multiplier, the barrel distortion adjustment multiplier,
is used to determine the perturbation of these parameters, based on the generic
perturbation size. Additionally, the frame-to-frame rate of change of each
barrel distortion parameter can be limited to a specified maximum. To disable
frame-to-frame adjustment of barrel/pincushion distortion parameters, set
bda-mult to zero. Setting bda-rate to zero disables rate limitation.</p>
<ll>--bda-mult=x Barrel distortion adjustment multiplier (0.0001 is default)
--bda-rate=x Barrel distortion rate of change maximum (0.0004 is default)
</ll>
</s><s><t>Level of detail</t>
<p>Alignment at large perturbation sizes is usually carried out on
reduced-detail images. To disable this, set lod-max to
log<sub>2</sub>(perturb-upper).</p>
<ll>--lod-max=x LOD scale factor is max(1, (2^floor(x))/perturb) (1 is def.)
</ll>
</s><s><t>Perturbation Types (experimental)</t>
<p>Perturbations are normally performed in output image coordinates. To perform
perturbations in source image coordinates, specify <l>--perturb-source</l>.</p>
<ll>--perturb-output Apply perturbations in output image coordinates. [default]
--perturb-source Apply perturbations in source image coordinates.
</ll>
</s><s><t>Global Searching</t>
<p>In cases where important image features do not have sufficient overlap using
default alignment parameters (determined by <l>--identity</l> and
<l>--follow</l>), a number of translations can be applied to the default
parameters in order to find a new alignment starting point. Since this process
searches the entire region of the alignment reference image, it is called a
global (as opposed to local) search. To avoid misalignment, a minimum overlap
area can be specified. In versions 0.8.1 and later, the search type 'points'
searches for a control point metric minimum.</p>
<ll>--gs &lt;type> Set global search to &lt;type>, one of:
local Local alignment only [default]
inner Alignment reference image inner region
outer Alignment reference image outer region
all Union of inner and outer
central inner if below threshold or better; else, outer.
points Align by control points. Ignores gs-mo. [0.8.1 and later]
--gs-mo &lt;x> Set &lt;x> pixel min. overlap for global search. (16 is default)
</ll>
</s>
</s>
</chapter>

125
doc/user/chains/index.xml Normal file
View File

@@ -0,0 +1,125 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-chains"><title>Rendering Chains</title>
<p>The ALE incremental renderer is configured using rendering chains. Rendering chains are
constructed hierarchically from: invariants, SSFEs (scaled sampling filters
with exclusion), SSFs (scaled sampling filters), and sampling filters. Each of
these components is described in a section below. Defaults are outlined in the
final section.</p>
<s><t>Chains</t>
<p>The chain is the top level of the rendering chain hierarchy, and is composed of a
sequence of invariants. Syntactically, a chain is specified as a number of
invariants separated by commas:</p>
<p><code>invariant<sub>1</sub>,invariant<sub>2</sub>,invariant<sub>3</sub>,...,invariant<sub>n</sub></code></p>
<p>Each rendered pixel is assigned a value at the first invariant whose weight
exceeds the weight threshold, or otherwise at the last invariant in the sequence.</p>
<s><t>Chain Options</t>
<pre>
--wt &lt;w&gt; Set weight threshold for defined pixels [default is 0.8 in v0.8.0; 0.1 in v0.8.1 and later]
--dchain &lt;g&gt; Use chain &lt;g&gt; to render the default output.
--ochain &lt;g&gt; &lt;o&gt; Use chain &lt;g&gt; to render output file &lt;o&gt;.
--achain &lt;g&gt; Use chain &lt;g&gt; to render the alignment reference image.
--3d-chain &lt;g> Use chain &lt;g> by default to render 3d output. [0.8.4 and later]
</pre>
</s><s><t>Chain Examples</t>
<pre>
triangle:2 ALE 0.6.0 merging (roughly)
fine:box:1 Drizzling (roughly)
fine:sinc*lanc:8 High-frequency preservation
last:nex:sinc*lanc:8 Useful for video stabilization
fine:box:1,triangle:2 Multi-resolution rendering
fine:sinc*lanc:8,sinc*lanc:8 Multi-resolution rendering
</pre>
</s></s><s><t>Invariants</t>
<p>Invariants determine whether the rendered pixel value should be taken from a
single frame, or from an average of all frames. If from a single frame, it can
be the first, last, minimal, or maximal pixel value. Averages include mean
and, in versions 0.8.1 and later, the median. By default, the mean is used.
(Note that using the median value may require allocation of a quantity of
memory linear in the number of frames.) The syntax is as follows:</p>
<table>
<caption>Invariant types</caption>
<tr><th>Syntax</th><th>Description</th></tr>
<tr><td>avg:&lt;SSFE&gt;</td><td>Mean value</td></tr>
<tr><td>median:&lt;SSFE&gt;</td><td>Median value</td></tr>
<tr><td>max:&lt;SSFE&gt;</td><td>Maximum value</td></tr>
<tr><td>min:&lt;SSFE&gt;</td><td>Minimum value</td></tr>
<tr><td>first:&lt;SSFE&gt;</td><td>First value</td></tr>
<tr><td>last:&lt;SSFE&gt;</td><td>Last value</td></tr>
<tr><td>&lt;SSFE&gt;</td><td>Same as avg:&lt;SSFE&gt;</td></tr>
</table>
</s><s><t>Scaled Sampling Filter with Exclusion (SSFE)</t>
<p>SSFEs qualify SSFs, indicating whether exclusion regions should be honored.</p>
<table>
<caption>Scaled sampling filter with exclusion (SSFE) types</caption>
<tr><th>Syntax</th><th>Description</th></tr>
<tr><td>ex:&lt;SSF&gt;</td><td>Honor exclusion regions</td></tr>
<tr><td>nex:&lt;SSF&gt;</td><td>Don't honor exclusion regions</td></tr>
<tr><td>&lt;SSF&gt;</td><td>Same as ex:&lt;SSF&gt;</td></tr>
</table>
</s><s><t>Scaled Sampling Filter (SSF)</t>
<p>SSFs indicate whether filtering should occur at the resolution of the output
image, or at the minimum of input and output image resolutions. The former prevents loss
of details; the latter prevents aliasing.</p>
<table>
<caption>Scaled sampling filter (SSF) types</caption>
<tr><th>Syntax</th><th>Description</th></tr>
<tr><td>fine:&lt;SF&gt;</td><td>Filter at full output image resolution</td></tr>
<tr><td>coarse:&lt;SF&gt;</td><td>Filter at minimum resolution</td></tr>
<tr><td>&lt;SF&gt;</td><td>Same as coarse:&lt;SF&gt;</td></tr>
</table>
<s><t>SSF Options</t>
<pre>
--afilter &lt;s&gt; Use SSF &lt;s&gt; to interpolate points in alignment.
</pre>
</s></s><s><t>Sampling Filter (SF)</t>
<p>SFs are used to limit bandwidth. Primitive functions and pointwise multiplication of these
functions (windowing) are available.</p>
<table>
<caption>Sampling filter (SF) types</caption>
<tr><th>Syntax</th><th>Description</th></tr>
<tr><td>sinc</td><td>sinc filter</td></tr>
<tr><td>lanc:&lt;x&gt;</td><td>Lanczos, diameter x.</td></tr>
<tr><td>triangle:&lt;x&gt;</td><td>Triangle, diameter x.</td></tr>
<tr><td>box:&lt;x&gt;</td><td>Box, diameter x.</td></tr>
<tr><td>zero</td><td>Zero function</td></tr>
<tr><td>&lt;f&gt;*&lt;f&gt;</td><td>Pointwise multiplication (windowing)</td></tr>
</table>
</s><s><t>Defaults</t>
<p>ALE defaults are as follows:</p>
<pre> dchain Varies by <a href="../../defaults/">default setting</a>
achain Varies by <a href="../../defaults/">default setting</a>
afilter internal (approximates triangle:2)
</pre>
</s>
</chapter>

70
doc/user/cp/index.xml Normal file
View File

@@ -0,0 +1,70 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-cp"><title>Control Points</title>
<p>Control points are used for 2D and 3D alignment, and to constrain 3D scene
models. Control point data is loaded from a control point file. Scripts to
generate and manipulate control point files are included in the
<code>scripts</code> directory of the source distribution; the file
specification is outlined in the final section below.</p>
<s><t>Loading a Control Point File</t>
<p>The --cpf-load= option is used to load data from a control point file.</p>
<pre>--cpf-load=&lt;f> Load control point data from file &lt;f> [0.8.1 and later]
</pre>
</s><s><t>Control Point File Format (version 0)</t>
<p>The version 0 control point file format consists of a version command followed
by a sequence of control points, with one control point per line of the file.</p>
<pre>V 0
<i>Control Point 1</i>
<i>Control Point 2</i>
<i>Control Point 3</i>
.
.
.
</pre>
<p>Control points can be one of three types:</p>
<s><t>Type A control points</t>
<p>Type A control points specify a sequence of 2D points, one for each frame,
where each point is specified as a pair of floating point numbers. If there is
no data for a frame, then "nan" should be specified. E.g.:</p>
<pre>A 20 30 nan nan 10 10 10 15
A 23 22 25 25 nan nan nan nan
</pre>
</s><s><t>Type B control points</t>
<p>Type B control points specify a 3D coordinate. E.g.:</p>
<pre>B 10 30 -400
B 10 15 -425
</pre>
</s><s><t>Type C control points</t>
<p>Type C control points specify both 2D and 3D data. There is a single 3D point
specified, as well as one 2D point for each frame. The 3D point appears at the
end of the line. E.g.:</p>
<pre>C 20 30 nan nan 10 10 10 15 10 30 -400
C 23 22 25 25 nan nan nan nan 10 15 -425
</pre>
</s></s>
</chapter>

108
doc/user/defaults/index.xml Normal file
View File

@@ -0,0 +1,108 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-defaults">
<title>Default Settings</title>
<p>ALE offers five different default settings, each of which emphasizes
image quality, speed, or some other rendering characteristic, as follows:</p>
<ll>--q0 Low quality, high speed. [default]
--qn Low noise, moderate speed.
--q1 Moderate quality and speed.
--q2 High quality, low speed.
--qr Range-extended high quality.
</ll>
<p>These settings specify defaults for other options: <l>--dchain</l>,
<l>--achain</l>, <l>--3d-chain</l>, <l>--ips</l>, <l>--exp-extend</l>, and
<l>--cx</l>. For more information about these options, see <xref
linkend="user-rendering"/> and <xref linkend="user-3d"/>. Details regarding
these defaults are provided in the following sections.</p>
<s><t>High speed (--q0)</t>
<p><code>--q0</code> emphasizes speed over image quality. This option is default, and
sets other options' defaults as follows:</p>
<ll>--dchain fine:box:1,triangle:2
--achain triangle:2
--ips 0
--exp-noextend
--no-cx
--3d-chain fine:box:1,triangle:2
</ll>
</s>
<s><t>Low noise (--qn)</t>
<p><code>--qn</code> emphasizes low noise over resolution and rendering speed, and
sets the following defaults:</p>
<ll>--dchain sinc*lanc:6
--achain sinc*lanc:6
--ips 0
--exp-noextend
--no-cx
--3d-chain sinc*lanc:6
</ll>
</s>
<s><t>Balanced quality and speed (--q1)</t>
<p><code>--q1</code> balances image quality and rendering speed, offering higher
resolution than <code>--qn</code>. As this option uses median values, its memory use
is linear in the number of input images (rather than constant).</p>
<ll>--dchain median:fine:sinc*lanc:8,triangle:2
--achain triangle:2
--ips 0
--exp-noextend
--no-cx
--3d-chain median:fine:sinc*lanc:8,triangle:2
</ll>
</s>
<s><t>High quality (--q2)</t>
<p><l>--q2</l> favors image quality over rendering speed, offering greater
emphasis for high-frequency details than <l>--q0</l>, <l>--qn</l>,
or <l>--q1</l>. It depends on the <l>--lpsf</l> and
<l>--nlpsf</l> options, which can be set indirectly via the
<l>--device</l> option. (More information about these options can be
found in <xref linkend="user-psf"/> and <xref linkend="user-device"/>.) <l>--q2</l>
sets the following defaults:</p>
<ll>--dchain triangle:2
--achain triangle:2
--ips 4
--exp-noextend
--no-cx
--3d-chain median:fine:sinc*lanc:8,triangle:2
</ll>
</s>
<s><t>Range extension (--qr)</t>
<p><code>--qr</code> is similar to <code>--q2</code>, but offers improved
rendering when input images have been taken with unequal exposures. In other
cases, it may exacerbate noise in light and dark regions. This option sets the
following defaults:</p>
<ll>--dchain triangle:2
--achain triangle:2
--ips 6
--exp-extend
--cx 0.7
--3d-chain median:fine:sinc*lanc:8,triangle:2
</ll>
</s>
</chapter>

54
doc/user/device/index.xml Normal file
View File

@@ -0,0 +1,54 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-device"><title>Devices</title>
<p>Device specification is optional. Specifying a device allows automatic
determination of <a href="../rendering/psf/">point-spread functions</a>,
refinement of the correspondence between incident light and pixel values (e.g.
power law), and refinement of certainty calculation.</p>
<pre>--device &lt;d&gt; Set the capture device to &lt;d&gt;.
</pre>
<p>Available devices are as follows:</p>
<table>
<caption>Available device types</caption>
<tr><td>canon_300d_raw_linear</td><td>Canon 300D (Digital Rebel) raw, linear data.</td></tr>
<tr><td>canon_300d_raw_linear+50mm_1.4</td><td>Canon 300D with EF 50mm f/1.4 lens, unspecified aperture.</td></tr>
<tr><td>canon_300d_raw_linear+50mm_1.4@1.4</td><td>Canon 300D with EF 50mm f/1.4 lens, aperture 1.4.</td></tr>
<tr><td>canon_300d_raw_linear+50mm_1.8</td><td>Canon 300D with EF 50mm f/1.8 lens, unspecified aperture.</td></tr>
<tr><td>canon_300d_raw_linear+85mm_1.8</td><td>Canon 300D with EF 85mm f/1.8 lens, unspecified aperture.</td></tr>
<tr><td>ov7620_raw_linear</td><td>OmniView OV7620 in raw RGB, linear mode.</td></tr>
<tr><td>xvp610_640x480</td><td>IBM PC Camera Pro (XVP610) in 640x480 mode.</td></tr>
<tr><td>xvp610_320x240</td><td>IBM PC Camera Pro (XVP610) in 320x240 mode.</td></tr>
</table>
<p>These device options are described in more detail below.</p>
<s><t>Canon 300D (Digital Rebel)</t>
<p>Direct support for CRW files depends on the ImageMagick configuration, and
may not be available on all platforms. Dave Coffin's <a
href="http://www.cybercom.net/~dcoffin/dcraw/">dcraw</a> program, invoked with
arguments -d -4, will produce a raw, linear PPM file suitable for use with this
device configuration. JPEG files produced by the 300D cannot be directly used
as inputs for this configuration, since they are gamma-corrected rather than
linear.</p>
</s><s><t>OV7620</t>
<p>Standard OV7620 drivers may not include options for setting raw RGB or linear
modes. Linux users may apply a <a href="/ov7620/">driver patch</a> to access
these modes. Setting the module option <code>rgb_raw=2</code> places the camera
into the desired mode.</p>
</s><s><t>XVP610</t>
<p>Users of XVP610 cameras and Linux may wish to apply a <a href="/xvp610/">driver patch</a>. This version of ALE expects that this patch has been applied.</p>
</s>
</chapter>

49
doc/user/eppm/index.xml Normal file
View File

@@ -0,0 +1,49 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-eppm"><title>Extended PPM (EPPM) Files</title>
<p>EPPM is an extension to the PPM file format that allows specification of
metadata. The header of an EPPM file conforms to the following template:</p>
<pre>P6#E
# Tag1: Value
# Tag2: Value
# Tag3: Value
# .
# .
# .
Width Height Maxval
Data
</pre>
<p>Tags recognized by ALE are outlined below.</p>
<s><t>Black level</t>
<p>The black level tag specifies a value that should be subtracted from
all pixels in order to achieve linearity. A modified version of dcraw (<a
href="/darcs/dcraw">darcs repository</a>) can be used to generate files
containing this tag.</p>
<pre># Black-level: &lt;value&gt;
</pre>
</s><s><t>Exposure tags</t>
<p>Exposure tags can be used for determining tonal registration through
specification of shutter speed, aperture, and ISO sensitivity (or gain).</p>
<pre># Shutter: &lt;value&gt;
# Shutter: 1/&lt;value&gt;
# Aperture: &lt;f-number&gt;
# ISO: &lt;value&gt;
# Gain: &lt;value&gt;
</pre>
</s>
</chapter>

39
doc/user/exclusion/index.xml Normal file
View File

@@ -0,0 +1,39 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-exclusion"><title>Exclusion Regions</title>
<p>ALE offers exclusion regions as a way to disallow certain areas from being
used in alignment and (optionally) rendering. Spatial coordinates are
expressed in the rendering coordinate system (prior to scaling). In cases
where the default transformation is used with the original frame, this is
identical to the unscaled original frame coordinate system, taking the
upper-left corner to be (0, 0). Frame numbering begins with 0, which represents
the original frame.</p>
<s><t>Rectangular Exclusion</t>
<p>All specified volumes are excluded from alignment (except where they affect
the alignment reference image), and are excluded from rendering by default.
(See <xref linkend="user-chains"/> for information on how to ignore exclusion
regions.) Exclusion region syntax is as follows:</p>
<ll>--ex &lt;args&gt; Exclude a specified volume.
&lt;args&gt; are space-delimited horizontal,
vertical, and frame limits:
&lt;xmin&gt; &lt;xmax&gt; &lt;ymin&gt; &lt;ymax&gt; &lt;fmin&gt; &lt;fmax&gt;
</ll>
</s><s><t>Cropping</t>
<p>Cropping excludes the spatial complement of an area over a specified set of
frames.</p>
<ll>--crop &lt;args&gt; Exclude the spatial complement of an area over a
specified set of frames. &lt;args&gt; are:
&lt;xmin&gt; &lt;xmax&gt; &lt;ymin&gt; &lt;ymax&gt; &lt;fmin&gt; &lt;fmax&gt;
</ll>
</s>
</chapter>

67
doc/user/file/index.xml Normal file
View File

@@ -0,0 +1,67 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-file"><title>File Output</title>
<p>File output options determine the format in which rendered images are written,
and how frequently they are written. Depending on the compilation options used,
available file output options vary.</p>
<s><t>Output Color Depth</t>
<p>Output color depth of 8 or 16 bits of precision per color channel can be specified,
for 24-bit or 48-bit color, respectively. </p>
<ll>--8bpc Write 8 bit per channel output [default]
--16bpc Write 16 bit per channel output
</ll>
</s>
<s><t>Extension-based file type determination</t>
<p>If ALE has been built with ImageMagick support, then the output file type can
be determined automatically by file extension. This is the default behavior
for ImageMagick builds. The <code>--auto</code> flag explicitly specifies that
the default behavior should be used; it generates an error on builds compiled
without ImageMagick support. </p>
<ll>--auto Determine file type automatically
</ll>
</s>
<s><t>PPM Output</t>
<p>All builds of ALE support PPM output. PPM can be written in plain (ASCII) or
raw (binary) format. If ALE has been built without ImageMagick support, or if
the file type cannot be automatically determined by file extension, then raw
PPM output is used by default.</p>
<ll>--raw Write raw PPM output
--plain Write plain PPM output
</ll>
</s>
<s><t>Incremental Output</t>
<p>By default, ALE writes intermediate results periodically throughout the rendering
process. This behavior can be disabled, however, so that output is written only
after rendering is complete.</p>
<ll>--inc Produce incremental output. [default]
--no-inc Don't produce incremental output.
</ll>
</s>
<s><t>Undefined Values</t>
<p>By default, ALE colors undefined values black. To assign nearest-neighbor colors
to undefined pixels, the <code>--def-nn</code> option can be used.
</p>
<ll>--def-nn &lt;R> Use nearest-neighbor defined values within
radius &lt;R>, zero outside. Default radius is 0.
</ll>
</s>
</chapter>

57
doc/user/index.xml Normal file
View File

@@ -0,0 +1,57 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>
User Manual
</title>
</bookinfo>
<edit by="David Hilvert" in-year="2003"/>
<edit by="David Hilvert" in-year="2004"/>
<edit by="David Hilvert" in-year="2005"/>
<edit by="David Hilvert" in-year="2006"/>
<edit by="David Hilvert" in-year="2007"/>
<!--
- Main chapters
-->
<!-- overview chapter -->
<xi:include href="overview/index.xml"/>
<!-- ordinary invocations -->
<!-- (this topic is subsumed within the overview) -->
<!-- ordinary command-line options -->
<xi:include href="defaults/index.xml"/>
<xi:include href="file/index.xml"/>
<xi:include href="rendering/index.xml"/>
<xi:include href="alignment/index.xml"/>
<xi:include href="exclusion/index.xml"/>
<xi:include href="device/index.xml"/>
<xi:include href="ui/index.xml"/>
<xi:include href="chains/index.xml"/>
<xi:include href="psf/index.xml"/>
<xi:include href="cp/index.xml"/>
<!-- file formats -->
<xi:include href="eppm/index.xml"/>
<xi:include href="tdf/index.xml"/>
<!--
- Appendices
-->
<!-- experimental invocations -->
<xi:include href="scope/index.xml"/>
<!-- experimental options -->
<xi:include href="3d/index.xml"/>
</book>

185
doc/user/overview/index.xml Normal file
View File

@@ -0,0 +1,185 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter><title>Overview</title>
<section><title>Purpose</title>
<para>This manual describes program operation and command-line usage for ALE
version <ver/>.</para>
<!-- <para>For more information on ALE, see the <a
href="http://auricle.dyndns.org/ALE/">ALE Home Page</a>.</para> -->
</section>
<section><title>Parameter Meta-syntax</title>
<p>When describing parameter syntax, the following conventions are used in this manual:</p>
<table>
<caption>Parameter Meta-syntax</caption>
<tr>
<td><l>&lt;foo></l></td>
<td>A required parameter called <meta>foo</meta>.</td>
<td></td>
</tr>
<tr>
<td><l>[&lt;foo>]</l></td>
<td>An optional parameter called <meta>foo</meta>.</td>
</tr>
<tr>
<td><l>[&lt;foo>]*</l></td>
<td>Zero or more parameters <meta>foo</meta>.</td>
</tr>
</table>
</section>
<section><title>Command-line syntax for Image Processing</title>
<para>The following command-line invocation can be used to process a series of
frames into an output file:</para>
<ll>ale [&lt;option>]* &lt;original-frame> [&lt;supplemental-frame>]* &lt;output-file></ll>
<p>For experimental argument scope syntax, see <xref linkend="user-scope"/>.</p>
<s><t>Option Arguments</t>
<s><t>Default Settings</t>
<para>Certain basic modes of operation, emphasizing image quality, speed, or
other rendering characteristics, are established in the form of default
settings. For more information, see:</para>
<ul><li><xref linkend="user-defaults"/>
</li></ul>
</s>
<s><t>Other options</t>
<para>For information about other options, see:</para>
<ul><li><xref linkend="user-file"/>
</li><li><xref linkend="user-rendering"/>
</li><li><xref linkend="user-alignment"/>
</li><li><xref linkend="user-exclusion"/>
</li><li><xref linkend="user-device"/>
</li><li><xref linkend="user-ui"/>
</li><li><xref linkend="user-chains"/>
</li><li><xref linkend="user-psf"/>
</li><li><xref linkend="user-cp"/>
</li><li><xref linkend="user-3d"/>
</li></ul>
</s>
</s>
<s><t>Image Files</t>
<para>ALE can be configured at compile time to use one of two different file
handlers. Execute 'ale --version' to determine which file handler is being
used. The table below outlines the supported formats for each file handler.</para>
<table>
<caption>Supported image file formats</caption>
<tr><th>Version Message</th><th>File Types Supported</th></tr>
<tr><td valign="top">
<ll>File handler: ImageMagick</ll>
</td>
<td>
Input and output files can be any of the <ulink url="http://imagemagick.sourceforge.net/www/formats.html">formats</ulink> supported by
ImageMagick.
</td>
<td/>
</tr>
<tr><td valign="top">
<ll>File handler: PPM</ll>
</td><td>
Input files must be PPM, and output files are written as PPM.
</td></tr>
</table>
<para>Note that many external programs, including ImageMagick's <ulink url="http://www.imagemagick.org/">command line utilities</ulink>, can be used to
convert between PPM and other formats.</para>
<para>See the README included in the source distribution for more information about
compile-time configuration of file handlers.</para>
<p>Usage of extended PPM syntax for specifying image metadata is outlined in <xref linkend="user-eppm"/>.</p>
</s>
</section>
<section>
<title>Command-line syntax for Version Information</title>
<para>The following command-line invocation can be used to print version
information and build options:</para>
<ll>ale --version</ll>
<para>The following is sample output from this invocation:</para>
<ll>ALE Version: <ver/>
File handler: ImageMagick
Color data: SINGLE
Coordinate data: SINGLE
DFT: FFTW3
Threads: POSIX
Assertions: Enabled
Optimizations: Enabled</ll>
<para>The first line of output indicates the program version; the remaining
lines reflect the build options selected at compile time.</para>
<para>For more information about build options, see the README file included in
the source distribution.</para>
</section>
<section>
<title>Command-line syntax for Help Output</title>
<para>When invoked with no arguments, or an insufficient number of file arguments,
ALE outputs a help message specifying command-line usage and available help
topics. The following is a sample invocation:</para>
<ll>ale</ll>
<s><t>Help Topics</t>
<para>More information about specific help topics can be obtained with an invocation
of the following form:</para>
<ll>ale &lt;help option&gt;</ll>
<para>Available help options, and their corresponding help topics, are outlined
below:</para>
<ll>--hu Usage (this message).
--hq Default settings.
--hf Image files.
--he Exclusion regions.
--ha Alignment (not exposure-related).
--hr Rendering (not exposure-related).
--hx Exposure.
--ht Transformation data files.
--hc Control points.
--hl Filtering (PSFs, rendering chains).
--hd Devices.
--hi User Interfaces.
--hp Process details.
--hs Argument scope (Experimental).
--hv Video stream processing (Experimental).
--h3 3D Modeling (Experimental).
--hz Undocumented options.
--hA Concatenate all help pages.</ll>
</s>
</section>
</chapter>

45
doc/user/psf/index.xml Normal file
View File

@@ -0,0 +1,45 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-psf"><title>Point Spread Functions</title>
<p>The ALE Irani-Peleg renderer uses a point-spread function to model the optical
and electronic properties of the capture device used. The PSF can be specified
in terms of one linear and one non-linear component.</p>
<s><t>PSF specification</t>
<p>The PSF can be explicitly specified by using one or both of the psf options.</p>
<ll>--lpsf &lt;p> Set linear colorspace point-spread function to &lt;p>
--nlpsf &lt;p> Set non-linear colorspace point-spread function to &lt;p>
</ll>
<p>Available explicit point-spread functions are as follows:</p>
<ll>box=&lt;d> Set the PSF to a box filter with diameter &lt;d>.
circle=&lt;d> Set the PSF to a circular filter with diameter &lt;d>.
stdin Specify a custom filter at runtime.
stdin_vg stdin with vertically-oriented gaps after every 8th pixel.
&lt;p>+&lt;p> Summation of two functions
&lt;p>^&lt;p> Convolution of two functions.
&lt;n>*&lt;p> Multiplication by a scalar &lt;n>.
</ll>
<p>If a device is known to ALE, then its PSF can be implicitly set with the
<l>--device</l> option. (See the <a href="../../device/">device</a> page
for more information.) If a device is not specified, then the default linear
PSF component is <l>box=1</l>. The non-linear PSF component is disabled
by default.</p>
</s><s><t>Determining the PSF</t>
<p>The PSF can be approximated based on images of known scenes. The ALE source
distribution includes an experimental script that numerically approximates the
PSF in this way (<l>d2/render/psf/ale-psf-calibrate</l>). Other, more
efficient methods for approximating the PSF are likely possible, however.</p>
</s>
</chapter>

158
doc/user/rendering/index.xml Normal file
View File

@@ -0,0 +1,158 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-rendering"><title>Rendering</title>
<p>Rendering determines how an output image is constructed from a series of
aligned input frames, and occurs in two stages: incremental rendering and
Irani-Peleg rendering. Additional rendering options include exposure
registration, certainty-weighted rendering, spatial extension, range extension,
scaling, and Bayer pattern specification. Experimental options for video
stream processing are also available.</p>
<s><t>Incremental Rendering</t>
<p>The incremental renderer uses configurable rendering chains to determine the
output image. It can increase resolution and reduce aliasing, but it cannot
reduce blur. For more information on rendering chains, see <xref
linkend="user-chains"/>.</p>
</s><s><t>Irani-Peleg Rendering</t>
<p>The Irani-Peleg renderer uses configurable point-spread functions to model
blur, which is then reduced by an iterative backprojection technique. By
default, mean correction values are used at each iteration step, but median
correction can also be specified. For more information about point-spread
functions, see <xref linkend="user-psf"/>. For iteration defaults, see
<xref linkend="user-defaults"/>.
</p>
<ll>--ips &lt;i&gt; Run &lt;i&gt; iterations.
--ip-mean Use the mean correction [default]
--ip-median Use the median correction
</ll>
</s><s><t>Exposure Registration</t>
<p>By default, ALE adjusts an exposure model to minimize differences in tone
between frames. The option <l>--exp-noregister</l> indicates that exposure
should be assumed uniform across all frames. In this case, no adjustment is
performed. The option <l>--exp-meta-only</l> indicates that only exposure
information included in the image files should be used for registration.
Currently, EPPM is the only type of exposure metadata supported by this option;
for more information, see <xref linkend="user-eppm"/>.</p>
<ll>--exp-register Register exposure between frames. [default]
--exp-noregister Assume uniform exposure across all frames.
--exp-meta-only Use only image metadata for registering exposure.
</ll>
</s><s><t>Color Adjustment</t>
<p>To adjust the color of the output image (e.g., for white balance), the
--exp-mult= option can be used.</p>
<ll>--exp-mult=c,r,b Adjust all channels by &lt;c&gt;, red by &lt;r&gt;, and blue by &lt;b&gt;.
</ll>
</s><s><t>Certainty-weighted Rendering</t>
<p>The exposure model includes an associated certainty function, which
quantifies the reliability of sensor measurements. By default, this function
is raised to the zeroth power, to obtain uniform certainty for all measurements.
To specify a different certainty exponent, the option <l>--cx</l> can be
used. This option is best used in combination with <l>--exp-extend</l> (see
below) and <l>--ips</l>. For defaults, see <xref
linkend="user-defaults"/>.</p>
<ll>--cx &lt;x> Render with certainty exponent &lt;x>
--no-cx Render with uniform certainty.
</ll>
</s><s><t>Scale factor</t>
<p>Rendering with a larger scale factor results in image output of the specified
larger scale. Larger scales can improve alignment precision and output image
quality, but can also increase alignment and rendering times.</p>
<ll>--scale=x Scale images by the factor x, where x > 0. (1 is default)
</ll>
</s><s><t>Image extents</t>
<p>The --extend option records pixel data that falls outside of the region of the
first frame in the sequence. This can be useful for providing additional
alignment constraints or creating panoramic image mosaics. (For mosaics, see
also the description of the --follow option in <xref linkend="user-alignment"/>.)</p>
<ll>--extend Increase image extents to accommodate all pixel data.
--no-extend Don't increase extents; crop to original frame. [default]
</ll>
</s><s><t>Exposure extents</t>
<p>By default, ALE restricts the output range to that of the original frame.
To adjust the output range to accommodate the ranges of all input frames,
specify <l>--exp-extend</l>. For defaults, see <xref linkend="user-defaults"/></p>
<ll>--exp-extend Extend range to include all calculated values.
--exp-noextend Restrict to the original frame's range.
</ll>
</s><s><t>Bayer pattern specification</t>
<p>Many cameras sample only one color channel per output pixel. To ignore the
other channels, a Bayer pattern can be specified.</p>
<ll>--bayer &lt;b&gt; Set the Bayer pattern to &lt;b&gt;, one of:
(clockwise from top left pixel)
rgbg Red-green-blue-green
gbgr Green-blue-green-red
grgb Green-red-green-blue
bgrg Blue-green-red-green
none RGB-RGB-RGB-RGB
Default is none or device-specific.
</ll>
</s><s><t>Video stream processing (Experimental)</t>
<p>If a sequence of frames represents a video stream, then, in addition to
producing a single output image, ALE can also produce one or more sequences of
processed frames, corresponding to one or more occurrences of the
<l>--visp</l> option. This option has its own associated scaling option,
as well as an option to show excluded regions as dimmed wherever possible.</p>
<ll>--visp &lt;args&gt; Process a video sequence.
&lt;args&gt; are:
&lt;chain&gt; &lt;stabilization-type&gt; &lt;prefix&gt; &lt;suffix&gt;
&lt;chain&gt; is an incremental rendering chain.
&lt;stabilization-type&gt; is one of:
ma:&lt;x&gt; Moving average over 2*&lt;x&gt; + 1 frames
sf:&lt;x&gt; Stabilize to single frame number &lt;x&gt;
identity Same as ma:0
&lt;prefix&gt; is an output file prefix
&lt;suffix&gt; is an output file suffix
--visp-scale=&lt;x&gt; Use scale &lt;x&gt; for VISP output. (default is 1.0)
--exshow For single-invariant chains, show --ex regions dimmed.
</ll>
<s><t>Video stream processing example</t>
<p>To mimic the behavior of repeated applications of the 0.6.0
<l>--replace</l> option over a sequence of frames, the following
<l>--visp</l> option could be used.</p>
<ll>--visp last:nex:triangle:2 sf:0 frame .jpg
</ll>
<p>For better filtering, the following option could be used instead:</p>
<ll>--visp last:nex:sinc*lanc:6 sf:0 frame .jpg
</ll>
</s>
</s>
</chapter>

8
doc/user/scope/index.xml Normal file
View File

@@ -0,0 +1,8 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<appendix id="user-scope"><title>Argument Scope (Experimental)</title>
</appendix>

130
doc/user/tdf/index.xml Normal file
View File

@@ -0,0 +1,130 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-tdf"><title>Transformation Data Files</title>
<p>Transformation data files are useful when performing alignment in several
passes or refining rendering options, and are necessary for specifying
barrel/pincushion distortion parameters. They also offer a way to manually
specify alignment when ALE cannot automatically align images. </p>
<s><t>Multiple-pass alignment</t>
<p>To align images in multiple passes, load the saved results of each previous
pass, as follows:</p>
<pre>$ ale --trans-save=a.t &lt;first pass arguments&gt;
$ ale --trans-load=a.t --trans-save=b.t &lt;second pass arguments&gt;
$ ale --trans-load=b.t --trans-save=c.t &lt;third pass arguments&gt;
.
.
.
</pre>
</s><s><t>Rendering option refinement</t>
<p>To refine rendering options using the same alignment, first save the alignment
for the first option set, and then load the saved alignment information with
each subsequent option set, setting the perturbation upper bound to zero to
prevent a new alignment pass from occurring:</p>
<pre>$ ale --trans-save=a.t &lt;first option set&gt;
$ ale --trans-load=a.t --perturb-upper=0 &lt;second option set&gt;
$ ale --trans-load=a.t --perturb-upper=0 &lt;third option set&gt;
.
.
.
</pre>
</s><s><t>Alignment file syntax (version 2)</t>
<p>There are two varieties of alignment file syntax that are both read and written
by ALE 0.7.0. The most basic of these is version 2. Version 3 is slightly
more complex, and is covered in the next section.</p>
<p>At the highest level, version 2 transformation data files contain the following
components: (a) a version command, and (b) a sequence of transformation
commands, one for each supplemental frame. Each line of text should contain at
most one command, between which optional comments may be interspersed. A
transformation command can be Euclidean, projective, or default. Euclidean and
projective commands take several arguments, including the width and height of
the supplemental frame. Default commands take no arguments. Commands are
outlined in more detail below.</p>
<s><t>Version command</t>
<p>The version 2 version command is as follows:</p>
<pre>V 2
</pre>
</s><s><t>Euclidean commands</t>
<p>The structure of a Euclidean command is as follows:</p>
<pre>E &lt;image width&gt; &lt;image height&gt; &lt;x-offset&gt; &lt;y-offset&gt; &lt;rotation-angle&gt;
</pre>
</s><s><t>Projective commands</t>
<p>Projective commands map the four corners of the supplemental frame to four
points in the rendering coordinate system:</p>
<pre>P &lt;image width&gt; &lt;image height&gt; &lt;top-left-x&gt; &lt;top-left-y&gt; &lt;blx&gt; &lt;bly&gt; &lt;brx&gt; &lt;bry&gt; &lt;trx&gt; &lt;try&gt;
</pre>
</s><s><t>Default commands</t>
<p>Default commands can be explicitly written as follows:</p>
<pre>D
</pre>
<p>Alternatively, if there are more frames than alignment commands (euclidean,
projective, or default), then the last supplemental frames in the frame
sequence will be assigned the default command.</p>
</s><s><t>Comments</t>
Comments can be inserted with the following syntax:
<pre># This comment extends to the end of this line. I can write anything I want here.
</pre>
</s></s><s><t>Alignment file syntax (version 3)</t>
<p>Version 3 syntax is required for specifying transformations for the original
frame, and for specifying barrel/pincushion distortion parameters. </p>
<p>In version 3, the first transformation command is associated with the
original frame, instead of being associated with the first supplemental frame.
Also, barrel/pincushion distortion commands can precede each projective,
Euclidean, or default command.</p>
<s><t>Version command</t>
<p>The version 3 version command is as follows:</p>
<pre>V 3
</pre>
</s><s><t>Barrel/pincushion distortion command</t>
<p>In version 3, barrel/pincushion distortion commands are supported. Distortion
is modeled as a transformation affecting the distance of image features from the
image center. The distorted distance is expressed as a polynomial function of
the undistorted distance. Zeroth and first order coefficients are fixed or
automatically determined; additional coefficients can be specified explicitly,
using the following syntax:</p>
<pre>B &lt;n&gt; &lt;coefficient 2&gt; &lt;coefficient 3&gt; ... &lt;coefficient n+1&gt;
</pre>
<p>Barrel/pincushion distortion commands should precede the projective, Euclidean,
or default transformation command for the corresponding frame.</p>
</s></s>
</chapter>

19
doc/user/ui/index.xml Normal file
View File

@@ -0,0 +1,19 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
<chapter id="user-ui"><title>User Interfaces</title>
<p>ALE currently supports two user interface types. The traditional interface
is the stream interface, which produces only printing characters and
whitespace. If ALE is compiled with IOCTL support, additional information can
be provided through the tty interface, which is default.</p>
<pre>--ui=&lt;type&gt; Set user interface to &lt;type&gt;, one of:
stream
tty [default]
</pre>
</chapter>