Adding a bias
Prev | Chapter 2. LqR library API user manual | Next

## Adding a bias

### Foreword

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.

### Important

The bias has to be added before the resizing takes place (but it can be added before initialisation since version 0.4).

### Note

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_xy(` | LqrCarver* carver,
| gdouble bias,
| gint x,
| gint 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_add(` | LqrCarver* carver,
| gdouble* buffer,
| gint 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).

### Note

This function, and all the following, will not swallow the buffer (to the contrary of what happens e.g. when creating a new `LqrCarver` 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_rgb(` | LqrCarver* carver,
| guchar* buffer,
| gint bias_factor,
| gint 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.

### Important

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 `LqrCarver` 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_area(` | LqrCarver* carver,
| gdouble* buffer,
| gint bias_factor,
| gint width,
| gint height,
| gint x_off,
| gint y_off`)`;

while for the rgb image case use:

`LqrRetVal lqr_carver_bias_add_rgb_area(` | LqrCarver* carver,
| guchar* buffer,
| gint bias_factor,
| gint channels,
| gint width,
| gint height,
| gint x_off,
| gint y_off`)`;

In both functions, `width` and `height` 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 ``width` * `height`` (or ``width` * `height` * `channels`` for the rgb case) but the specified areas need not to be strictly included inside the `LqrCarver` image area: only the parts which overlap with it will be used. For example, the offsets can also be negative.

Prev | Up | Next
Automatic feature detection | Home | Adding a rigidity mask