Tuning
Prev | Chapter 2. LqR library API user manual | Next

## 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 `LqrCarver` 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 * carver`)`;

### Choosing 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_order(` | LqrCarver* carver,
| LqrResizeOrder 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_frequency(` | LqrCarver* carver,
| guint switch_frequency`)`;

The default value for newly created `LqrCarver` 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_cache(` | LqrCarver* carver,
| gboolean use_cache`)`;

To disable the cache, set `use_cache` to `FALSE`. To re-enable it back, set it to `TRUE`.

Prev | Up | Next
Adding a rigidity mask | Home | Dealing with the visibility maps (the seams)