Generating the multi-size image
Prev | Chapter 2. LqR library API user manual | Next

## Generating the multi-size image

### Carver object creation

The `LqrCarver` 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 `LqrCarver` upon success, or `NULL` in case of insufficient memory.

In order to create `LqrCarver` 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:

`LQR_COLDEPTH_8I`

  8 bit unsigned integers (guchar)

`LQR_COLDEPTH_16I`

  16 bit unsigned integers (guint16)

`LQR_COLDEPTH_32F`

  32 bit floating point (gfloat)

`LQR_COLDEPTH_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 `LqrCarver` 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 `LqrCarver` object and must not be accessed directly any more (and of course it must not be freed, the `LqrCarver` destructor does it). If, instead, you want the Liquid Rescale library to keep the buffer intact, you must flag the `LqrCarver` 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 `LqrCarver` 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 `LqrCarver` and that would be enough (see the Importing a visibility map in a carver section).

If the visibility map has to be computed, the `LqrCarver` 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).

### Important

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:

- `LQR_GREY_IMAGE`
- `LQR_GREYA_IMAGE`
- `LQR_RGB_IMAGE`
- `LQR_RGBA_IMAGE`
- `LQR_CMY_IMAGE`
- `LQR_CMYK_IMAGE`
- `LQR_CMYKA_IMAGE`
- `LQR_CUSTOM_IMAGE`

When creating a `LqrCarver` object, the image type is inferred from the number of channels according to this table:

Table 2.1. Image types assigned by default

channels | type
--- | ---
1 | `LQR_GREY_IMAGE`
2 | `LQR_GREYA_IMAGE`
3 | `LQR_RGB_IMAGE`
4 | `LQR_RGBA_IMAGE`
5 | `LQR_CMYKA_IMAGE`
>5 | `LQR_CUSTOM_IMAGE`

When setting a carver to `LQR_CUSTOM_IMAGE`, 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_index`)`;

`LqrRetVal 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 `LQR_CUSTOM_IMAGE` in a carver normally requires special care in the choice and definitions of the energy functions (see the Automatic feature detection section).

### Note

Setting manually the alpha or black channel with the above functions automatically sets the carver image type to `LQR_CUSTOM_IMAGE`.

### Note

The support for CMY (and derived) color models is very naïve, since no color profiles are yet managed by the library.

Prev | Up | Next
Chapter 2. LqR library API user manual | Home | Liquid rescaling