LqrCarver">
LqrCarverList">
LqrVMap">
LqrVMapList">
LqrReadingWindow">
LqrProgress">
TRUE">
FALSE">
NULL">
x">
y">
width">
height">
channels">
depth">
LQR_COLDEPTH_8I">
LQR_COLDEPTH_16I">
LQR_COLDEPTH_32F">
LQR_COLDEPTH_64F">
LQR_GREY_IMAGE">
LQR_GREYA_IMAGE">
LQR_RGB_IMAGE">
LQR_RGBA_IMAGE">
LQR_CMY_IMAGE">
LQR_CMYK_IMAGE">
LQR_CMYKA_IMAGE">
LQR_CUSTOM_IMAGE">
LQR_OK">
LQR_ERROR">
LQR_NOMEM">
LQR_USRCANCEL">
"Resizing width..."">
"Resizing height..."">
"done"">
"done"">
]>
The &lqrl; ManualCarloBaldassiLqR library0.4.2 API (3:2:3)200720082009Carlo Baldassi10 Maj 2009IntroductionCopyright
Liquid Rescale Library Manual.
Copyright (C) 2007-2009 Carlo Baldassi carlobaldassi@gmail.com
This manual is released under the terms of the GNU General Public License as published by the Free
Software Foundation; version 3 dated June, 2007.
You should have received a copy of the GNU General Public License along with the library; if not, see
http://www.gnu.org/licensesAbout this document
This manual describes in detail the &lqrl; API, starting from a brief overview on seam carving, the
internal image representation, a minimal list of basic methods and the full explanation of all the
library public methods.
In the `examples' directory, you will find a minimal example program, which only
uses basic methods, and a full-featured demo program, which uses almost all of the methods described in
this document. Both programs are fully commented, see also the README file in the
`examples' directory.
Refer to the README file for information about installing and compiling.
The latest version of the &lqrl; and of this manual can be found at
http://liblqr.wikidot.com.
Seam carving in brief
Basically, the rescaling algorithm tries to find out which parts of the image are important, and which
are not, based on the contrast between adjacent pixels; then, the image is resized through the
elimination or insertion of continuous paths, called `seams'. The seams connect the top of the image
with the bottom when rescaling horizontally, or they connect the left side with the right side when
rescaling vertically. In the seam carving process, seams are removed in sequence, therefore shrinking
the image by one pixel at a time. The seam insertion process mirrors the seam carving process,
introducing interpolated seams in regions where they would have been carved.
Once it has been computed, the carving information can be efficiently stored in a so called multi-sized
image, which can be used to reproduce the carving operation on the fly at any later moment.
It often happens that the automatic feature detection fails to identify as significant some image
regions; in these cases a preservation mask can be specified, which marks those regions. In fact, the
feature recognition process can be manually driven quite easily to its full extent, by using custom
masks.
See also the References section for more information about the
algorithm.
About enlarging
As mentioneed above, the enlargment process mirrors the carving process. More precisely, in order to
enlarge the image by a given amount of pixels, say N, the library first computes which would be the
first N seams to be removed; then, it inserts N new seams nearby those.
This means that it is clearly not possible to go beyond twice the original size in a single step. It
also means that doubling the image size in this way is just equivalent to standard scaling, since
the result is that each seam is just duplicated. For these reasons, the library rescaling engine
automatically divides enlarging sessions in steps, and allows to set the step size.
This same issue also affects in a tricky way the preservation of image areas when enlarging: suppose
your image is 1000 pixels wide, and you have protected an area which is 800 pixels wide. It is then
clear that you cannot shrink the image to less than 800 pixels without affecting the preserved area,
but the same is true when enlarging, so you should not go beyond 1200 pixels in a single step (=
1000 + (1000 - 800)), i.e. you should use a value lower than 1.2 for the enlargement step size.
In general, however, the optimal enlargement step size depends on the image, since large step sizes
have the disadvantages discussed above, while small step sizes will tend to inflate the same areas
of the image over and over at each step.
Overview of the library
The &lqrl; is written in C, but can be used into C++ programs without any modification. It has an
object-oriented design, so that the terminology in this manual is borrowed from C++. The central class
of the library is called &carv_obj;. Carver objects can generate and store multi-size images, or load
them, and read them out at the desired size.
Internally, multi-size images are stored simply as plain images with the addition of a visibility map.
Each pixel in the image has its own visibility level. Whether to display a pixel or not simply depends
on the comparison of each pixel's visibility with a given global visibility level. In this way, images
of different sizes can be read out, simply by setting a global visibility level.
Therefore, once the visibility map has been computed, it allows effortless, real-time scaling. However,
visibility maps also necessarily have an orientation, either horizontal or vertical. If we want to
resize on the other direction, the visibility map has to be computed afresh, and the previous visibility
map becomes useless, because the two maps are not consistent one with the other.
This also implies that the resizing order affects the final result: rescaling horizontally first, then
vertically, does not yield the same result as following the reverse order. Moreover, one could choose an
intermediate way, e.g. by rescaling by one pixel in one direction, one in the other, then iterating as
needed to reach the final size.
The default behaviour of the library is to rescale horizontally first, then vertically, but this order
can be reversed.
Visibility maps can be stored in objects of type &vmap_obj;. When an &carv_obj; object is created from
an input image, the visibility of each pixel is uninitialised. At this point, one could either import a
previously computed &vmap_obj;, or activate the &carv_obj; so that it creates one afresh when asked to.
In either case, there's a single method to call, specifiying the new desired size; all the rest will
automatically be computed as necessary. By default, the visibility maps are only computed up to the
extent to which they are needed for resizing.
Basic methods
Following is a list of the basic public methods associated with the &carv_obj; objects:
constructors and destructor
LqrCarver * lqr_carver_new (guchar *buffer, gint width, gint height, gint channels);
LqrCarver * lqr_carver_new_ext (void *buffer, gint width, gint height, gint channels, LqrColDepth colour_depth);
void lqr_carver_destroy (LqrCarver *carver);
initialization
LqrRetVal lqr_carver_init (LqrCarver *carver, gint delta_x, gfloat rigidity);
image manipulations
LqrRetVal lqr_carver_resize (LqrCarver *carver, gint new_width, gint new_width);
LqrRetVal lqr_carver_flatten (LqrCarver *carver);
readout
gboolean lqr_carver_scan (LqrCarver *carver, gint *x, gint *y, guchar **rgb);
gboolean lqr_carver_scan_ext (LqrCarver *carver, gint *x, gint *y, void **rgb);
gboolean lqr_carver_scan_by_row (LqrCarver *carver);
gboolean lqr_carver_scan_line (LqrCarver *carver, gint *n, guchar **rgb);
gboolean lqr_carver_scan_line_ext (LqrCarver *carver, gint *n, void **rgb);
get values
gint lqr_carver_get_width (LqrCarver *carver);
gint lqr_carver_get_height (LqrCarver *carver);
gint lqr_carver_get_channels (LqrCarver *carver);
LqrColDepth lqr_carver_get_col_depth (LqrCarver *carver);
The fastest way to see how they work is having a look at the code of
examples/liquidrescale-basic.cpp, which is a very simple and fully commented
demostrative program.
The return value of many functions is of type LqrRetVal. This is just an enum
type which can be used for signal handling, see the Signal handling
section.
The other classes are optional: the class &vmap_obj; is used to hold the carving information (and the
class &vmapl_obj; is used to retrieve it from the &carv_obj; ojects); the class &prog_obj; is used to
customize progress report from the resizing engine (by default it is turned off).
A complete list of the library public methods can be found in the reference at the end of this document.
LqR library API user manualSignal handling
Many library functions return a value of type LqrRetVal. This is an enum type
which can hold the values:
&err_ok;
everyting OK
&err_err;
generic fatal error
&err_nomem;
not enough memory
&err_cancel;
action cancelled by the user
At top level, it is important that the user handle these values explicitly, because the library
functions don't do anything else than stopping and returning an error signal in case of errors. An easy
way is setting up some macros and wrap each function call with those, as shown in the example files.
Below top level, the library provides some convenient macros which can be used to wrap function calls,
in order to propagate these signals:
LQR_CATCH (expr)
if expr is equal to &err_ok; it does nothing, otherwise it
returns expr (or the result of the execution of
expr if it happens to be a function)
LQR_CATCH_F (expr)
returns &err_err; if expr is FALSELQR_CATCH_MEM (expr)
returns &err_nomem; if expr is NULL
The names of these macros have changed since version 0.4; the previous names
CATCH, CATCH_F and CATCH_MEM are
still available, but they can be disabled at configure time if they cause conflicts
(configure --help for details).
Generating the multi-size imageCarver object creation
The &carv_obj; objects are initialised from a plain buffer representing an image. The default
constructor assumes a colour depth of 8 bits per channel:
LqrCarver * lqr_carver_new guchar * buffer gint width gint height gint channels
Here, buffer is the array representing an image of size
width by height with channels
colour channels per pixels. Thus, the overall buffer size has to be of
widht * height *
channels unsigned characters, and ordered such that the
k-th colour of the pixel at row
y and column x is found at:
buffer[(y * width + x) * channels + k] (this assumes that
x, y and
k all start from 0 and reach the maximum
values widht-1, height-1 and
channels-1, respectively)
The function returns a pointer to the newly allocated &carv_obj; upon success, or
NULL in case of insufficient memory.
In order to create &carv_obj; objects with more than 8 bits per channel, an extended version of the
constructor must be used:
LqrCarver * lqr_carver_new_ext void * buffer gint width gint height gint channels LqrColDepth colour_depth
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 colour_depth, which
can take one of the following values:
&col_depth_8i;
8 bit unsigned integers (guchar)
&col_depth_16i;
16 bit unsigned integers (guint16)
&col_depth_32f;
32 bit floating point (gfloat)
&col_depth_64f;
64 bit floating point (gdouble)
Floating point type values must range between 0 and 1.
The library has some support for different image types and color models. When a &carv_obj; 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 lqr_carver_set_image_type if your program has to
deal with different color models. See the section Choosing the image
type for more details.
By default, the buffer is assumed to be a copy of the original image, and therefore it is owned by
the &carv_obj; object and must not be accessed directly any more (and of course it must not be
freed, the &carv_obj; destructor does it). If, instead, you want the
&lqrl; to keep the buffer intact, you must flag the &carv_obj; after creation (or after
activation), using this function:
void lqr_carver_set_preserve_input_image LqrCarver * carver
This function must be used before any other operation takes place.
Carver activation
The newly created &carv_obj; 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 &carv_obj; and that
would be enough (see the Importing a visibility map in a carver
section).
If the visibility map has to be computed, the &carv_obj; needs to be initialised through this
function:
LqrRetVal lqr_carver_init LqrCarver * carver gint delta_x gfloat rigidity
Here, delta_x is the maximum allowed transversal step of the seams (0 means
straight seams, the typical value is 1), while the rigidity 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
Adding a rigidity mask).
It is currently an error to initalise a carver object if a visibility map has been imported
already.
Choosing the image type
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.
The image type can be set manually using the function:
LqrRetVal lqr_carver_set_image_type LqrCarver * carver LqrImageType image_type
The type LqrImageType is an enum which can take these values:
&img_type_grey;&img_type_greya;&img_type_rgb;&img_type_rgba;&img_type_cmy;&img_type_cmyk;&img_type_cmyka;&img_type_custom;
When creating a &carv_obj; object, the image type is inferred from the number of channels according
to this table:
Image types assigned by defaultchannelstype1&img_type_grey;2&img_type_greya;3&img_type_rgb;4&img_type_rgba;5&img_type_cmyka;>5&img_type_custom;
When setting a carver to &img_type_custom;, it is assumed that there are no alpha or black channels,
but if there are, their index can be specified with the functions:
LqrRetVal lqr_carver_set_alpha_channel LqrCarver * carver gint channel_indexLqrRetVal lqr_carver_set_black_channel LqrCarver * carver gint channel_index
Use the value -1 in the indices arguments to unset those channels. Note that
using &img_type_custom; in a carver normally requires special care in the choice and definitions of
the energy functions (see the Automatic feature detection section).
Setting manually the alpha or black channel with the above functions automatically sets the
carver image type to &img_type_custom;.
The support for CMY (and derived) color models is very naïve, since no color profiles are yet
managed by the library.
Liquid rescalingThe resizing method
Once initialised, or if a visibility map has been loaded, the image can be resized through this
function:
LqrRetVal lqr_carver_resize LqrCarver * carver gint new_width gint new_height
This function decides automatically whether it can use the already computed visibility map, it has
to update it or waste it completely and start afresh. This last event occurs when the map was
computed for horizontal resizing and a vertical resize has been requested, or vice versa, and also
when the required enlargment is bigger than the enlargement step value (see
Setting the enlargement step). Note that only initialised
carvers can update or change the visibility map; if this is not the case, an error is returned.
The function also takes advantage of the fact that the enlargment process mirrors the shrink
process. For example, if the original size of the image is (w0,
h0) and lqr_carver_resize is invoked with
(w0 - 100, h0) as an argument, then subsequent
calls to the function will allow on-the-fly resizing in the whole range from
(w0 - 100, h0) to (w0
+ 100, h0). (But note that this may be overcome if
w0 + 100 is bigger than the enlargement step.)
Flattening
In order to resize in more than one step, the image can be flattened in its current state, thrugh
this function:
gboolean lqr_carver_flatten LqrCarver * carver
The return value is &ret_false; in case of insufficient memory, &ret_true; otherwise.
This function destroys the current visibility map and reinitialises the multi-size image from its
current state.
Every time that the image is flattened (including when changing the resize direction) the
original image and all information about it is lost.
Cancelling an action
The resizing and flattening operations can be aborted using this function:
LqrRetVal lqr_carver_cancel LqrCarver * carver
This function can be invoked asynchronously, from a different thread with respect to the one in
which the resizing or flattening methods were called. If successful, this function will return
&err_ok;, and any ongoing resizing or flattening functions will immidiately abort and return the
special value &err_cancel;; however, this function will have no effect if no operation was in
progress when calling it.
This function can be called multiple times.
Whenever a function returns &err_cancel;, it means that the &carv_obj; object is in an
inconsistent state, and there is currently no way to recover from this situation. Therefore, any
further operation on it must be avoided, and it must be destroyed.
The functions lqr_carver_resize and lqr_carver_flatten
are not the only ones which can return &err_cancel;; instead, any function in the library whose
return type is LqrRetVal and which operates on &carv_obj; objects can
return such value: for example, any function will do so if called over a &carv_obj; object for
which an operation was actually cancelled (but this is not the only possibility).
Reading the multi-size imagePixel by pixel
Once you have rescaled the image, you can read out the result through the functions:
gboolean lqr_carver_scan LqrCarver * carver gint* x gint* y guchar** rgb
or
gboolean lqr_carver_scan_ext LqrCarver * carver gint* x gint* y void** rgb
Here, x and y are pointers to the varaibles which will
hold the pixel coordinate, while rgb is a pointer to an array which will
contain the pixel colour information. If the carver was created using the standard 8-bit constructor
lqr_carver_new, the first form can be used, otherwise you must use the extended
form lqr_carver_scan_ext. In this last case, the output pointer
rgb must be passed as a pointer to void*, but the outcome should
actually be cast to a pointer to an array of the appropriate type, depending on the &carv_obj;
colour depth.
The return value is &ret_false; when the end of the image is reached, or the buffer has the wrong
number of bits, &ret_true; otherwise.
Each time these functions are invoked, they will store the coordinates and rgb information in the
output pointers and move to the next pixel. If they reach the end, they reset the reader and return
&ret_false;.
Here is a sample code usage:
A simple readout example
gint x, y;
guchar *rgb;
while (lqr_carver_scan (carver, &x, &y, &rgb) {
my_plot (x, y, rgb[0], rgb[1], rgb[2]);
}
In this example, it is assumed that the image has three 8-bit colour channels, and that there exist
some function my_plot which writes out the pixels somewhere.
The same readout example with different colour depth would read like this:
A simple readout example - extended version
gint x, y;
void *rgb;
gdouble *rgb_out;
while (lqr_carver_scan (carver, &x, &y, &rgb) {
rgb_out = (gdouble*) rgb;
my_plot (x, y, rgb_out[0], rgb_out[1], rgb_out[2]);
}
In this example it is assumed that the carver was loaded with the &col_depth_64f; as the
colour_depth argument in the constructor
lqr_carver_new_ext, and that it has 3 colour channels (see
the constructor section for details); therefore, the output is
cast to type gdouble before using it.
The rgb array is owned by to the carver object, so it doesn't need
initialization, as in the example. Indeed, it must be used for read-only purposes, and the
content should always be copyed after each call to a scan function.
One line at a time
The image can also be read one line at a time, but it is not possible to freely decide if it is to
be read by row or by column. Instead, this has to be queried by calling this function:
gboolean lqr_carver_scan_by_rowLqrCarver* carver
The function returns &ret_true; if the image is read by row, and &ret_false; if it is read by
column.
Then, the image can be read through these functions:
gboolean lqr_carver_scan_lineLqrCarver* carvergint* nguchar** rgb
or
gboolean lqr_carver_scan_line_extLqrCarver* carvergint* nvoid** rgb
These functions work exactly the same way as lqr_carver_scan and
lqr_carver_scan_ext, but only one coordinate is stored (either the row or the
column number), and the rgb array will contain a whole line.
Here is a sample code usage for the standard 8-bit case:
Line-by-line readout example
gint n;
guchar *rgb;
gboolean by_row;
by_row = lqr_carver_scan_by_row (carver);
while (lqr_carver_scan_line (carver, &n, &rgb) {
by_row ? my_plot_row (n, rgb) : my_plot_col (n, rgb);
}
where, as before, it is assumed that the my_plot_row and
my_plot_col functions have been previously defined and "know what to do".
The extended version for images with more colour depth is very similar, it only requires an
additional cast:
Line-by-line readout example - extended version
gint n;
void *rgb;
guchar *rgb_out;
gboolean by_row;
by_row = lqr_carver_scan_by_row (carver);
while (lqr_carver_scan_line_ext (carver, &n, &rgb) {
rgb_out = (gboolean*) rgb;
by_row ? my_plot_row (n, rgb_out) : my_plot_col (n, rgb_out);
}
Resetting
Normally, it is not needed to reset the image scan. However, if the scan has been stopped at same
intermediate step for some reason, the following function can be used to restart from the beginning:
void lqr_carver_scan_resetLqrCarver* carverAutomatic feature detectionForeword
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.
There is a unified framework in the &lqrl; 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.
The library provides a small set of very simple (yet normally effective) gradient-based energy
functions, and a customisation framework for defining more functions.
Builtin energy functions
The library has some builtin functions for energy evaluation; in order to set one of the builtin
functions in a &carv_obj; object this function is used:
LqrRetVal lqr_carver_set_energy_function_builtinLqrCarver* carverLqrEnergyFunctionBuiltinType ef_ind
The currently available builtin functions which can be used as ef_ind are:
LQR_EF_GRAD_XABS
absolute value of the brightness gradient in the direction
of the rescaling (this is the default)
LQR_EF_GRAD_SUMABS
sum of absolute values of the brightness gradients in both directions
LQR_EF_GRAD_NORM
norm of the brightness gradient
LQR_EF_LUMA_GRAD_XABS
absolute value of the luma gradient in the direction
of the rescaling
LQR_EF_LUMA_GRAD_SUMABS
sum of absolute values of the luma gradients in both directions
LQR_EF_LUMA_GRAD_NORM
norm of the luma gradient
LQR_EF_NULL
null
All of the above gradient functions have a radius of 1 pixel.
Custom energy functions
Custom energy functions for a &carv_obj; object are set using this function:
LqrRetVal lqr_carver_set_energy_functionLqrCarver* carverLqrEnergyFunc ef_funcgint radiusLqrEnergyReaderType reader_typegpointer extra_data
Here, ef_func is the function (the prototype will be explained below),
radius is used to set the size of the square region around each pixel which
is used to evaluate the energy for that pixel, reader_type is used to set
which quantity is used for the energy computation (e.g. brightness, luma etc.) and
extra_data is a (void) pointer which can be used to pass additional
parameters to the energy function.
The LqrEnergyReaderType is an enum which can take these values (also
noted is the number of channels of the corresponging output):
LQR_ER_BRIGHTNESS
brightness (1 channel)
LQR_ER_LUMA
luma (1 channel)
LQR_ER_RGBA
RGBA (4 channels)
LQR_ER_CUSTOM
read the normalised image channels as they are (as many channels as the image has)
These readouts always return values beetween 0 and 1.
Note that these readouts may have special meanings depending on the image type:
for LQR_GREY_IMAGE, LQR_GREYA_IMAGE and
LQR_CUSTOM_IMAGE images, the LQR_ER_LUMA
readout will yield the same result as LQR_ER_BRIGHTNESS
for LQR_CUSTOM_IMAGE images, the LQR_ER_BRIGHTNESS
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.
for LQR_CUSTOM_IMAGE images, the LQR_ER_RGBA
readout cannot be used: it will always return
0
The custom energy function must be declared like in the following sample declaration:
Custom energy declaration
gfloat my_energy (gint x, gint y, gint width, gint height, LqrReadingWindow *rwindow, gpointer extra_data);
This function should return the energy at pixel x, y,
based on the knowledge of the current image size (obtained from width and
height) and the content of the image in a square around that pixel, which is
passed through the rwindow reading window: in order to access this content,
this function must be used:
gdouble lqr_rwindow_readLqrReadingWindow * rwindowgint xgint ychannel channel
When reading out the content from a window, the x and
y parameters are relative to the window centre (which instead is given by the
x, y parameters passed to the custom energy function),
and they both range between -radius and
radius included (radius being the same
one which is used in lqr_carver_set_energy_function). The parameter
channel specifies which channel to read out; depending on the
read_type passed to lqr_carver_set_energy_function the
range and meaning of this parameter will change: for the cases LQR_ER_BRIGHTNESS and
LQR_ER_LUMA it must be 0, because the readout consists of a
single channel, for LQR_ER_RGBA it must be between 0 and
3 (and then the readout will contain the RGBA information), while for
LQR_ER_CUSTOM it must be one of the original image channels.
The rwindow parameters can be read out from within a custom defined energy
function using these functions:
LqrEnergyReaderType lqr_rwindow_get_read_tLqrReadingWindow * rwindowgint lqr_rwindow_get_radiusLqrReadingWindow * rwindowgint lqr_rwindow_get_channelsLqrReadingWindow * rwindow
Following is an example of how a simple Sobel fliter can be defined and used within this framework:
Custom energy definition and setup
/* 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);
In the above sobel 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 ¶m_x;, ¶m_y;, ¶m_w; and ¶m_h; are not used. Also, no extra
parameters are passed to the function.
The function lqr_rwindow_read returns 0 when the
requested value is out of the image boundary or beyond the reading window radius.
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 LQR_EF_GRAD_XABS builtin
function).
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
k is scaled so that the sum of the absolute values of the matrix is equal
to 1.
In actual code, the call to lqr_carver_set_energy_function should be
protected to test its return value.
Reading out the energy
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.
The first function can be used to get a buffer of normalised values, and it has a simple syntax:
LqrRetVal lqr_carver_get_energyLqrCarver * carvergfloat * buffergint orientation
This function writes the the energy values at the time of calling to the given
buffer, ordered by row and then by column. All values range between
0 and 1. The buffer must be allocated by the user before
calling it.
The orientation parameter determines which orientation will be used when
computing the energy: 0 means horizontal, 1 means vertical.
The carver need not be initialised; if a bias was added to it (see the
Adding a bias section), its effect is included in the output.
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):
LqrRetVal lqr_carver_get_true_energyLqrCarver * carvergfloat * buffergint orientation
The third function can be used to fill directly an image buffer:
LqrRetVal lqr_carver_get_energy_imageLqrCarver * carvervoid * buffergint orientationLqrColDepth col_depthLqrImageType image_type
In this case, the buffer must be passed as void*, while the
col_depth and image_type are used to specify the
colour depth and the image type, in the same way as is done when creating an &carv_obj; object (see
Carver objcet creation and the
Choosing the image type sections). The only restriction is that it
is not possible to ask for &img_type_custom; image types.
For any choice of the parameters, the buffer will hold a greyscale image,
ranging from black (lowest energy) to white (highest energy). The opacity (alpha) will be set to
1, if present. All the information will be stored in the black channel in
&img_type_cmyk; and &img_type_cmyka; image types.
Calling the function lqr_carver_get_energy_image with &col_depth_32f; and
&img_type_grey; arguments will yield the same result as calling the function
lqr_carver_get_energy, but the latter is slightly more efficient.
Adding a biasForeword
The automatic feature detection can be driven manually by adding a bias to the pixels of the image.
For example, it is possible to protect regions of the image by adding a positive bias to the
corresponding pixels. This will make the seams more unlikely to cross those regions, thus avoiding
distortion (but increasing distortion of the other regions).
It is also possible to make the seams more likely to cross some regions by adding a negative bias to
them. In this case, reducing the size of the image will tend to erase those regions, while
(possibly) keeping the rest of the image in a consistent state.
The bias has to be added before the resizing takes place (but it can be added before
initialisation since version 0.4).
In all of the bias-related functions, the bias is added on top of the existing one, so that all
of the functions can be called multiple times.
Adding a bias pixel by pixel
The function to use in order to add a bias to a given pixel is:
LqrRetVal lqr_carver_bias_add_xyLqrCarver* carvergdouble biasgint xgint y
Typical values for the bias parameter would be between 100
and 10000 in module.
Using an array of floating-point values
It is possible to use a whole array of floating points at once through this function:
LqrRetVal lqr_carver_bias_addLqrCarver* carvergdouble* buffergint bias_factor
Here, buffer is an array contining the bias values, and it is assumed to have
the same size as the image loaded in carver, while
bias_factor is an overall bias factor, which can be used to affect the global
bias level: if the elements of buffer are of order 1, a standard choice for
the bias_factor would be between 100 and 10000 (in module).
This function, and all the following, will not swallow the buffer (to the contrary of what
happens e.g. when creating a new &carv_obj; object and allowing the default behaviour),
therefore the buffer must be freed by the user afterwards.
Using another image
The bias can also be read from an 8-bit rgb buffer. This buffer has to be in the same format as the
one used in the 8-bit LqrCarver constructor (but may have a different number of colours per
channel). The function is:
LqrRetVal lqr_carver_bias_add_rgbLqrCarver* carverguchar* buffergint bias_factorgint channels
As in the previous case, buffer is assumed to hold and image of the same size
as the one in the carver.
The buffer contents will be transformed into floating-points by averaging the
colour components and multiplying the result by the alpha channel (transparency) value.
The existence of an alpha channel is inferred from the channels value: if
this is 1 or 3, no alpha channel is assumed, if it is 2 or 4 or greater, it is assumed that the
last channel holds the alpha value. If this is not what you want, you should resort to one of
the previous methods.
Operating on a specific area
The two previously described functions operate on the whole &carv_obj; image. It is also possible
to access specific image regions in a similar way; for the floating point case use:
LqrRetVal lqr_carver_bias_add_areaLqrCarver* carvergdouble* buffergint bias_factorgint widthgint heightgint x_offgint y_off
while for the rgb image case use:
LqrRetVal lqr_carver_bias_add_rgb_areaLqrCarver* carverguchar* buffergint bias_factorgint channelsgint widthgint heightgint x_offgint y_off
In both functions, ¶m_w; and ¶m_h; are used to specify the size of the area of interest,
while x_off and y_off specify its offset. For the
rest, both functions work in the same way as their global couterpart.
The provided buffers have to be of size ¶m_w; * ¶m_h; (or
¶m_w; * ¶m_h; * ¶m_channels; for the rgb case) but the specified
areas need not to be strictly included inside the &carv_obj; image area: only the parts which
overlap with it will be used. For example, the offsets can also be negative.
Adding a rigidity maskForeword
The rigidity parameter which is set at carver activation time (see section
Carver activation) normally affects the whole image. It is
possible, however, to specify which areas of the image should be affected by using a rigidity mask.
When a rigidity mask is used, each pixel of the image acquires an individual rigidity coefficient,
which has to be multiplied with the overall rigidity parameter to get the actual pixel's rigidity.
This is useful in some situations to reduce distorsions in specific areas of the image while keeping
the seams optimal in other areas.
The library interface to deal with rigidity masks follows very closely the scheme for bias masks as
described in the bias section, the main difference being that no
equivalent to the bias factor has to be provided (since it is already given in the
lqr_carver_init function).
The rigidity mask has to be added always after the &carv_obj;
initialization and before resizing takes place. (Note that this is
different from the bias, which instead can also be added to non-initialised carver objects.)
Whenever a rigidity mask is set, all pixels for which the value is not explicitly defined will
have coefficient 0, i.e. the rigidity setting will will be disabled.
All of the functions can be called multiple times, but their effect is not summed up, to the
contrary of what happens for the bias functions; instead, new values will substitute old ones
when the affected regions overlap.
Adding an individual rigidity coefficient to a pixel
The function to use in order to set the rigidity mask at a given pixel is:
LqrRetVal lqr_carver_rigmask_add_xyLqrCarver* carvergdouble rigiditygint xgint yUsing an array of floating-point values
It is possible to use a whole array of floating points at once through this function:
LqrRetVal lqr_carver_rigmask_addLqrCarver* carvergdouble* buffer
Here, buffer is an array contining the rigidity coefficients values, and it
is assumed to have the same size as the image loaded in carver.
This function, and all the following, will not swallow the buffer (to the contrary of what
happens e.g. when creating a new &carv_obj; object and allowing the default behaviour),
therefore the buffer must be freed by the user afterwards.
Using another image
The rigidity mask can also be read from an 8-bit rgb buffer. This buffer has to be in the same
format as the one used in the 8-bit LqrCarver constructor (but may have a different number of
colours per channel). The function is:
LqrRetVal lqr_carver_rigmask_add_rgbLqrCarver* carverguchar* buffergint channels
As in the previous case, buffer is assumed to hold and image of the same size
as the one in the carver.
The buffer contents will be transformed into floating-points by averaging the
colour components and multiplying the result by the alpha channel (transparency) value.
The existence of an alpha channel is inferred from the channels value: if
this is 1 or 3, no alpha channel is assumed, if it is 2 or 4, it is assumed that the last
channel is holds the alpha value. If this is not what you want, you should resort to one of the
previous methods.
Operating on a specific area
The two previously described functions operate on the whole &carv_obj; image. It is also possible
to access specific image regions in a similar way; for the floating point use:
LqrRetVal lqr_carver_rigmask_add_areaLqrCarver* carvergdouble* buffergint widthgint heightgint x_offgint y_off
while for the rgb image use:
LqrRetVal lqr_carver_rigmask_add_rgb_areaLqrCarver* carverguchar* buffergint channelsgint widthgint heightgint x_offgint y_off
In both functions, ¶m_w; and ¶m_h; are used to specify the size of the area of interest,
while x_off and y_off specify its offset. For the
rest, both functions work in the same way as their global couterpart.
The provided buffers have to be of size ¶m_w; * ¶m_h; (or
¶m_w; * ¶m_h; * ¶m_channels; for the rgb case) but the specified
areas need not to be strictly included inside the &carv_obj; image area: only the parts which
overlap with it will be used. For example, the offsets can also be negative.
Tuning
The behaviour can be tuned through some additional functions.
Setting the enlargement step
As mentioned in About enlarging, if the requested final size is
too big, the rescaling is automatically divided in steps.
For example, let us suppose that we have created an &carv_obj; object from a 100 by 100 pixels
image, and that we call lqr_carver_resize 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.
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 lqr_carver_flatten).
In most situations, however, the steps should be smaller in order to obtain good results. This can
be set with this function:
LqrRetVal lqr_carver_set_enl_step LqrCarver * carver gfloat enl_step
The value of enl_step 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.
The current value of the enlargement step can be retrieved with this function:
gfloat lqr_carver_get_enl_step LqrCarver * carverChoosing the resize order
When the function lqr_carver_resize 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:
void lqr_carver_set_resize_orderLqrCarver* carverLqrResizeOrder resize_order
The possible values for resize_order are:
LQR_RES_ORDER_HOR
resize horizonally first (this is the default)
LQR_RES_ORDER_VERT
resize vertically first
Choosing the side switch frequency
When the function lqr_carver_resize 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).
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:
void lqr_carver_set_side_switch_frequencyLqrCarver* carverguint switch_frequency
The default value for newly created &carv_obj; objects is 0, 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 switch_freqency to
a ridicolously high value in order to be sure to get this effect.
As for the final result, a very small value (e.g. 1 to 4) 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.
Using the cache
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:
void lqr_carver_set_use_cacheLqrCarver* carvergboolean use_cache
To disable the cache, set use_cache to FALSE. To
re-enable it back, set it to TRUE.
Dealing with the visibility maps (the seams)Dumping the visibility map
The visibility map can be saved at any moment by calling the function:
LqrVMap* lqr_vmap_dumpLqrCarver* carver
This function will return a pointer to a newly allocated &vmap_obj; object, or &ret_null; in case of
failure. See also the section "The visibility map objects".
Storing the visibility maps
By default, the computed visibility maps are wasted. Instead of saving them individually, it is
possible to automatically dump them at the end of the carving process, attaching them to their
associated &carv_obj;. In order to activate this feature, the following function has to be called:
void lqr_carver_set_dump_vmapsLqrCarver* carver
This will have the effect of dumping the visibility map each time
lqr_carver_resize is invoked, and storing it internally. When resizing along
both directions, two maps will be dumped, one for each direction.
In order to revert the effect of lqr_carver_set_dump_vmaps, thus stopping the
automatic dumping, use the function
void lqr_carver_set_no_dump_vmapsLqrCarver* carver
Alternatively, the internal storage mechanism can be called over the current visibility map at any
given moment by calling this function:
LqrRetVal lqr_vmap_internal_dumpLqrCarver* carver
The dumped maps are stored inside &vmap_obj; objects, and these are attached to their corresponing
&carv_obj; object through a linked list, whose type is &vmapl_obj;
Accessing the internally attached visibility maps
To access the maps attached to a carver one has first to obtain the pointer to the list, with the
function:
LqrVMapList* lqr_vmap_list_startLqrCarver* carver
Then, one can iterate through the attached maps by using these two functions:
LqrVMap* lqr_vmap_list_currentLqrVMapList* listLqrVMapList* lqr_vmap_list_nextLqrVMapList* list
Here is a sample code usage:
Accessing visibility maps #1
LqrVMap *vmap;
LqrVMapList *list;
list = lqr_vmap_list_start (carver);
while (list) {
vmap = lqr_vmap_list_current (list);
/* ... do something on vmap ... */
list = lqr_vmap_list_next (list);
}
The maps will always be accessed in the order in which they were dumped.
Alternatively, one can apply a function to all the elements of the list, through this function:
LqrRetVal lqr_vmap_list_foreachLqrVMapList* listLqrVMapFunc funcgpointer data
To use this second method, you'll need to define a function first, as in this sample code:
Accessing visibility maps #2
LqrRetVal my_func (LqrVMap vmap, gpointer data)
{
/* ... do something on vmap ... */
return LQR_OK;
}
LqrVMapList *list;
list = lqr_vmap_list_start (carver);
lqr_vmap_list_foreach (list, my_func, NULL);
In the above example, no data is actually passed on to the function.
In actual code the call to lqr_vmap_list_foreach should be protected to
test its return value, which is &err_ok; if all my_func calls have been
successful, or it will hold the first non-successful return value from
my_func.
The visibility map objects
The &vmap_obj; objects contain an int buffer with the actual map data (plain array, ordered by row),
plus all the information needed to be able to recover it from scratch.
The information can be extracted with these functions:
gint* lqr_vmap_get_data (&vmap_obj;* vmap);
gint lqr_vmap_get_width (&vmap_obj;* vmap);
gint lqr_vmap_get_height (&vmap_obj;* vmap);
gint lqr_vmap_get_orientation (&vmap_obj;* vmap);
gint lqr_vmap_get_depth (&vmap_obj;* vmap);
The first one returns a pointer to the data buffer.
The orientation of the map is 0 if the map is to be used for horizontal rescaling, 1 otherwise.
The depth of the map is the maximum amount of rescaling possible with that map, either shrinking or
enlarging.
Reading visibility maps data
If we have a &vmap_obj; pointer called vmap, we could access the
value at (x,y) by:
gint *buffer;
gint width;
gint vis;
buffer = lqr_vmap_get_data (vmap);
width = lqr_vmap_get_width (vmap);
vis = buffer[y * width + x];
Uninitialised points will yield vis = 0. For
initialised points, vis will store a positive value between
1 (least visible points, the first to be carved away or to be duplicated)
and (¶m_depth; + 1) (most visible points, the last to be carved away
or to be duplicated).
If the orientation is 0, the map allows resizing in the whole range form (¶m_w;
- ¶m_depth;) to (¶m_w; + ¶m_depth;). If the
orientation is 1, the analogue formula holds with ¶m_h; in place of ¶m_w;.
Importing a visibility map in a carver
Having an &vmap_obj; object, one can load it in an &carv_obj; simply by calling this function:
LqrRetVal lqr_vmap_loadLqrCarver* carverLqrVMap* vmap
The carver must not to be initialised, neither before nor after invoking this function.
This implies that the map cannot be updated, and that it will only be possible to resize the
carver by an amount ¶m_depth; along the orientation given by
lqr_vmap_orientation. The enlargment step is also set to its maximum, 2.0.
Invoking lqr_carver_resize with an out-of-bounds argument results in a
fatal error (i.e. it returns &err_err;).
Do not attach other carvers after you have loaded a visibility map (see also the
Attaching extra images section).
Saving and loading visibility maps to/from files
The library does not include methods to load/save visibility maps to/from files. However, a way to
do so is shown in the demo program `liquidrescale' in the
`examples' directory.
Attaching extra imagesAttaching a carver
Given an &carv_obj; object, it is possible to attach an arbitrary number of extra carvers to it:
these will passively undergo the same carving process as the root carver. In order for this to be
possible, the carvers must be all of the same size.
The function to use is simply:
LqrRetVal lqr_carver_attachLqrCarver* carverLqrCarver* aux
This attaches aux to carver.
It is not necessary that the parent &carv_obj; is activated. In fact, a carver can be attached to a
carver which is itself attached to another one.
Needless to say, no resizing operation should be done directly on an &carv_obj; once it has been
attached to another &carv_obj;, and neither should the cancel method be invoked directly on them.
The carvers always have to be attached before loading visibility maps.
Accessing attached carvers
Attached carvers can be read-out in the same way as their parents. There are however also methods
to span all them, in a way very similar to that in which internally dumped &vmap_obj;'s are
accessed, but &vmapl_obj; objects are substitued in this case by &carvl_obj; objects.
First, the starting point of the list has to be retreived through:
LqrCarverList* lqr_carver_list_startLqrCarver* carver
Then, one can iterate through the attached carvers by using these two functions:
LqrCarver* lqr_carver_list_currentLqrCarverList* listLqrCarverList* lqr_carver_list_nextLqrCarverList* list
Here is a sample code usage:
Accessing attached carvers #1
LqrCarver *aux;
LqrCarverList *list;
list = lqr_carver_list_start (carver);
while (list) {
aux = lqr_carver_list_current (list);
/* ... do something on aux ... */
list = lqr_carver_list_next (list);
}
The carvers will always be accessed in the order in which they were attached.
Alternatively, one can apply a function to all the elements of the list (and recursively to all the
elements of their attached lists, if there are any), through this function:
LqrRetVal lqr_carver_list_foreach_recursiveLqrCarverList* listLqrCarverFunc funcLqrDataTok data
To use this second method, you'll need to define a function first, as in the following sample code:
Accessing attached carvers #2
LqrRetVal my_func (LqrCarver *aux, LqrDataTok data)
{
/* ... do something on aux ... */
return LQR_OK;
}
LqrCarverList *list;
LqrDataTok data_tok;
list = lqr_carver_list_start (carver);
data_tok->data = NULL;
lqr_carver_list_foreach_recursive (list, my_func, data_tok);
The data to be passed on to the LqrCarverFunc is of type LqrDataTok. This
is defined as a union, with the following fields:
&carv_obj;* carvergintintegergpointerdata
In the above example, no data is actually passed on to the function.
In actual code, the call to lqr_carver_list_foreach_recursive should be
protected to test its return value, which is &err_ok; if all my_func calls have been successful
(or if the list is empty), or it will hold the first non-successful return value from
my_func.
Progress indicators
By default, the resizing is performed silently. However, it is possible to define progress report
functions, to receive feedback while the resizing is in progress. This is done through the &prog_obj;
objects.
Creating and attaching a progress report object
A &prog_obj; object is created through the function:
LqrProgress* lqr_progress_new
and can be associated to an &carv_obj; object through this function:
void lqr_carver_set_progressLqrCarver* carverLqrProgress* pSetting up progress hooks
Newly created progress objects are inactive, and need to be set up.
First, hook functions have to be set, which specify the action to take as the rescaling process
starts, progresses, and ends, by using the functions:
LqrRetVal lqr_progress_set_init (&prog_obj; * p, LqrProgressFuncInit init_func)
LqrRetVal lqr_progress_set_update (&prog_obj; * p, LqrProgressFuncUpdate update_func)
LqrRetVal lqr_progress_set_end (&prog_obj; * p, LqrProgressFuncEnd end_func)
as in this sample piece of code:
Setting progress hooks
LqrProgress *p;
p = lqr_progress_new();
lqr_progress_set_init (p, my_init);
lqr_progress_set_update (p, my_update);
lqr_progress_set_end (p, my_end);
The above example requires that the hook functions my_init,
my_update and my_end are defined as in the following
sample declarations:
Progress hooks declaration
LqrRetVal my_init (const gchar *init_message);
LqrRetVal my_update (gdouble percentage);
LqrRetVal my_end (const gchar *end_message);
Initial and ending progress messages
The init and end hooks will be called at the beginning and at the end of each rescaling operation by
function lqr_carver_resize. The messages that will be passed to these hooks
will change, depending if the resizing is occurring in the horizontal or in the vertical direction.
The defaults for newly created &prog_obj; objects are:
These can be changed using these functions:
LqrRetVal lqr_progress_set_init_width_message (&prog_obj; *p, const gchar * message)
LqrRetVal lqr_progress_set_init_height_message (&prog_obj; *p, const gchar * message)
LqrRetVal lqr_progress_set_end_width_message (&prog_obj; *p, const gchar * message)
LqrRetVal lqr_progress_set_end_height_message (&prog_obj; *p, const gchar * message)
Progress update step
The update hook will be called at regular intervals, and it will be passed the completion percentage
as the argument.
The update step can be specified through:
LqrRetVal lqr_progress_set_update_stepLqrProgress* pgfloat update_step
The default step is 0.02 (i.e. 2%).
Releasing the memory
&carv_obj; objects can be destroyed using this function:
void lqr_carver_destroyLqrCarver* carver
This function also destroys any attached object, thus it should never be called on attached carvers.
&vmap_obj; objects can be destroyed using this function:
void lqr_vmap_destroyLqrVMap* vmapLqR library API referenceTypes defined by the libraryLqrRetVal3LqrRetValthe return value of many &lqrl; functionsDescription
The return type of many functions in the &lqrl; is LqrRetVal, which is an
enum type that can take these values:
&err_ok;
everyting OK
&err_err;
generic fatal error
&err_nomem;
not enough memory
&err_cancel;
action cancelled by the user
The user should handle the error values explicitly at each function call returning this type.
See alsoLqrColDepth3LqrColDepthcarver objects colour depth specificationDescription
The default &carv_obj; object constructor lqr_carver_new uses a colour
depth of 8 bits per channel, and therefore its input must be an array of unsigned
chars. However, the &carv_obj; objects can handle images of grater colour depth, if
they are created with the lqr_carver_new_ext constructor. The possible
colour depths are specified through variables of type LqrColDepth, which is an enum
type; its possible values, and the type of the input buffer associated with them, are:
&col_depth_8i;
use type guchar (8 bit unsigned integers) - the default
&col_depth_16i;
use type guint16 (16 bit unsigned integers)
&col_depth_32f;
use type gfloat (32 bit floating point)
&col_depth_64f;
use type gdouble (64 bit floating point)
These values are also relevant when reading out a &carv_obj; object with the functions
lqr_carver_scan_ext or lqr_carver_scan_line_ext, since
the readout buffer must be cast to the appropriate type to be actually read.
The colour depth of an &carv_obj; object can be obtained with the function
lqr_carver_get_col_depth.
See alsoLqrImageType3LqrImageTypecarver objects image type (colour model) specificationDescription
The &carv_obj; objects use knowledge about the image type they're working on in order to compute
correctly some quantities (e.g. the brightness) for the automatic feature detection. Image types
are set automatically by the constructors, but they can also be specified manually using
quantities of the type LqrImageType, which is an enum which can
take these values:
&img_type_grey;&img_type_greya;&img_type_rgb;&img_type_rgba;&img_type_cmy;&img_type_cmyk;&img_type_cmyka;&img_type_custom;
Use the function to set the image type of
a carver, and the function to read it out.
See alsoCarver objectslqr_carver_new3lqr_carver_newlqr_carver_new_extthe &carv_obj; object constructors#include <lqr.h>LqrCarver* lqr_carver_newguchar* buffergint widthgint heightgint channelsLqrCarver* lqr_carver_new_extvoid* buffergint widthgint heightgint channelsLqrColDepth colour_depthDescription
The functions lqr_carver_new and lqr_carver_new_ext
create a new &carv_obj; object from an image of size ¶m_w; * ¶m_h; with ¶m_channels;
colour channels.
The image must be stored in buffer as a plain array of unsigned chars
(for lqr_carver_new) or the appropriate type cast to void (for
lqr_carver_new_ext), ordered by row, then by column, then by colour
channel.
In the extended constructor lqr_carver_new_ext, the additional parameter
colour_depth is required to specify the colour depth of the buffer (see
for more information).
After calling the function, the buffer will be owned by the &carv_obj; object and must not be
accessed any more, unless you subsequently call the function.
The image type is et automatically from the value of channels according
to this table:
Image types assigned by defaultchannelstype1&img_type_grey;2&img_type_greya;3&img_type_rgb;4&img_type_rgba;5&img_type_cmyka;>5&img_type_custom;
Return value
The return value is the address of the newly created &carv_obj; object, or &ret_null; in case of
failure (insufficient memory).
See alsolqr_carver_destroy3lqr_carver_destroythe &carv_obj; object destructor#include <lqr.h>void lqr_carver_destroyLqrCarver* carverDescription
The function lqr_carver_destroy destroys the &carv_obj; object pointed to
by carver, and all of its attched components (visibility maps and
attached carvers). It must never be invoked over a carver which is attached to another one.
This function will not release the memory buffer passed to
if it was protected by calling
.
See alsolqr_carver_init3lqr_carver_initactivates an &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_initLqrCarver* carvergint delta_xgfloat rigidityDescription
The function lqr_carver_init initialises the &carv_obj; pointed to by
carver, so that it can compute the visibility maps as needed upon calls
of lqr_carver_resize.
The parameter delta_x controls the maximum transversal step a seam can
make. A value of 0 means straight seams. Normally, it is set to 1.
The parameter rigidity can be used to add a negative bias to non-straight
seams, and it is normally set to 0.
Visibility maps must not be loaded with the function lqr_vmap_load when
using this function, neither before nor after invoking it.
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_carver_set_image_type3lqr_carver_set_image_typesets the image type of an &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_set_image_typeLqrCarver* carverLqrImageType image_typeDescription
The function lqr_carver_set_image_type sets the image type of the
&carv_obj; pointed to by carver to image_type.
If image_type is equal to &img_type_custom;, it is assumed that there are
no alpha or black channels. You can set those independently using
and
.
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_carver_set_alpha_channel3lqr_carver_set_alpha_channelsets the alpha channel index in a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_set_alpha_channel LqrCarver * carver gint channel_indexDescription
The function lqr_carver_set_alpha_channel sets the alpha channel index of
the image stored in the &carv_obj; pointed to by carver to
channel_index (between 0 and channels -
1, where channels is the number of colour channels of the
carver).
Use a negative value for cahnnel_index to specify that no alpha channel
is present.
If the specified channel coincides with the current value of the black channel, the black
channel is unset.
Calling this function sets the image time of the carver to
&img_type_custom;.
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_carver_set_black_channel3lqr_carver_set_black_channelsets the black channel index in a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_set_black_channel LqrCarver * carver gint channel_indexDescription
The function lqr_carver_set_black_channel sets the black channel index of
the image stored in the &carv_obj; pointed to by carver to
channel_index (between 0 and channels -
1, where channels is the number of colour channels of the
carver).
Use a negative value for cahnnel_index to specify that no black channel
is present.
If the specified channel coincides with the current value of the alpha channel, the alpha
channel is unset.
Calling this function sets the image time of the carver to
&img_type_custom;. Furthermore, the image color model will be assumed to be subtractive by the
function when it computes the brightness or the luma.
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_carver_resize3lqr_carver_resizeliquid rescale a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_resizeLqrCarver* carvergint new_widthgint new_heightDescription
The function lqr_carver_resize performs the liquid rescaling over the
&carv_obj; object pointed to by carver. If a visibility map was loaded
through the function lqr_vmap_load, and the carver was not initialised, the
resizing operations must be limited to the direction and the sizes included in the loaded map.
If the carver was initialised through the function lqr_carver_init, there
are no limitations to the final size.
The resizing function can be called multiple times, and it will decide automatically whether the
computation of the visibility map is necessary or not. In case it isn't, the function returns
almost immediately, otherwise operations will proceed following the order given through the
function lqr_carver_set_resize_order. Currently, on-the-fly rescaling
without computation is only possible for a single direction at a time.
If the new size (in one direction or in both) is greater than or equal to the original size
multiplied by the enlargement step of the carver object (as obtained
through ), the rescaling will be performed in
multiple steps. At each step, the original size stored internally is reset to the new value;
therefore, each step in the process can be bigger then the previous one.
Whenever the resizing dirction changes (this may happen in a single call of the rescaling
function or through multiple calls), or if performing a multiple steps enlargement as per the
previous paragraph, the visibility map computed during the first direction rescale is dropped to
make place for the one for the second (and the original size of the image is reset to the
current value). These visibility maps can be saved by using the
lqr_carver_set_vmap_dump function, for inspection or future use.
Return value
The return value follows the &lqrl; signalling system. It returns an error if trying to exceed
the limitations of a loaded visibility map, or if passed a negative or null size.
See alsolqr_carver_flatten3lqr_carver_flattenflatten a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_flattenLqrCarver* carverDescription
The function lqr_carver_flatten can be used to discard the visibility map
information and flatten the multi-size image contained in the &carv_obj; object pointed to by
carver to its current state.
It will also reset the internally stored original width and height, as if the image was just
loaded in the &carv_obj; object.
This function must only be invoked over initialised &carv_obj; objects.
This function is called internally each time the rescaling direction changes, or at each new
step in a multiple-step enlargement, but, when calling it manually, the discarded visibility map
will not be dumped automatically by it; use the functions
or
in order to save it before invoking this function.
Return value
The return value follows the &lqrl; signalling system. Errors can occur for non-initialised
&carv_obj; objects or in case of insufficient memory.
See alsolqr_carver_cancel3lqr_carver_cancelcancel ongoing operations on a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_cancelLqrCarver* carverDescription
The function lqr_carver_cancel can be used to cancel an ongoing operation
which is currently being performed on the the &carv_obj; object pointed to by
carver. It must be used asynchronouly, from within an independent thread.
If an operation is in fact cancelled by this function, the function which was performing the
operation will return the value &err_cancel;, and so will do any other operation successively
called on the same &carv_obj; object whose return type is LqrRetVal;
otherwise it will have no effect.
Whenever a function returns &err_cancel;, it means that the &carv_obj; object is in an
inconsistent state, and, since there is currently no way to recover from this situation, any
further operation on that object must be avoided, and it must be destroyed.
This function will fail if invoked over attached &carv_obj; objects.
Return value
The return value follows the &lqrl; signalling system. However, it can be called multiple times,
so it will never return &err_cancel; itself.
See alsolqr_carver_scan_reset3lqr_carver_scan_resetreset the readout cursor of a multi-size image#include <lqr.h>void lqr_carver_scan_resetLqrCarver* carverDescription
The function lqr_carver_scan_reset resets the readout pointer associated
with the &carv_obj; object pointed to by carver to the start of the
image. (Normally, calling this function isn't needed, as the pointer is reset automatically
whenever an operation is performed or once a readout has completed.)
See alsolqr_carver_scan3lqr_carver_scanlqr_carver_scan_extread out a multi-size image one pixel at a time#include <lqr.h>gboolean lqr_carver_scanLqrCarver* carvergint* xgint* yguchar** rgbgboolean lqr_carver_scan_extLqrCarver* carvergint* xgint* yvoid** rgbDescription
The functions lqr_carver_scan and lqr_carver_scan_ext
are used to read out the multi-size image contained in the &carv_obj; object pointed to by
carver one pixel at a time. They store the pixel coordinates in the
variables pointed to by x and y, and the pixel
content in the array pointed to by rgb; then they move the readout
pointer to the next pixel, or they reset it if the end of the image is reached.
The first one must only be used on the &carv_obj; objects created with
lqr_carver_new, i.e. with 8-bit images, while the second one is general
(see ), but the rgb pointer must
be cast to the appropriate type to be used (i.e pass the address of a pointer to
void to the function lqr_carver_scan_ext, then cast it
to a pointer of the appropriate type and use this last one for reading the output).
The rgb variable will point to an array which is internal to the
&carv_obj; object, so there is no need to allocate memory for it. However, it should only be
accessed right after a call to the scan functions, and writing to it must be avoided.
Return value
These functions return &ret_true; in case the readout is successful and the end of the image
was not reached, &ret_false; otherwise.
If lqr_carver_scan is called over a non-8-bit &carv_obj; object,
it will return &ret_false;.
See alsolqr_carver_scan_by_row3lqr_carver_scan_by_rowtells if the image in &carv_obj; will be scanned by row or by column#include <lqr.h>gboolean lqr_carver_scan_by_rowLqrCarver* carverDescription
The function lqr_carver_scan_by_row must be used before calling the
functions
lqr_carver_scan_line and
lqr_carver_scan_line_ext,
in order to ascertain if those functions will scan the multi-size image contained in the
&carv_obj; object pointed to by carver by row or by column, which depends
on which was last rescaling direction and cannot be controlled directly by the user.
Return value
This function returns &ret_true; in case the image is going to be scanned by row, &ret_false; in
case it is going to be scanned by column;
See alsolqr_carver_scan_line3lqr_carver_scan_linelqr_carver_scan_line_extread out a multi-size image one line at a time#include <lqr.h>gboolean lqr_carver_scan_lineLqrCarver* carvergint* nguchar** rgbgboolean lqr_carver_scan_line_extLqrCarver* carvergint* nvoid** rgbDescription
The functions lqr_carver_scan_line and
lqr_carver_scan_line_ext are used to read out the multi-size image
contained in the &carv_obj; object pointed to by carver one line at a
time. They store the line number (row or column) in the variable pointed to by
n and the colour values in the array pointed to by
rgb; then they move the readout pointer to the next line, or they reset
it if the end of the image is reached.
The first one must only be used on the &carv_obj; objects created with
lqr_carver_new, i.e. with 8-bit images, while the second one is general,
but the rgb pointer must be cast to the appropriate type to be used (i.e
pass the address of a pointer to void to the function
lqr_carver_scan_line_ext, then cast it to a pointer of the appropriate type
and use this last one for reading the output).
Use the function before calling these to know
whether your image will be scanned by row or by column.
Return value
These functions return &ret_true; in case the readout is successful and the end of the image was
not reached, &ret_false; otherwise. If lqr_carver_scan_line is called over
a non-8-bit &carv_obj; object, it will return &ret_false;.
See alsolqr_carver_get_width3lqr_carver_get_widthget the current width of a &carv_obj; object#include <lqr.h>gint lqr_carver_get_widthLqrCarver* carverDescription
The function lqr_carver_get_width returns the current width of the image
contained in the &carv_obj; object pointed to by carver, in pixel units.
See alsolqr_carver_get_height3lqr_carver_get_heightget the current height of a &carv_obj; object#include <lqr.h>gint lqr_carver_get_heightLqrCarver* carverDescription
The function lqr_carver_get_height returns the current height of the image
contained in the &carv_obj; object pointed to by carver, in pixel units.
See alsolqr_carver_get_ref_width3lqr_carver_get_ref_widthget the reference width of a &carv_obj; object#include <lqr.h>gint lqr_carver_get_ref_widthLqrCarver* carverDescription
The function lqr_carver_get_ref_width returns the internal reference width
of the image contained in the &carv_obj; object pointed to by carver, in
pixel units.
The reference width is set as the original height at carver initialization, and reset any time
the carver gets subsequently flattened, either explicitly through or implicitly when the rescale direction changes or
an enlargment beyond the maximum enlargement step is performed.
See alsolqr_carver_get_ref_height3lqr_carver_get_ref_heightget the reference height of a &carv_obj; object#include <lqr.h>gint lqr_carver_get_ref_heightLqrCarver* carverDescription
The function lqr_carver_get_ref_height returns the internal reference
height of the image contained in the &carv_obj; object pointed to by
carver, in pixel units.
The reference height is set as the original height at carver initialization, and reset any time
the carver gets subsequently flattened, either explicitly through or implicitly when the rescale direction changes or
an enlargment beyond the maximum enlargement step is performed.
See alsolqr_carver_get_channels3lqr_carver_get_channelslqr_carver_get_bppget the number of channels in a &carv_obj; object#include <lqr.h>gint lqr_carver_get_channelsLqrCarver* carvergint lqr_carver_get_bppLqrCarver* carverDescription
The functions lqr_carver_get_channels returns the number of colour channels
of the image contained in the &carv_obj; object pointed to by carver.
The function lqr_carver_get_bpp is an alias for
lqr_carver_get_channels, it is deprecated and it is maintained for backward
compatibility purposes only.
See alsolqr_carver_get_col_depth3lqr_carver_get_col_depthget the colour depth of a &carv_obj; object#include <lqr.h>LqrColDepth lqr_carver_get_col_depthLqrCarver* carverDescription
The function lqr_carver_get_col_depth returns the colour depth of the image
contained in the &carv_obj; object pointed to by carver.
See alsolqr_carver_get_image_type3lqr_carver_get_image_typeget the image type of a &carv_obj; object#include <lqr.h>LqrImageType lqr_carver_get_image_typeLqrCarver* carverDescription
The function lqr_carver_get_image_type returns the image type (i.e. colour
model) of the image contained in the &carv_obj; object pointed to by
carver.
See alsolqr_carver_get_enl_step3lqr_carver_get_enl_stepget the enlargement step of a &carv_obj; object#include <lqr.h>gfloat lqr_carver_get_enl_stepLqrCarver* carverDescription
The function lqr_carver_get_enl_step returns the enlargement step of the
&carv_obj; object pointed to by carver, i.e. the maximum enlargement
allowed in a single step for that carver, expressed as the ratio with respect to its reference
width (for horizontal rescalings) or height (for vertical rescalings). The returned value is
strictly greater than 1 and less than 2.
See alsolqr_carver_get_orientation3lqr_carver_get_orientationget the orientation of a &carv_obj; object#include <lqr.h>gint lqr_carver_get_orientationLqrCarver* carverDescription
The function lqr_carver_get_orientation returns the current orientation of
the visibility map internal to the &carv_obj; object pointed to by
carver, which is 0 if the last rescale operation has
been in the horizontal direction, 1 if it has been in the vertical direction.
See alsolqr_carver_get_depth3lqr_carver_get_depthget the depth of a &carv_obj; object#include <lqr.h>gint lqr_carver_get_depthLqrCarver* carverDescription
The function lqr_carver_get_depth returns the current depth of the
visibility map internal to the &carv_obj; object pointed to by vmap, i.e.
the maximum amount of scaling which can be performed with respect to the internal reference
sizes in the current orientation without updating the internal map.
See alsolqr_carver_set_enl_step3lqr_carver_set_enl_stepset the enlargement step of a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_set_enl_stepLqrCarver* carvergfloat enl_stepDescription
The function lqr_carver_set_enl_step sets the enlargement step of the
&carv_obj; object pointed to by carver to the value specified in
enl_step, which must be strictly greater than 1 and less than 2.
The enlargement step is the maximum enlargement ratio (with respect to either the original width
or original height of carver) which the function
lqr_carver_resize applies in a single step; if that function is asked a
greater enlargement, it divides the process in multiple steps (and updates the original sizes
accordingly at each new step - these can be readout at any time with
and
).
The default value for new &carv_obj; objects is 2.0.
Return value
The return value follows the &lqrl; signalling system. &err_err; is returned if the
enl_step parameter is out of bounds.
See alsolqr_carver_set_resize_order3lqr_carver_set_resize_orderset &carv_obj; object resize order#include <lqr.h>void lqr_carver_set_resize_orderLqrCarver* carverLqrResizeOrder resize_orderDescription
When the function is invoked and both the
horizontal and vertical sizes are different from the current ones, the rescaling occurs first in
one direction and then in the other.
The function lqr_carver_set_resize_order can be used to set which direction
to rescale first for the &carv_obj; object pointed to by carver. The
parameter resize_order can take either the value
LQR_RES_ORDER_HOR (horizontal rescale first) or
LQR_RES_ORDER_VERT (vertical rescale first). By default, when an &carv_obj;
object is created, the value is set to LQR_RES_ORDER_HORSee alsolqr_carver_set_dump_vmaps3lqr_carver_set_dump_vmapslqr_carver_set_no_dump_vmapsset the visibility maps autodump for an &carv_obj; object#include <lqr.h>void lqr_carver_set_dump_vmapsLqrCarver* carvervoid lqr_carver_set_no_dump_vmapsLqrCarver* carverDescription
Invoking function lqr_carver_set_dump_vmaps over the &carv_obj; object
pointed to by carver has the effect of activating the automatic dumping
of visibility maps at each rescale operation (which by default is turned off).
Rescale operations involving both directions will dump two maps.
The dumped maps will be attached to the &carv_obj; object and can be accessed at any later time
using the functions or a combination of
,
and .
Using this setting is pointless if the &carv_obj; object is not initialised.
The function lqr_carver_set_no_dump_vmaps reverts the effect of the
previous one (but the maps dumped so far will be kept).
Note that it is also possible to dump the visibility maps manually; however, using the automatic
dump is the only way to get intermidiate maps when the function
performs the rescaling in both directions, or in
more than one step.
See alsolqr_carver_set_side_switch_frequency3lqr_carver_set_side_switch_frequencyset &carv_obj; object side switch frequency#include <lqr.h>void lqr_carver_set_side_switch_frequencyLqrCarver* carverguint switch_frequencyDescription
When the function is invoked, it computes a
relevance value for each pixel in the image, then chooses the optimal seam to carve based on
such relvance values. 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.
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 function lqr_carver_set_side_switch_frequency sets the side switch
frequency to switch_frequency for the &carv_obj; object pointed to by
carver. This will have the effect that, for each rescale operation, the
favoured side will be switched switch_frequency times (or as much times
as the number of pixels to rescale).
The default value for newly created &carv_obj; objects is 0.
As for the final result, a very small value (e.g. 1 to 4)
will normally suffice to balance the left and right side of the image (or the top and the boddom
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.
See alsolqr_carver_set_progress3lqr_carver_set_progressset the progress report function for an &carv_obj; object#include <lqr.h>void lqr_carver_set_progressLqrCarver* carverLqrProgress* pDescription
The function lqr_carver_set_progress associates the progress indicator
pointed to by progress to the &carv_obj; object pointed to by
carver. Progress indicators objects are created with the function
.
By default, no progress indicator is used.
See alsolqr_carver_set_preserve_input_image3lqr_carver_set_preserve_input_imageset a flag to preserve the buffer passed to a &carv_obj; object upon creation#include <lqr.h>void lqr_carver_set_preserve_input_imageLqrCarver* carverDescription
The function lqr_carver_set_preserve_input_image flags the &carv_obj;
object pointed to by carver so that it does not alter in any way the
buffer which is passed to it by the constructor. It must be used before any resizing-related
operation takes place, either after the carver construction or after the
calls to or
.
See alsolqr_carver_set_use_cache3lqr_carver_set_use_cacheenable/disable &carv_obj; object cache#include <lqr.h>void lqr_carver_set_use_cacheLqrCarver* carvergboolean use_cacheDescription
The function lqr_carver_set_use_cache can be used to disable or enable the
cache for the &carv_obj; object pointed to by carver.
By default, the caching is on.
See alsolqr_carver_attach3lqr_carver_attachattach an &carv_obj; to another &carv_obj;#include <lqr.h>LqrRetVal lqr_carver_attachLqrCarver* carverLqrCarver* auxDescription
The function lqr_carver_attach is used to attach an &carv_obj; object
(pointed to by aux) to another one (pointed to by
carver). This will have the effect that each operation performed over
the carver object will be reflected on aux (they
will share the same visibility map).
This function must not be used after a visibility map was loaded into the base object (the one
pointed to by carver).
The object pointed to by aux must have the same original size as the base
object. Note that the original size information is reset whenever a flattening operation
occurs, or the rescaling direction changes, so that this function should be called befor
rescaling occurs.
There is no limitation on the number of &carv_obj; objects which is possible to attach. Nesting
is also possible. It is irrelevant if the aux carver is initialised or
not; from the moment of attachment, it will passively undergo all transformations performed over
carver.
Return value
The return value follows the &lqrl; signalling system. &err_err; is returned if the sizes of
carver and aux don't match.
See alsolqr_carver_list_start3lqr_carver_list_startget the staritng point of the attachement list in an &carv_obj; object#include <lqr.h>LqrCarverList* lqr_carver_list_startLqrCarver* carverDescription
The function lqr_carver_list_start returns the stating point of the
&carvl_obj; object associated with the &carv_obj; object pointed to by
carver, which is used to keep track of the &carv_obj; objects attached to
it.
The returned value is &ret_null; if there are no attached carvers.
Use the functions and
to access the list element individually, or the
function to operate on whole lists.
See alsolqr_carver_list_current3lqr_carver_list_currentget current &carv_obj; object in a &carvl_obj; object#include <lqr.h>LqrCarver* lqr_carver_list_currentLqrCarverList* listDescription
The function lqr_carver_list_current returns a pointer to the &carv_obj;
object corresponding to the current value of the list parameter, or
&ret_null; in case of errors.
See alsolqr_carver_list_next3lqr_carver_list_nextadvance the &carvl_obj; object#include <lqr.h>LqrCarverList* lqr_carver_list_nextLqrCarverList* listDescription
The function lqr_carver_list_next returns a pointer to the next attached
&carv_obj; object in list, or &ret_null; if the list has reached the end.
See alsolqr_carver_list_foreach3lqr_carver_list_foreachperform operations on all &carv_obj; objects in an &carvl_obj; object#include <lqr.h>LqrRetVal lqr_carver_list_foreachLqrCarverList* listLqrCarverFunc funcLqrDataTok dataLqrRetVal lqr_carver_list_foreach_recursiveLqrCarverList* listLqrCarverFunc funcLqrDataTok dataDescription
The function lqr_carver_list_foreach can be used to apply the function
func to all the &carv_obj; objects listed in list.
The parameter data is used to pass arguments to the function.
The list value should be obtained through the function
. The order in the list will then follow the one
in which carver objects were attached.
The function func is of type LqrCarverFunc, whose
prototype is defined by:
typedef LqrRetVal (*LqrCarverFunc) (LqrCarver *carver, LqrDataTok data);
The data argument is of type LqrDataTok, which
is defined as a union with the following fields:
&carv_obj;*carvergintintegergpointerdata
The function lqr_carver_list_foreach_recursive is equivelant to
lqr_carver_list_foreach, but it works recursively if the &carv_obj; objects
in list have themselves other attached &carv_obj; objects attached. In
this case, the function func will be applied to each element of the list
and to each element of the attached list recursively, before moving on to the next element.
See alsoVisibiliy mapslqr_vmap_new3lqr_vmap_newthe &vmap_obj; object constructor#include <lqr.h>LqrVMap* lqr_vmap_newgint* buffergint widthgint heightgint depthgint orientationDescription
The function lqr_vmap_new is the constructor for &vmap_obj; objects. It can
be used to convert saved data in a format which can be loaded in an &carv_obj; object.
The parameter buffer must point to an an array of
width * heightints holding the visibility information.
The parameter depth represents the maximum possible amount of rescaling
with the given map.
The parameter orientation must be 0 if the map is to
be used for horizontal rescaling, 1 if it is to be used for vertical
rescaling.
Visibility maps format
The buffer must be an array of integers of size
width * height. For an
horizontally oriented visibility map, the format is as such: each row must contain all values
between 1 and depth (included) exactly once, with low values indicating
the pixels which will be operated on first during rescaling. All other pixels must be 0, which
means that they won't be affected by rescaling. Such a map allows for horizontal rescaling in
the range from width - depth to
width + depth. The same
applies to vertically oriented visibility maps, with columns in place of rows and
height in place of width.
Return value
The function returns the newly created &vmap_obj; if successful, or &ret_null; in case of
insufficient memory.
See alsolqr_vmap_destroy3lqr_vmap_destroythe &vmap_obj; object destructor#include <lqr.h>void lqr_vmap_destroyLqrVMap* vmapDescription
The function lqr_vmap_destroy destroys the &vmap_obj; object. It is not
necessary to invoke it over visibility maps which were loaded in &carv_obj; objects, as this is
done already by the carver object destructor.
See alsolqr_vmap_get_data3lqr_vmap_get_dataget varous &vmap_obj; object quantities#include <lqr.h>gint* lqr_vmap_get_dataLqrVMap* vmapDescription
The function lqr_vmap_get_data returns an array with the data stored into
the &vmap_obj; object pointed to by vmap, ordered first by row, then by
column.
Reading the data requires retrieval of the other quantities, through the functions
,
,
and
.
See the &vmap_obj; objects format description in the page for
.
See alsolqr_vmap_get_depth3lqr_vmap_get_depthget the depth of an &vmap_obj; object#include <lqr.h>gint lqr_vmap_get_depthLqrVMap* vmapDescription
The function lqr_vmap_get_depth returns the depth of the &vmap_obj; object
pointed to by vmap, i.e. the maximum scaling allowed by it.
See the &vmap_obj; objects format description in the page for
&vmap_obj; constructor and destructor.
See alsolqr_vmap_get_width3lqr_vmap_get_widthget the width of an &vmap_obj; object#include <lqr.h>gint lqr_vmap_get_widthLqrVMap* vmapDescription
The function lqr_vmap_get_width returns the width of the &vmap_obj; object
pointed to by vmap.
See the &vmap_obj; objects format description in the page for
&vmap_obj; constructor and destructor.
See alsolqr_vmap_get_height3lqr_vmap_get_heightget the height of an &vmap_obj; object#include <lqr.h>gint lqr_vmap_get_heightLqrVMap* vmapDescription
The function lqr_vmap_get_height returns the height of the &vmap_obj;
object pointed to by vmap.
See the &vmap_obj; objects format description in the page for
&vmap_obj; constructor and destructor.
See alsolqr_vmap_get_orientation3lqr_vmap_get_orientationget the orientation of an &vmap_obj; object#include <lqr.h>gint lqr_vmap_get_orientationLqrVMap* vmapDescription
The function lqr_vmap_get_orientation returns the orientation of the
&vmap_obj; object pointed to by vmap, which is 0 for
horizontally oriented maps, 1 for vertically oriented ones.
See the &vmap_obj; objects format description in the page for
&vmap_obj; constructor and destructor.
See alsolqr_vmap_dump3lqr_vmap_dumpdump an &vmap_obj; object#include <lqr.h>LqrVMap* lqr_vmap_dumpLqrCarver* carverDescription
The function lqr_vmap_dump returns the current visibility map of the
&carv_obj; object pointed to by carver, or &ret_null; in case of errors.
See alsolqr_vmap_internal_dump3lqr_vmap_internal_dumpdump an &vmap_obj; objects into an &carv_obj; object#include <lqr.h>LqrRetVal lqr_vmap_internal_dumpLqrCarver* carverDescription
The function lqr_vmap_internal_dump dumps the current visibility map of the
&carv_obj; object pointed to by carver internally to it, attaching it to
the same &vmapl_obj; object list as the one used for automatic dumping (as activated by
.
See alsolqr_vmap_load3lqr_vmap_loadload an &vmap_obj; object into an &carv_obj; object#include <lqr.h>LqrRetVal lqr_vmap_loadLqrCarver* carverLqrVMap* vmapDescription
The function lqr_vmap_load loads the visibility map contained in the
&vmap_obj; object pointed to by vmap in the &carv_obj; object pointed to
by carver.
It can only be called over uninitialised carver objects, therefore care must be taken not to
exceed the loaded map depth when resizing (see the &vmap_obj; objects format description in the
page for ).
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_vmap_list_start3lqr_vmap_list_startget the &vmapl_obj; list attached to an &carv_obj;#include <lqr.h>LqrVMapList* lqr_vmap_list_startLqrCarver* carverDescription
The function lqr_vmap_list_start returns the stating point of the
&vmapl_obj; object associated with the &carv_obj; object pointed to by
carver, which is used to keep track of the &vmap_obj; objects internally
dumped by it.
The returned value is &ret_null; if there are no dumped visibility maps.
The function lqr_vmap_list_current returns the &vmap_obj; object
corresponding to the current value of the list parameter, or &ret_null;
in case of errors.
Use the functions and
to access the list element individually, or the
function to operate on whole lists.
See alsolqr_vmap_list_current3lqr_vmap_list_currentget current &vmap_obj; object in a &vmapl_obj; object#include <lqr.h>LqrVMap lqr_vmap_list_currentLqrVMapList* listDescription
The function lqr_vmap_list_current returns the &vmap_obj; object
corresponding to the current value of the list parameter, or &ret_null;
in case of errors.
See alsolqr_vmap_list_next3lqr_vmap_list_nextadvance the &vmapl_obj; object#include <lqr.h>LqrVMapList lqr_vmap_list_nextLqrVMapList* listDescription
The function lqr_vmap_list_next returns a pointer the next dumped
&vmap_obj; object in list, or &ret_null; if the list has reached the end.
See alsolqr_vmap_list_foreach3lqr_vmap_list_foreachperform operations on all &vmap_obj; objects in an &vmapl_obj; object#include <lqr.h>LqrRetVal lqr_vmap_list_foreachLqrVMapList* listLqrVMapFunc funcgpointer dataDescription
The function lqr_vmap_list_foreach can be used to apply the function
func to all the &vmap_obj; objects listed in list.
The parameter data is used to pass arguments to the function.
The list value should be obtained through the function
.
The function func is of type LqrVMapFunc, whose
prototype is defined by:
typedef LqrRetVal (*LqrVMapFunc) (LqrVMap *vmap, gpointer data);
The data argument is of type gpointer, which is
just a pointer to void.
See alsoEnergylqr_carver_set_energy_function_builtin3lqr_carver_bias_set_energy_function_builtinset a builtin energy function for a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_set_energy_function_builtinLqrCarver* carverLqrEnergyFuncBuiltinType ef_indDescription
The function lqr_carver_set_energy_function_builtin allows to pick a
builtin energy function for the &carv_obj; object pointed to by carver.
The possible values for ef_ind are:
LQR_EF_GRAD_XABS
absolute value of the brightness gradient in the direction of the rescaling
(this is the default)
LQR_EF_GRAD_SUMABS
sum of absolute values of the brightness gradients in both directions
LQR_EF_GRAD_NORM
norm of the brightness gradient
LQR_EF_LUMA_GRAD_XABS
absolute value of the luma gradient in the direction of the rescaling
LQR_EF_LUMA_GRAD_SUMABS
sum of absolute values of the luma gradients in both directions
LQR_EF_LUMA_GRAD_NORM
norm of the luma gradient
LQR_EF_NULL
null
All of the above gradient functions have a radius of 1 pixel.
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_carver_set_energy_function3lqr_carver_bias_set_energy_functionset a custom energy function for a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_set_energy_functionLqrCarver* carverLqrEnergyFunc en_funcgint radiusLqrEnergyReaderType reader_typegpointer extra_dataDescription
The function lqr_carver_set_energy_function assigns the energy function
en_func to the &carv_obj; object pointed to by
carver (see below for more details on custom functions definitions).
The parameter radius determines the size of the square region which
affects the computation around each pixel (the side of the square will be 2 *
radius + 1 pixels long).
The parameter reader_type sets the reader type used when reading the
image, and therefore it determines what quantity will be passed on to the function
en_func (see below for more details on reader types).
The parameter extra_data is a (void) pointer which can be used to pass on
additional values to the function ef_func.
Custom functions definition
The function en_func must be of type
LqrEnergyFunc, whose prototype is defined by:
typedef gfloat (*LqrEnergyFunc) (gint x, gint y, gint img_width, gint img_height, LqrReadingWindow * rwindow, gpointer extra_data);
Such a function is expected to compute the energy at pixel ¶m_x;, ¶m_y; based on the
knowledge of the current image size (obtained from ¶m_w; and ¶m_h;) and the content of
the image in a square around that pixel, which is passed through the
rwindow reading window.
In most cases, the parameters ¶m_x;, ¶m_y;, ¶m_w; and ¶m_h; would only be used
to determine whether the region under consideration is at the image boundary or not.
The rwindow content must be read using the function
.
Reader types
The LqrEnergyReaderType is an enum which can take these values
(also noted is the number of channels of the corresponging reading window):
LQR_ER_BRIGHTNESS
brightness (1 channel)
LQR_ER_BRIGHTNESS
luma (1 channel)
LQR_ER_RGBA
RGBA (4 channels)
LQR_ER_CUSTOM
read the normalised image channels as they are (as many channels as the image has)
These readouts always return values beetween 0 and 1.
Note that these readouts may have special meanings depending on the image type:
for LQR_GREY_IMAGE, LQR_GREYA_IMAGE and
LQR_CUSTOM_IMAGE images, the LQR_ER_LUMA
readout will yield the same result as LQR_ER_BRIGHTNESS
for LQR_CUSTOM_IMAGE images, the LQR_ER_BRIGHTNESS
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.
for LQR_CUSTOM_IMAGE images, the LQR_ER_RGBA
readout cannot be used: it will always return
0Return value
The return value follows the &lqrl; signalling system.
See alsolqr_carver_get_energy3lqr_carver_get_energylqr_carver_get_true_energylqr_carver_get_energy_imageget the energy map for a &carv_obj; object#include <lqr.h>LqrRetVal lqr_carver_get_energyLqrCarver* carvergfloat * buffergint orientation#include <lqr.h>LqrRetVal lqr_carver_get_true_energyLqrCarver* carvergfloat * buffergint orientation#include <lqr.h>LqrRetVal lqr_carver_get_energyLqrCarver* carvervoid * buffergint orientationLqrColDepth col_depthLqrImageType image_typeDescription
The function lqr_carver_get_energy writes the energy map of the &carv_obj;
object pointed to by carver to the given buffer,
in a format suitable for plotting: all values are in the range between 0 and
1, and the true values are mapped nonlinearly and stretched on this whole
range, so that the differences between the middle values are enhanced with respect to very high
or very low values.
The orientation parameter must be either 0 to get the
energy map used for horizontal scalings, or 1 to get the map for vertical
scalings.
The buffer must be allocated by the user before calling this function, and its size must be at
least ¶m_w; * ¶m_h;, where ¶m_w; and ¶m_h; are the current
width and height of the carver. The energy values are ordered by row
first, then by column.
The outcome will include the effect of the bias added to the carver, if
any.
This function can be called over non-initialised &carv_obj; objects, e.g. to provide previews on
the effect of different energy functions, but it can also be invoked at any later time. Note,
however, that in this latter case the carver could be flattened if
necessary, therefore the function invocation is potentially destructive of the internal
visibiliy map.
The function lqr_carvet_get_true_energy is identical to the previous one,
but the resulting buffer will contain the true energy, not scaled nor shifted.
The function lqr_carver_get_energy_image is very similar to the function
lqr_carveR_get_energy, but it can be used to fill directly an image buffer
of the format specified through the additional parameters col_depth and
image_type (see and
). The buffer must be passed as
void*, but it must point to a memory area with sufficient allocated space for the
chosen image type and colour depth. The image type cannot be &img_type_custom;.
For any choice of the parameters describing the image, the resulting
buffer will hold a greyscale image, ranging from black (lowest energy) to
white (highest energy). The opacity (alpha) will be set to 1, if present. All
the information will be stored in the black channel in &img_type_cmyk; and &img_type_cmyka;
image types.
Return values
The return values follow the &lqrl; signalling system. The function
lqr_carver_get_energy_image will return an error if
image_type is &img_type_custom;.
See alsolqr_rwindow_read3lqr_rwindow_readread the content of a &rwin_obj; object#include <lqr.h>gfloat lqr_rwindow_readLqrReadingWindow* rwindowgint xgint ygint channelDescription
The function lqr_rwindow_read returns the content of the reading window
rwindow at point ¶m_x;, ¶m_y; and at channel
channel.
The coordinates ¶m_x; and ¶m_y; are relative to the rwindow
centre, and they both can range from -radius to radius
(extremes included), where radius can be obtained with the function
.
The function returns 0 when the coordinates are out of range, either because
they are beyond the rwindow radius or because they are outside the image
boundary.
The channel parameter specifies which channel to read out; depending on
the rwindow reader type, the range and meaning of this parameter changes:
for the cases LQR_ER_BRIGHTNESS and LQR_ER_LUMA it must be
0, because the readout consists of a single channel, for
LQR_ER_RGBA it must be between 0 and 3
(and then the readout will contain the RGBA information), while for
LQR_ER_CUSTOM it must be one of the original image channels.
See alsolqr_rwindow_get_read_t3lqr_rwindow_get_read_tget the reader type of a &rwin_obj; object#include <lqr.h>LqrEnergyReaderType lqr_rwindow_get_read_tLqrReadingWindow* rwindowDescription
The function lqr_rwindow_get_read_t returns the reader type associated with
the reading window rwindow.
The reader types are described in the page for
.
See alsolqr_rwindow_get_radius3lqr_rwindow_get_radiusget the size of the region accessible from a &rwin_obj; object#include <lqr.h>gint lqr_rwindow_get_radiusLqrReadingWindow* rwindowDescription
The function lqr_rwindow_get_radius returns the radius of the region
accessible through the reading window rwindow.
The region is a square of size 2 * radius - 1 pixels.
See alsolqr_rwindow_get_channels3lqr_rwindow_get_channelsget the number of channels of a &rwin_obj; object#include <lqr.h>gint lqr_rwindow_get_channelsLqrReadingWindow* rwindowDescription
The function lqr_rwindow_get_channels returns the number of channels of
reading window rwindow.
This function is actually only necessary when the rwindow reader type is
LQR_ER_CUSTOM.
The reader types are described in the page for
.
See alsolqr_carver_set_gradient_function3lqr_carver_set_gradient_functionset the gradient function for an &carv_obj; object#include <lqr.h>void lqr_carver_set_gradient_functionLqrCarver* carverLqrGradFuncType gf_indDescription
The function lqr_carver_set_gradient_function is deprecated and should not
be used in newly written code. The function
should be used instead.
The function lqr_carver_set_gradient_function is still maintained for
backwards compatibility reasons; its result is equivalent to calling
lqr_carver_set_energy_function_builtin, with the following mapping between
the argument gs_ind of the former and the argument
ef_ind of the latter:
LqrGradFuncTypeLqrEnergyFuncBuiltinTypeLQR_GF_XABSLQR_EF_GRAD_XABSLQR_GF_SUMABSLQR_EF_GRAD_SUMABSLQR_GF_NORMLQR_EF_GRAD_NORMLQR_GF_NULLLQR_EF_NULLSee alsoBiaslqr_carver_bias_add3lqr_carver_bias_add_xylqr_carver_bias_add_arealqr_carver_bias_addlqr_carver_bias_add_rgb_arealqr_carver_bias_add_rgbupdate an &carv_obj; bias#include <lqr.h>LqrRetVal lqr_carver_bias_add_xyLqrCarver* carvergdouble biasgint xgint yLqrRetVal lqr_carver_bias_add_areaLqrCarver* carvergdouble* buffergint bias_factorgint widthgint heightgint x_offgint y_offLqrRetVal lqr_carver_bias_addLqrCarver* carvergdouble* buffergint bias_factorLqrRetVal lqr_carver_bias_add_rgb_areaLqrCarver* carvergdouble* buffergint bias_factorgint channelsgint widthgint heightgint x_offgint y_offLqrRetVal lqr_carver_bias_add_rgbLqrCarver* carvergdouble* buffergint bias_factorgint channelsForeword
All the functions described in this page are used to add a bias to &carv_obj; objects. A
positive biased pixel will be more likely to be avoided by seams, and thus be preserved during
rescaling, while a negative bias has the opposite effect.
All of these functions must be called before . If
called multiple times, the biases added at each call will sum up.
Adding a bias pixel by pixel
The function lqr_carver_bias_add_xy adds a bias to the ¶m_x;, ¶m_y;
pixel of the image loaded into the &carv_obj; object pointed to by carver
A typical value for bias_factor would be 1000 (in
absolute value).
Adding a bias from a buffer
The function lqr_carver_bias_add_area adds a bias to an area of the image
loaded into the &carv_obj; object pointed to by carver.
The parameter buffer must point to an array of doubles of
size width * height, ordered
first by rows, then by columns.
The offset of the area relative to the image can be specified through
x_off and y_off. The bias area can exceed the
boundary of the image, and the offsets can be negative.
The parameter bias_factor is an overall bias scale. A typical value when
the buffer contents are of the order of 1 would be 1000
(in absolute value).
The function lqr_carver_bias_add can be used when the area to add is of the
same size of the image loaded in the &carv_obj; object and the offsets are 0.
Adding a bias from an image
The functions lqr_carver_bias_add_rgb_area and
lqr_carver_bias_add_rgb are very similar to
lqr_carver_bias_add_area and lqr_carver_bias_add,
except that they use 8-bit multi-channel images as inputs.
The number of channels in the image is passed via the parameter channels.
The last channel is assumed to be the alpha (opacity) channel if channels
is equal to 2 or greater than 3 (if this is not the case,
use the previous functions).
The bias is computed from the average of the colour channels, multiplied by the value of the
alpha channel if present. For example, in RGBA images a white, nontransparent pixel is
equivalent to a value of 1.0 when using a buffer in
lqr_carver_bias_add_area.
Return values
The return values follow the &lqrl; signalling system.
See alsolqr_carver_bias_clear3lqr_carver_bias_clearclear an &carv_obj; bias#include <lqr.h>void lqr_carver_bias_clearLqrCarver* carverDescription
The function lqr_carver_bias_clear clears the bias from the &carv_obj;
object pointed to by carverSee alsoRigidity maskslqr_carver_rigmask_add3lqr_carver_rigmask_add_xylqr_carver_rigmask_add_arealqr_carver_rigmask_addlqr_carver_rigmask_add_rgb_arealqr_carver_rigmask_add_rgbupdate an &carv_obj; rigidity mask#include <lqr.h>LqrRetVal lqr_carver_rigmask_add_xyLqrCarver* carvergdouble rigiditygint xgint yLqrRetVal lqr_carver_rigmask_add_areaLqrCarver* carvergdouble* buffergint widthgint heightgint x_offgint y_offLqrRetVal lqr_carver_rigmask_addLqrCarver* carvergdouble* bufferLqrRetVal lqr_carver_rigmask_add_areaLqrCarver* carvergdouble* buffergint channelsgint widthgint heightgint x_offgint y_offLqrRetVal lqr_carver_rigmask_add_rgbLqrCarver* carvergdouble* buffergint channelsForeword
All the functions described in this page are used to add a rigidity mask to &carv_obj; objects.
Whenever one of these functions is called, a rigidity mask is activated for the whole image; the
mask contains coefficients which modulate the value of the rigidity (which is set with
) in different areas of the image.
It is very important to note that using no rigidity masks at all is equivalent to use a rigidity
mask over the whole image with all the values set to 1.0, but, when first
adding a rigidity mask to a &carv_obj; object, all the pixels outside the affected area will
have their rigidity set to zero; therefore, the functions
lqr_carver_rigmask_add_xy, lqr_carver_rigmask_add_area
and lqr_carver_rigmask_add_rgb_area actually affect the whole image,
despite their name.
All the functions must be called after lqr_carver_init and before
lqr_carver_resize. If called multiple times over the same area, new values
will replace the old ones.
Setting the rigidity mask pixel by pixel
The function lqr_carver_rigmask_add_xy sets the rigidity mask value of the
¶m_x;, ¶m_y; pixel of the image loaded into the &carv_obj; object pointed to by
carverSetting the rigidity mask from a buffer
The function lqr_carver_rigmask_add_area adds a rigidity mask to an area of
the image loaded in the &carv_obj; object pointed to by carver.
The parameter buffer must point to an array of doubles of
size width * height, ordered
first by rows, then by columns.
The offset of the area relative to the image are specified through x_off
and y_off. The rigidity mask area can exceed the boundary of the image,
and the offsets can be negative.
The values in the given buffer are scaled by the overall
rigidity value set when calling the function
lqr_carver_init.
The function lqr_carver_rigmask_add can be used when the area to add is of
the same size of the image loaded in the &carv_obj; object and the offsets are
0.
Setting the rigidity mask from an image
The functions lqr_carver_rigmask_add_rgb_area and
lqr_carver_rigmask_add_rgb are very similar to
lqr_carver_rigmask_add_area and
lqr_carver_rigmask_add, but use 8-bit multi-channel images as inputs.
The number of channels in the image is passed via the parameter channels.
The last channel is assumed to be the alpha (opacity) channel if channels
is equal to 2 or greater than 3 (if this is not the case,
use the previous functions).
The rigidity value is computed from the average of the colour channels, multiplied by the value
of the alpha channel if present. For example, in RGBA images a white, nontransparent pixel is
equivalent to a value of 1.0 when using a buffer in
lqr_carver_rigmask_add_area.
Return value
The return values follow the &lqrl; signalling system.
See alsolqr_carver_rigmask_clear3lqr_carver_rigmask_clearclear an &carv_obj; rigidity mask#include <lqr.h>void lqr_carver_rigmask_clearLqrCarver* carverDescription
The function lqr_carver_rigmask_clear clears the rigidity mask from the
&carv_obj; object pointed to by carverSee alsoProgress reportslqr_progress_new3lqr_progress_newthe &prog_obj; object constructor#include <lqr.h>LqrProgress* lqr_progress_newDescription
The function lqr_progress_new is the constructor for &prog_obj; objects. It
can be used to setup a progress report indicator for rescale operations performed through
.
Newly created &prog_obj; objects are inactive, and need to be set up using the functions
,
and
.
&prog_obj; objects are associated to &carv_obj; objects using the function
Return value
The function returns the newly created &prog_obj; if successful, or &ret_null; in case of
insufficient memory.
See alsolqr_progress_set_init3lqr_progress_set_initexecude custom code before each rescaling operation#include <lqr.h>LqrRetVal lqr_progress_set_initLqrProgress* pLqrProgressFuncInit init_funcDescription
The function lqr_progress_set_init sets the hook
init_func to the &prog_obj; object pointed to by
p.
The function init_func is of type
LqrProgressFuncInit, whose prototype is defined by:
typedef LqrRetVal (*LqrProgressFuncInit) (const gchar* init_message);
Each time that the function performs a rescale
operation (recall that it can perform more than one rescale operation at each call) this
function will be called first, with a string argument passed through the parameter
init_message, which is different for horizontal and vertical rescalings.
The message arguments can be set with the functions
and
.
The default values for newly created &prog_obj; objects are:
Horizontal:
&prog_init_w_mess;
Vertical:
&prog_init_h_mess;
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_progress_set_update3lqr_progress_set_updateexecude custom code at regular steps during each rescaling operation#include <lqr.h>LqrRetVal lqr_progress_set_updateLqrProgress* pLqrProgressFuncUpdate update_funcDescription
The function lqr_progress_set_update sets the hook
update_func to the &prog_obj; object pointed to by
p.
The function update_func is of type
LqrProgressFuncUpdate, whose prototype is defined by:
typedef LqrRetVal (*LqrProgressFuncUpdate) (gdouble completion_percentage);
Each time that the function performs a rescale
operation (recall that it can perform more than one rescale operation at each call) this
function will be called at regular intervale, with the current completion percentage
completion_percentage as an argument.
The update step can be set with the function
.
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_progress_set_end3lqr_progress_set_endexecude custom code after each rescaling operation#include <lqr.h>LqrRetVal lqr_progress_set_endLqrProgress* pLqrProgressFuncEnd end_funcDescription
The function lqr_progress_set_end sets the hook
end_func to the &prog_obj; object pointed to by p.
The function end_func is of type
LqrProgressFuncEnd, whose prototype is defined by:
typedef LqrRetVal (*LqrProgressFuncEnd) (const gchar* end_message);
Each time that the function performs a rescale
operation (recall that it can perform more than one rescale operation at each call) this
function will be called at the end, with a string argument passed through the parameter
end_message, which is different for horizontal and vertical rescalings.
The message arguments can be set with the functions
and
.
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_progress_set_update_step3lqr_progress_set_update_stepsetup update step for &prog_obj; objects#include <lqr.h>LqrRetVal lqr_progress_set_update_stepLqrProgress* pgfloat update_stepDescription
The function lqr_progress_set_update_step sets the update step of the
&prog_obj; pointed to by p to the value
update_step.
The update step must be between 0 and 1.
The default value is 0.02 (i.e. 2%).
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_progress_set_init_width_message3lqr_progress_set_init_width_messagesetup width message for init hooks in &prog_obj; objects#include <lqr.h>LqrRetVal lqr_progress_set_init_width_messageLqrProgress* pconst guchar* messageDescription
The function lqr_progress_set_init_width_message sets the string
message in the &prog_obj; object pointed to by p
as the argument when rescaling the width for init hooks set with
The default value for newly created &prog_obj; objects is: &prog_init_w_mess;
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_progress_set_init_height_message3lqr_progress_set_init_height_messagesetup height message for init hooks in &prog_obj; objects#include <lqr.h>LqrRetVal lqr_progress_set_init_height_messageLqrProgress* pconst guchar* messageDescription
The function lqr_progress_set_init_height_message sets the string
message in the &prog_obj; object pointed to by p
as the argument when rescaling the height for init hooks set with
The default value for newly created &prog_obj; objects is: &prog_init_h_mess;
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_progress_set_end_width_message3lqr_progress_set_end_width_messagesetup width message for end hooks in &prog_obj; objects#include <lqr.h>LqrRetVal lqr_progress_set_end_width_messageLqrProgress* pconst guchar* messageDescription
The function lqr_progress_set_end_width_message sets the string
message in the &prog_obj; object pointed to by p
as the argument when rescaling the width for end hooks set with
The default value for newly created &prog_obj; objects is:
"done".
Return value
The return value follows the &lqrl; signalling system.
See alsolqr_progress_set_end_height_message3lqr_progress_set_end_height_messagesetup height message for end hooks in &prog_obj; objects#include <lqr.h>LqrRetVal lqr_progress_set_end_height_messageLqrProgress* pconst guchar* messageDescription
The function lqr_progress_set_end_height_message sets the string
message in the &prog_obj; object pointed to by p
as the argument when rescaling the height for end hooks set with
The default value for newly created &prog_obj; objects is:
"done".
Return value
The return value follows the &lqrl; signalling system.
See alsoReferences
The library implements the algorithm described in the paper "Seam Carving for Content-Aware Image Resizing"
by Shai Avidan and Ariel Shamir, which can be found at
http://www.faculty.idc.ac.il/arik/imret.pdfAPI changes in new versions of the libraryNew symbols in version 0.4LqrImageTypelqr_carver_set_image_typelqr_carver_get_image_typelqr_carver_set_alpha_channellqr_carver_set_black_channellqr_carver_set_preserve_input_imagelqr_carver_set_use_cachelqr_carver_list_foreach_recursivelqr_carver_set_energy_function_builtinlqr_carver_set_energy_functionlqr_carver_get_energylqr_carver_get_true_energylqr_carver_get_energy_imagelqr_rwindow_readlqr_rwindow_get_read_tlqr_rwindow_get_radiuslqr_rwindow_get_channelslqr_carver_bias_add_xylqr_carver_bias_clearlqr_carver_rigmask_add_xylqr_carver_rigmask_clearlqr_carver_cancelNew symbols in version 0.3lqr_carver_get_enl_steplqr_carver_set_enl_steplqr_carver_get_ref_widthlqr_carver_get_ref_heightlqr_carver_get_orientationlqr_carver_get_depthNew symbols in version 0.2LqrColDepthlqr_carver_new_extlqr_carver_scan_extlqr_carver_scan_line_extlqr_carver_get_channelslqr_carver_get_col_depthlqr_carver_set_side_switch_frequencylqr_carver_rigmask_addlqr_carver_rigmask_add_arealqr_carver_rigmask_add_rgblqr_carver_rigmask_add_rgb_areaDeprecated symbolslqr_carver_get_bpplqr_carver_set_gradient_function