/usr/share/doc/liblqr-1-0-dev/html/tuning.html is in liblqr-1-0-dev 0.4.1-1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Tuning</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="The Liquid Rescale library Manual"><link rel="up" href="api-manual.html" title="Chapter 2. LqR library API user manual"><link rel="prev" href="rigmask.html" title="Adding a rigidity mask"><link rel="next" href="vmaps.html" title="Dealing with the visibility maps (the seams)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Tuning</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="rigmask.html">Prev</a> </td><th width="60%" align="center">Chapter 2. LqR library API user manual</th><td width="20%" align="right"> <a accesskey="n" href="vmaps.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Tuning"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tuning"></a>Tuning</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="tuning.html#lqr-enl-step">Setting the enlargement step</a></span></dt><dt><span class="sect2"><a href="tuning.html#res-order">Choosing the resize order</a></span></dt><dt><span class="sect2"><a href="tuning.html#switch-freq">Choosing the side switch frequency</a></span></dt><dt><span class="sect2"><a href="tuning.html#cache">Using the cache</a></span></dt></dl></div><p>
The behaviour can be tuned through some additional functions.
</p><div class="sect2" title="Setting the enlargement step"><div class="titlepage"><div><div><h3 class="title"><a name="lqr-enl-step"></a>Setting the enlargement step</h3></div></div></div><p>
As mentioned in <a class="link" href="seam-carve.html#about-enlarge" title="About enlarging">About enlarging</a>, if the requested final size is
too big, the rescaling is automatically divided in steps.
</p><p>
For example, let us suppose that we have created an <code class="classname">LqrCarver</code> object from a 100 by 100 pixels
image, and that we call <code class="function">lqr_carver_resize</code> with 600 and 100 as width and height
arguments. With the default settings, the rescaling of the width will be performed in 3 steps:
first, from 100 to 199, then from 199 to 397, and finally from 397 to 600.
</p><p>
The rule here is that the maximum size which can be reached in a single step is equal to twice the
original size minus one, and that at each step the original size is reset to the current size
(through an internal call to <code class="function">lqr_carver_flatten</code>).
</p><p>
In most situations, however, the steps should be smaller in order to obtain good results. This can
be set with this function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrRetVal <b class="fsfunc">lqr_carver_set_enl_step</b>(</code></td><td> LqrCarver * <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td> gfloat <var class="pdparam">enl_step</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
The value of <em class="parameter"><code>enl_step</code></em> must be strictly grater then 1.0 and less then (or
equal to) 2.0. The default value is 2.0 (for back-compatibility reasons); any other value will
result in the function returning an error. The new maximum size for a step will then be obtained by
multiplying the original size by the enlargement step and subtracting 1.
</p><p>
The current value of the enlargement step can be retrieved with this function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">gfloat <b class="fsfunc">lqr_carver_get_enl_step</b>(</code></td><td> LqrCarver * <var class="pdparam">carver</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p></div><div class="sect2" title="Choosing the resize order"><div class="titlepage"><div><div><h3 class="title"><a name="res-order"></a>Choosing the resize order</h3></div></div></div><p>
When the function <code class="function">lqr_carver_resize</code> is asked to resize along both directions in
a single step, it has to choose which direction to resize first. The resize order can be changed
through this function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">lqr_carver_set_resize_order</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>LqrResizeOrder <var class="pdparam">resize_order</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
The possible values for resize_order are:
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">LQR_RES_ORDER_HOR</code></span></dt><dd><p>
resize horizonally first (this is the default)
</p></dd><dt><span class="term"><code class="literal">LQR_RES_ORDER_VERT</code></span></dt><dd><p>
resize vertically first
</p></dd></dl></div><p>
</p></div><div class="sect2" title="Choosing the side switch frequency"><div class="titlepage"><div><div><h3 class="title"><a name="switch-freq"></a>Choosing the side switch frequency</h3></div></div></div><p>
When the function <code class="function">lqr_carver_resize</code> is invoked, it chooses at each step the
optimal seam to carve based on the relvance value for each pixel. However, in the case two seams
are equivalent (which may happen when large portions of the image have the same colour, for
example), the algorithm always chooses the seams from one side, which might be a problem (e.g. an
object centered in the original image might not be centered any more in the resulting image).
</p><p>
In order to overcome this effect, an option is given to automatically switch the favoured side
during rescaling, at the cost of a slightly worse performance. The number of times such a switching
event occurs for each rescale operation can be set using the function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">lqr_carver_set_side_switch_frequency</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>guint <var class="pdparam">switch_frequency</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
The default value for newly created <code class="classname">LqrCarver</code> objects is <code class="literal">0</code>, which is equivalent
to disabling this feature. Giving a value greater than the number of pixels by which to rescale
produces a switch for each pixel, therefore you could set <em class="parameter"><code>switch_freqency</code></em> to
a ridicolously high value in order to be sure to get this effect.
</p><p>
As for the final result, a very small value (e.g. <code class="literal">1<code class="literal"> to </code>4</code>) will
normally suffice to balance the left and right side of the image (or the top and the bottom sides
for vertical rescalings), without noticeable computational costs. However, in order to obtain a
smoother behaviour for the visibiliy map, i.e. for the intermediate steps, higher values may be
required.
</p></div><div class="sect2" title="Using the cache"><div class="titlepage"><div><div><h3 class="title"><a name="cache"></a>Using the cache</h3></div></div></div><p>
By default, the library tries to cache some quantities in order to save computational time. The
cache may be disabled in order to save memory instead, using this function:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">lqr_carver_set_use_cache</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>gboolean <var class="pdparam">use_cache</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
To disable the cache, set <em class="parameter"><code>use_cache</code></em> to <code class="literal">FALSE</code>. To
re-enable it back, set it to <code class="literal">TRUE</code>.
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rigmask.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="api-manual.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="vmaps.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Adding a rigidity mask </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Dealing with the visibility maps (the seams)</td></tr></table></div></body></html>
|