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

## Reading the multi-size image

### Pixel 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 `LqrCarver` colour depth.

The return value is `FALSE` when the end of the image is reached, or the buffer has the wrong number of bits, `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 `FALSE`.

Here is a sample code usage:

Example 2.1. 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:

Example 2.2. 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 `LQR_COLDEPTH_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.

### Important

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

The function returns `TRUE` if the image is read by row, and `FALSE` if it is read by column.

Then, the image can be read through these functions:

`gboolean lqr_carver_scan_line(` | LqrCarver* carver,
| gint* n,
| guchar** rgb`)`;

or

`gboolean lqr_carver_scan_line_ext(` | LqrCarver* carver,
| gint* n,
| void** 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:

Example 2.3. 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:

Example 2.4. 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_reset(` | LqrCarver* carver`)`;

Prev | Up | Next
Liquid rescaling | Home | Automatic feature detection