/usr/share/doc/liblqr-1-0-dev/html/generate-multi-size.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 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Generating the multi-size image</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="api-manual.html" title="Chapter 2. LqR library API user manual"><link rel="next" href="lqr.html" title="Liquid rescaling"></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">Generating the multi-size image</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="api-manual.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="lqr.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Generating the multi-size image"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="generate-multi-size"></a>Generating the multi-size image</h2></div></div></div><div class="toc"><dl><dt><span class="sect2"><a href="generate-multi-size.html#carver-new">Carver object creation</a></span></dt><dt><span class="sect2"><a href="generate-multi-size.html#carver-init">Carver activation</a></span></dt><dt><span class="sect2"><a href="generate-multi-size.html#image-type">Choosing the image type</a></span></dt></dl></div><div class="sect2" title="Carver object creation"><div class="titlepage"><div><div><h3 class="title"><a name="carver-new"></a>Carver object creation</h3></div></div></div><p>
The <code class="classname">LqrCarver</code> objects are initialised from a plain buffer representing an image. The default
constructor assumes a colour depth of 8 bits per channel:
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">LqrCarver * <b class="fsfunc">lqr_carver_new</b>(</code></td><td> guchar * <var class="pdparam">buffer</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">width</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">height</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">channels</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
Here, <em class="parameter"><code>buffer</code></em> is the array representing an image of size
<em class="parameter"><code>width</code></em> by <em class="parameter"><code>height</code></em> with <em class="parameter"><code>channels</code></em>
colour channels per pixels. Thus, the overall buffer size has to be of
<code class="literal"><em class="parameter"><code>widht</code></em> * <em class="parameter"><code>height</code></em> *
<em class="parameter"><code>channels</code></em> </code> unsigned characters, and ordered such that the
<code class="literal"><span class="symbol">k</span></code>-th colour of the pixel at row
<code class="literal"><span class="symbol">y</span></code> and column <code class="literal"><span class="symbol">x</span></code> is found at:
</p><pre class="programlisting">buffer[(y * width + x) * channels + k]</pre><p> (this assumes that
<code class="literal"><span class="symbol">x</span></code>, <code class="literal"><span class="symbol">y</span></code> and
<code class="literal"><span class="symbol">k</span></code> all start from <code class="literal">0</code> and reach the maximum
values <code class="literal"><span class="symbol">widht</span>-1</code>, <code class="literal"><span class="symbol">height</span>-1</code> and
<code class="literal"><span class="symbol">channels</span>-1</code>, respectively)
</p><p>
The function returns a pointer to the newly allocated <code class="classname">LqrCarver</code> upon success, or
<code class="literal"><span class="returnvalue">NULL</span></code> in case of insufficient memory.
</p><p>
In order to create <code class="classname">LqrCarver</code> objects with more than 8 bits per channel, an extended version of the
constructor 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">LqrCarver * <b class="fsfunc">lqr_carver_new_ext</b>(</code></td><td> void * <var class="pdparam">buffer</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">width</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">height</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">channels</var>, </td></tr><tr><td> </td><td> LqrColDepth <var class="pdparam">colour_depth</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
The differnece with the default version is that the input buffer must be passed as void, and its
type must be specified through the additional parameter <em class="parameter"><code>colour_depth</code></em>, which
can take one of the following values:
</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">LQR_COLDEPTH_8I</code></span></dt><dd><p>
8 bit unsigned integers (<span class="type">guchar</span>)
</p></dd><dt><span class="term"><code class="literal">LQR_COLDEPTH_16I</code></span></dt><dd><p>
16 bit unsigned integers (<span class="type">guint16</span>)
</p></dd><dt><span class="term"><code class="literal">LQR_COLDEPTH_32F</code></span></dt><dd><p>
32 bit floating point (<span class="type">gfloat</span>)
</p></dd><dt><span class="term"><code class="literal">LQR_COLDEPTH_64F</code></span></dt><dd><p>
64 bit floating point (<span class="type">gdouble</span>)
</p></dd></dl></div><p>
</p><p>
Floating point type values must range between <code class="literal">0</code> and <code class="literal">1</code>.
</p><p>
The library has some support for different image types and color models. When a <code class="classname">LqrCarver</code> object is
created, the image type is automatically set from the number of channels (basically, assuming that
the image is either grayscale or RGB with possibly an alpha channel), but it is important to set it
manually using the function <code class="function">lqr_carver_set_image_type</code> if your program has to
deal with different color models. See the section <a class="link" href="generate-multi-size.html#image-type" title="Choosing the image type">Choosing the image
type</a> for more details.
</p><p>
By default, the buffer is assumed to be a copy of the original image, and therefore it is owned by
the <code class="classname">LqrCarver</code> object and must not be accessed directly any more (and of course it must not be
freed, the <code class="classname">LqrCarver</code> <a class="link" href="release.html" title="Releasing the memory">destructor</a> does it). If, instead, you want the
Liquid Rescale library to keep the buffer intact, you must flag the <code class="classname">LqrCarver</code> after creation (or after
<a class="link" href="generate-multi-size.html#carver-init" title="Carver activation">activation</a>), 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_preserve_input_image</b>(</code></td><td> LqrCarver * <var class="pdparam">carver</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
This function must be used before any other operation takes place.
</p></div><div class="sect2" title="Carver activation"><div class="titlepage"><div><div><h3 class="title"><a name="carver-init"></a>Carver activation</h3></div></div></div><p>
The newly created <code class="classname">LqrCarver</code> consists only of the image buffer plus an uninitialised visibility map.
If one had a previously computed visibility map, it could be imported into the <code class="classname">LqrCarver</code> and that
would be enough (see the <a class="link" href="vmaps.html#import-vmap" title="Importing a visibility map in a carver">Importing a visibility map in a carver</a>
section).
</p><p>
If the visibility map has to be computed, the <code class="classname">LqrCarver</code> needs to be initialised 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">LqrRetVal <b class="fsfunc">lqr_carver_init</b>(</code></td><td> LqrCarver * <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">delta_x</var>, </td></tr><tr><td> </td><td> gfloat <var class="pdparam">rigidity</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>
Here, <em class="parameter"><code>delta_x</code></em> is the maximum allowed transversal step of the seams (0 means
straight seams, the typical value is 1), while the <em class="parameter"><code>rigidity</code></em> parameter can be
used to introduce a global bias for non-straight seams (the typical value is 0; a nonzero value can
be modulated locally for specific areas using the functions described in section
<a class="link" href="rigmask.html" title="Adding a rigidity mask">Adding a rigidity mask</a>).
</p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
It is currently an error to initalise a carver object if a visibility map has been imported
already.
</p></div></div><div class="sect2" title="Choosing the image type"><div class="titlepage"><div><div><h3 class="title"><a name="image-type"></a>Choosing the image type</h3></div></div></div><p>
The library supports a small number of different image types/color models in order to correctly
compute quantities such as the brightness of a pixel, which are important for automatic feature
detection.
</p><p>
The image type can be set manually 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">LqrRetVal <b class="fsfunc">lqr_carver_set_image_type</b>(</code></td><td> LqrCarver * <var class="pdparam">carver</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>
</p><p>
The type <span class="type">LqrImageType</span> is an <code class="literal">enum</code> which can take these values:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="literal">LQR_GREY_IMAGE</code></li><li class="listitem"><code class="literal">LQR_GREYA_IMAGE</code></li><li class="listitem"><code class="literal">LQR_RGB_IMAGE</code></li><li class="listitem"><code class="literal">LQR_RGBA_IMAGE</code></li><li class="listitem"><code class="literal">LQR_CMY_IMAGE</code></li><li class="listitem"><code class="literal">LQR_CMYK_IMAGE</code></li><li class="listitem"><code class="literal">LQR_CMYKA_IMAGE</code></li><li class="listitem"><code class="literal">LQR_CUSTOM_IMAGE</code></li></ul></div><p>
</p><p>
When creating a <code class="classname">LqrCarver</code> object, the image type is inferred from the number of channels according
to this table:
</p><div class="table"><a name="def-image-types"></a><p class="title"><b>Table 2.1. Image types assigned by default</b></p><div class="table-contents"><table summary="Image types assigned by default" border="1"><colgroup><col><col></colgroup><thead><tr><th>channels</th><th>type</th></tr></thead><tbody><tr><td>1</td><td><code class="literal">LQR_GREY_IMAGE</code></td></tr><tr><td>2</td><td><code class="literal">LQR_GREYA_IMAGE</code></td></tr><tr><td>3</td><td><code class="literal">LQR_RGB_IMAGE</code></td></tr><tr><td>4</td><td><code class="literal">LQR_RGBA_IMAGE</code></td></tr><tr><td>5</td><td><code class="literal">LQR_CMYKA_IMAGE</code></td></tr><tr><td>>5</td><td><code class="literal">LQR_CUSTOM_IMAGE</code></td></tr></tbody></table></div></div><p><br class="table-break">
</p><p>
When setting a carver to <code class="literal">LQR_CUSTOM_IMAGE</code>, it is assumed that there are no alpha or black channels,
but if there are, their index can be specified with the functions:
</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_alpha_channel</b>(</code></td><td> LqrCarver * <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">channel_index</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</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_black_channel</b>(</code></td><td> LqrCarver * <var class="pdparam">carver</var>, </td></tr><tr><td> </td><td> gint <var class="pdparam">channel_index</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
Use the value <code class="literal">-1</code> in the indices arguments to unset those channels. Note that
using <code class="literal">LQR_CUSTOM_IMAGE</code> in a carver normally requires special care in the choice and definitions of
the energy functions (see the <a class="link" href="energy.html" title="Automatic feature detection">Automatic feature detection</a> section).
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Setting manually the alpha or black channel with the above functions automatically sets the
carver image type to <code class="literal">LQR_CUSTOM_IMAGE</code>.
</p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The support for CMY (and derived) color models is very naïve, since no color profiles are yet
managed by the library.
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="api-manual.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="lqr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. LqR library API user manual </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Liquid rescaling</td></tr></table></div></body></html>
|