/usr/share/doc/liblqr-1-0-dev/html/energy.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 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Automatic feature detection</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="read-out.html" title="Reading the multi-size image"><link rel="next" href="bias.html" title="Adding a bias"></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">Automatic feature detection</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="read-out.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="bias.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Automatic feature detection"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="energy"></a>Automatic feature detection</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="energy.html#energy-foreword">Foreword</a></span></dt><dt><span class="sect2"><a href="energy.html#energy-builtin">Builtin energy functions</a></span></dt><dt><span class="sect2"><a href="energy.html#energy-custom">Custom energy functions</a></span></dt><dt><span class="sect2"><a href="energy.html#energy-readout">Reading out the energy</a></span></dt></dl></div><div class="sect2" title="Foreword"><div class="titlepage"><div><div><h3 class="title"><a name="energy-foreword"></a>Foreword</h3></div></div></div><p>
The automatic feature detection relies on the evaluation of the relevance of each pixel; this
quantity is called `energy': the higher the energy of a pixel, the less likely it will be that such
pixel will be directly involved in the rescaling. The energy function which the library uses can be
customised; normally, edge detector filters are the best choices for this purpose.
</p><p>
There is a unified framework in the Liquid Rescale library for energy fucntions: briefly, each energy function used
by the library receives the current position and image size as parameters, and is provided access to
a square of values from the image, centered around the current position. This access is provided
through an object which is called a "reading window", and the image pixels are not read directly,
but rather they are accessed according to a "reader type", which means that the energy function can
get e.g. the brightness of a pixel without needing to care for the underlying image representation,
i.e. the image type or the colour depth.
</p><p>
The library provides a small set of very simple (yet normally effective) gradient-based energy
functions, and a customisation framework for defining more functions.
</p></div><div class="sect2" title="Builtin energy functions"><div class="titlepage"><div><div><h3 class="title"><a name="energy-builtin"></a>Builtin energy functions</h3></div></div></div><p>
The library has some builtin functions for energy evaluation; in order to set one of the builtin
functions in a <code class="classname">LqrCarver</code> object this function is used:
</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_energy_function_builtin</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>LqrEnergyFunctionBuiltinType <var class="pdparam">ef_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
The currently available builtin functions which can be used as <em class="parameter"><code>ef_ind</code></em> are:
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">LQR_EF_GRAD_XABS</code></span></dt><dd><p>
absolute value of the brightness gradient in the direction
of the rescaling (this is the default)
</p></dd><dt><span class="term"><code class="literal">LQR_EF_GRAD_SUMABS</code></span></dt><dd><p>
sum of absolute values of the brightness gradients in both directions
</p></dd><dt><span class="term"><code class="literal">LQR_EF_GRAD_NORM</code></span></dt><dd><p>
norm of the brightness gradient
</p></dd><dt><span class="term"><code class="literal">LQR_EF_LUMA_GRAD_XABS</code></span></dt><dd><p>
absolute value of the luma gradient in the direction
of the rescaling
</p></dd><dt><span class="term"><code class="literal">LQR_EF_LUMA_GRAD_SUMABS</code></span></dt><dd><p>
sum of absolute values of the luma gradients in both directions
</p></dd><dt><span class="term"><code class="literal">LQR_EF_LUMA_GRAD_NORM</code></span></dt><dd><p>
norm of the luma gradient
</p></dd><dt><span class="term"><code class="literal">LQR_EF_NULL</code></span></dt><dd><p>
null
</p></dd></dl></div><p>
</p><p>
All of the above gradient functions have a radius of 1 pixel.
</p></div><div class="sect2" title="Custom energy functions"><div class="titlepage"><div><div><h3 class="title"><a name="energy-custom"></a>Custom energy functions</h3></div></div></div><p>
Custom energy functions for a <code class="classname">LqrCarver</code> object are set 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">LqrRetVal <b class="fsfunc">lqr_carver_set_energy_function</b>(</code></td><td>LqrCarver* <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>LqrEnergyFunc <var class="pdparam">ef_func</var>, </td></tr><tr><td> </td><td>gint <var class="pdparam">radius</var>, </td></tr><tr><td> </td><td>LqrEnergyReaderType <var class="pdparam">reader_type</var>, </td></tr><tr><td> </td><td>gpointer <var class="pdparam">extra_data</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
Here, <em class="parameter"><code>ef_func</code></em> is the function (the prototype will be explained below),
<em class="parameter"><code>radius</code></em> is used to set the size of the square region around each pixel which
is used to evaluate the energy for that pixel, <em class="parameter"><code>reader_type</code></em> is used to set
which quantity is used for the energy computation (e.g. brightness, luma etc.) and
<em class="parameter"><code>extra_data</code></em> is a (void) pointer which can be used to pass additional
parameters to the energy function.
</p><p>
The <span class="type"><code class="literal">LqrEnergyReaderType</code></span> is an enum which can take these values (also
noted is the number of channels of the corresponging output):
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">LQR_ER_BRIGHTNESS</code></span></dt><dd><p>
brightness (1 channel)
</p></dd><dt><span class="term"><code class="literal">LQR_ER_LUMA</code></span></dt><dd><p>
luma (1 channel)
</p></dd><dt><span class="term"><code class="literal">LQR_ER_RGBA</code></span></dt><dd><p>
RGBA (4 channels)
</p></dd><dt><span class="term"><code class="literal">LQR_ER_CUSTOM</code></span></dt><dd><p>
read the normalised image channels as they are (as many channels as the image has)
</p></dd></dl></div><p>
These readouts always return values beetween <code class="literal">0</code> and <code class="literal">1</code>.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Note that these readouts may have special meanings depending on the image type:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
for <code class="literal">LQR_GREY_IMAGE</code>, <code class="literal">LQR_GREYA_IMAGE</code> and
<code class="literal">LQR_CUSTOM_IMAGE</code> images, the <code class="literal">LQR_ER_LUMA</code>
readout will yield the same result as <code class="literal">LQR_ER_BRIGHTNESS</code>
</p></li><li class="listitem"><p>
for <code class="literal">LQR_CUSTOM_IMAGE</code> images, the <code class="literal">LQR_ER_BRIGHTNESS</code>
readout will return the average pixel value (additive, i.e. if a black channel is
present the channel values will be inverted and multiplied by the black channel
inverse), multiplied by the alpha channel value.
</p></li><li class="listitem"><p>
for <code class="literal">LQR_CUSTOM_IMAGE</code> images, the <code class="literal">LQR_ER_RGBA</code>
readout <span class="emphasis"><em>cannot be used</em></span>: it will always return
<code class="literal">0</code>
</p></li></ul></div><p>
</p></div><p>
The custom energy function must be declared like in the following sample declaration:
</p><div class="example"><a name="ex-custom-en-decl"></a><p class="title"><b>Example 2.5. Custom energy declaration</b></p><div class="example-contents"><pre class="programlisting">
gfloat my_energy (gint x, gint y, gint width, gint height, LqrReadingWindow *rwindow, gpointer extra_data);
</pre></div></div><p><br class="example-break">
This function should return the energy at pixel <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>,
based on the knowledge of the current image size (obtained from <em class="parameter"><code>width</code></em> and
<em class="parameter"><code>height</code></em>) and the content of the image in a square around that pixel, which is
passed through the <em class="parameter"><code>rwindow</code></em> reading window: in order to access this content,
this function must be used:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">gdouble <b class="fsfunc">lqr_rwindow_read</b>(</code></td><td>LqrReadingWindow * <var class="pdparam">rwindow</var>, </td></tr><tr><td> </td><td>gint <var class="pdparam">x</var>, </td></tr><tr><td> </td><td>gint <var class="pdparam">y</var>, </td></tr><tr><td> </td><td>channel <var class="pdparam">channel</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
When reading out the content from a window, the <em class="parameter"><code>x</code></em> and
<em class="parameter"><code>y</code></em> parameters are relative to the window centre (which instead is given by the
<em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em> parameters passed to the custom energy function),
and they both range between <code class="literal"><span class="symbol">-radius</span></code> and
<code class="literal"><span class="symbol">radius</span></code> included (<em class="parameter"><code>radius</code></em> being the same
one which is used in <code class="function">lqr_carver_set_energy_function</code>). The parameter
<em class="parameter"><code>channel</code></em> specifies which channel to read out; depending on the
<em class="parameter"><code>read_type</code></em> passed to <code class="function">lqr_carver_set_energy_function</code> the
range and meaning of this parameter will change: for the cases <code class="literal">LQR_ER_BRIGHTNESS</code> and
<code class="literal">LQR_ER_LUMA</code> it must be <code class="literal">0</code>, because the readout consists of a
single channel, for <code class="literal">LQR_ER_RGBA</code> it must be between <code class="literal">0</code> and
<code class="literal">3</code> (and then the readout will contain the RGBA information), while for
<code class="literal">LQR_ER_CUSTOM</code> it must be one of the original image channels.
</p><p>
The <em class="parameter"><code>rwindow</code></em> parameters can be read out from within a custom defined energy
function using these functions:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrEnergyReaderType <b class="fsfunc">lqr_rwindow_get_read_t</b>(</code></td><td>LqrReadingWindow * <var class="pdparam">rwindow</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">gint <b class="fsfunc">lqr_rwindow_get_radius</b>(</code></td><td>LqrReadingWindow * <var class="pdparam">rwindow</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">gint <b class="fsfunc">lqr_rwindow_get_channels</b>(</code></td><td>LqrReadingWindow * <var class="pdparam">rwindow</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
Following is an example of how a simple Sobel fliter can be defined and used within this framework:
</p><div class="example"><a name="ex-custom-en-def"></a><p class="title"><b>Example 2.6. Custom energy definition and setup</b></p><div class="example-contents"><pre class="programlisting">
/* definition */
gfloat sobel(gint x, gint y, gint width, gint height, LqrReadingWindow *rw, gpointer extra_data)
{
gint i, j;
gdouble ex = 0;
gdouble ey = 0;
gdouble k[3][3] = {{0.125, 0.25, 0.125}, {0, 0, 0}, {-0.125, -0.25, -0.125}};
for (i = -1; i <=1; i++) {
for (j = -1; j <=1; j++) {
ex += k[i + 1][j + 1] * lqr_rwindow_read(rw, i, j, 0);
ey += k[j + 1][i + 1] * lqr_rwindow_read(rw, i, j, 0);
}
}
return (gfloat) sqrt(ex * ex + ey * ey);
}
/* usage */
lqr_carver_set_energy_function (carver, sobel, 1, LQR_ER_BRIGHTNESS, NULL);
</pre></div></div><p><br class="example-break">
</p><p>
In the above <code class="function">sobel</code> function it is assumed that the radius is 1 and that the
readout will consist of a single channel. Furthermore, no boundary checking is performed, and
therefore the parameters <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>, <em class="parameter"><code>width</code></em> and <em class="parameter"><code>height</code></em> are not used. Also, no extra
parameters are passed to the function.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The function <code class="function">lqr_rwindow_read</code> returns <code class="literal">0</code> when the
requested value is out of the image boundary or beyond the reading window radius.
</p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The energy functions are called over the transposed image in case of vertical scaling,
therefore, if they are asymmetrical, the result will be different depending on the scaling
orientation (this is the case for example for the <code class="literal">LQR_EF_GRAD_XABS</code> builtin
function).
</p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The energy function output should be normalised in order to be comparable with the builtin
functions, otherwise the scale of the bias would be different depending on the energy function
used. This is the reason why in the Sobel filter written above the kernel
<em class="parameter"><code>k</code></em> is scaled so that the sum of the absolute values of the matrix is equal
to <code class="literal">1</code>.
</p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
In actual code, the call to <code class="function">lqr_carver_set_energy_function</code> should be
protected to test its return value.
</p></div></div><div class="sect2" title="Reading out the energy"><div class="titlepage"><div><div><h3 class="title"><a name="energy-readout"></a>Reading out the energy</h3></div></div></div><p>
The energy can be read out with three similar functions, all of which fill a buffer provided by
the user, but in different ways: two of them are suitable for plotting, while the third one can be
used to retreive the true values of the energy, as used internally.
</p><p>
The first function can be used to get a buffer of normalised values, and it has a simple syntax:
</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_get_energy</b>(</code></td><td>LqrCarver * <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>gfloat * <var class="pdparam">buffer</var>, </td></tr><tr><td> </td><td>gint <var class="pdparam">orientation</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
This function writes the the energy values at the time of calling to the given
<em class="parameter"><code>buffer</code></em>, ordered by row and then by column. All values range between
<code class="literal">0</code> and <code class="literal">1</code>. The buffer must be allocated by the user before
calling it.
</p><p>
The <em class="parameter"><code>orientation</code></em> parameter determines which orientation will be used when
computing the energy: <code class="literal">0</code> means horizontal, <code class="literal">1</code> means vertical.
</p><p>
The <em class="parameter"><code>carver</code></em> need not be initialised; if a bias was added to it (see the
<a class="link" href="bias.html" title="Adding a bias">Adding a bias</a> section), its effect is included in the output.
</p><p>
The above function does not return the true energy which is used internally, because that would not
be suitable for plotting, since the energy range is arbitrary (only the energy differences are
meaningful, and there is no upper nor lower bound to the values). In order to get the true energy
values used internally, this function must be used instead (with the same syntax):
</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_get_true_energy</b>(</code></td><td>LqrCarver * <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>gfloat * <var class="pdparam">buffer</var>, </td></tr><tr><td> </td><td>gint <var class="pdparam">orientation</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
The last function can be used to fill directly an image buffer:
</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_get_energy_image</b>(</code></td><td>LqrCarver * <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td>void * <var class="pdparam">buffer</var>, </td></tr><tr><td> </td><td>gint <var class="pdparam">orientation</var>, </td></tr><tr><td> </td><td>LqrColDepth <var class="pdparam">col_depth</var>, </td></tr><tr><td> </td><td>LqrImageType <var class="pdparam">image_type</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
In this case, the buffer must be passed as <span class="type">void*</span>, while the
<em class="parameter"><code>col_depth</code></em> and <em class="parameter"><code>image_type</code></em> are used to specify the
colour depth and the image type, in the same way as is done when creating an <code class="classname">LqrCarver</code> object (see
<a class="link" href="generate-multi-size.html#carver-new" title="Carver object creation">Carver objcet creation</a> and the
<a class="link" href="generate-multi-size.html#image-type" title="Choosing the image type">Choosing the image type</a> sections). The only restriction is that it
is not possible to ask for <code class="literal">LQR_CUSTOM_IMAGE</code> image types.
</p><p>
For any choice of the parameters, the <em class="parameter"><code>buffer</code></em> will hold a greyscale image,
ranging from black (lowest energy) to white (highest energy). The opacity (alpha) will be set to
<code class="literal">1</code>, if present. All the information will be stored in the black channel in
<code class="literal">LQR_CMYK_IMAGE</code> and <code class="literal">LQR_CMYKA_IMAGE</code> image types.
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Calling the function <code class="function">lqr_carver_get_energy_image</code> with <code class="literal">LQR_COLDEPTH_32F</code> and
<code class="literal">LQR_GREY_IMAGE</code> arguments will yield the same result as calling the function
<code class="function">lqr_carver_get_image</code>, but the latter is slightly more efficient.
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="read-out.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="bias.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Reading the multi-size image </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Adding a bias</td></tr></table></div></body></html>
|