mosaicing: libvips Reference Manual

## mosaicing mosaicing — build image mosaics |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | vips_merge ()
int | vips_mosaic ()
int | vips_mosaic1 ()
int | vips_match ()
int | vips_globalbalance ()
int | vips_remosaic ()
int | vips_matrixinvert ()

## Includes

    #include <vips/vips.h>

## Description

These functions are useful for joining many small images together to make one large image. They can cope with unstable contrast and arbitrary sub-image layout, but will not do any geometric correction. Geometric errors should be removed before using these functions.

The mosaicing functions can be grouped into layers:

The lowest level operation is `vips_merge()` which joins two images together left-right or up-down with a smooth seam.

Next, `vips_mosaic()` uses search functions plus the two low-level merge operations to join two images given just an approximate overlap as a start point.

vips_mosaic1() is a first-order analogue of the basic mosaic functions: it takes two approximate tie-points and uses them to rotate and scale the right-hand or bottom image before starting to join.

Finally, `vips_globalbalance()` can be used to remove contrast differences in a mosaic which has been assembled with these functions. It takes the mosaic apart, measures image contrast differences along the seams, finds a set of correction factors which will minimise these differences, and reassembles the mosaic. `vips_remosaic()` uses the same techniques, but will reassemble the image from a different set of source images.

## Functions

### vips_merge ()

    int
    vips_merge (VipsImage *ref,
                VipsImage *sec,
                VipsImage **out,
                VipsDirection direction,
                int dx,
                int dy,
                ...);

Optional arguments:

- `mblend` : `gint`, maximum blend size

This operation joins two images left-right (with `ref` on the left) or up-down (with `ref` above) with a smooth seam.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>).

`dx` and `dy` give the displacement of `sec` relative to `ref` , in other words, the vector to get from the origin of `sec` to the origin of `ref` , in other words, `dx` will generally be a negative number.

`mblend` limits the maximum width of the blend area. A value of "-1" means "unlimited". The two images are blended with a raised cosine.

Pixels with all bands equal to zero are "transparent", that is, zero pixels in the overlap area do not contribute to the merge. This makes it possible to join non-rectangular images.

See also: `vips_mosaic()`, `vips_insert()`.

#### Parameters

ref | reference image |
sec | secondary image |
out | output image. | [out]
direction | horizontal or vertical merge |
dx | displacement of ref from sec |
dy | displacement of ref from sec |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mosaic ()

    int
    vips_mosaic (VipsImage *ref,
                 VipsImage *sec,
                 VipsImage **out,
                 VipsDirection direction,
                 int xref,
                 int yref,
                 int xsec,
                 int ysec,
                 ...);

Optional arguments:

- `bandno` : `gint`, band to search for features

- `hwindow` : `gint`, half window size

- `harea` : `gint`, half search size

- `mblend` : `gint`, maximum blend size

- `dx0` : `gint`, output, detected displacement

- `dy0` : `gint`, output, detected displacement

- `scale1` : `gdouble`, output, detected first order scale

- `angle1` : `gdouble`, output, detected first order rotation

- `dx1` : `gdouble`, output, detected first order displacement

- `dy1` : `gdouble`, output, detected first order displacement

This operation joins two images left-right (with `ref` on the left) or top-bottom (with `ref` above) given an approximate overlap.

`sec` is positioned so that the pixel (`xsec` , `ysec` ) in `sec` lies on top of the pixel (`xref` , `yref` ) in `ref` . The overlap area is divided into three sections, 20 high-contrast points in band `bandno` of image `ref` are found in each, and a window of pixels of size `hwindow` around each high-contrast point is searched for in `sec` over an area of `harea` .

A linear model is fitted to the 60 tie-points, points a long way from the fit are discarded, and the model refitted until either too few points remain or the model reaches good agreement.

The detected displacement is used with `vips_merge()` to join the two images together.

You can read out the detected transform with `dx0` , `dy0` , `scale1` , `angle1` , `dx1` , `dy1` .

See also: `vips_merge()`, `vips_insert()`.

#### Parameters

ref | reference image |
sec | secondary image |
out | output image. | [out]
direction | horizontal or vertical join |
xref | position in reference image |
yref | position in reference image |
xsec | position in secondary image |
ysec | position in secondary image |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mosaic1 ()

    int
    vips_mosaic1 (VipsImage *ref,
                  VipsImage *sec,
                  VipsImage **out,
                  VipsDirection direction,
                  int xr1,
                  int yr1,
                  int xs1,
                  int ys1,
                  int xr2,
                  int yr2,
                  int xs2,
                  int ys2,
                  ...);

Optional arguments:

- `search` : search to improve tie-points

- `hwindow` : half window size

- `harea` : half search size

- `interpolate` : interpolate pixels with this

- `mblend` : maximum blend size

This operation joins two images top-bottom (with `sec` on the right) or left-right (with `sec` at the bottom) given an approximate pair of tie-points. `sec` is scaled and rotated as necessary before the join.

If `search` is `TRUE`, before performing the transformation, the tie-points are improved by searching an area of `sec` of size `harea` for a object of size `hwindow` in `ref` .

`mblend` limits the maximum size of the blend area. A value of "-1" means "unlimited". The two images are blended with a raised cosine.

Pixels with all bands equal to zero are "transparent", that is, zero pixels in the overlap area do not contribute to the merge. This makes it possible to join non-rectangular images.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type (see table Smallest common format in <link linkend="libvips-arithmetic">arithmetic</link>).

See also: `vips_merge()`, `vips_insert()`, `vips_globalbalance()`.

#### Parameters

ref | reference image |
sec | secondary image |
out | output image |
direction | horizontal or vertical join |
xr1 | first reference tie-point |
yr1 | first reference tie-point |
xs1 | first secondary tie-point |
ys1 | first secondary tie-point |
xr2 | second reference tie-point |
yr2 | second reference tie-point |
xs2 | second secondary tie-point |
ys2 | second secondary tie-point |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_match ()

    int
    vips_match (VipsImage *ref,
                VipsImage *sec,
                VipsImage **out,
                int xr1,
                int yr1,
                int xs1,
                int ys1,
                int xr2,
                int yr2,
                int xs2,
                int ys2,
                ...);

Optional arguments:

- `search` : search to improve tie-points

- `hwindow` : half window size

- `harea` : half search size

- `interpolate` : interpolate pixels with this

Scale, rotate and translate `sec` so that the tie-points line up.

If `search` is `TRUE`, before performing the transformation, the tie-points are improved by searching an area of `sec` of size `harea` for a match of size `hwindow` to `ref` .

This function will only work well for small rotates and scales.

#### Parameters

ref | reference image |
sec | secondary image |
out | output image. | [out]
xr1 | first reference tie-point |
yr1 | first reference tie-point |
xs1 | first secondary tie-point |
ys1 | first secondary tie-point |
xr2 | second reference tie-point |
yr2 | second reference tie-point |
xs2 | second secondary tie-point |
ys2 | second secondary tie-point |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_globalbalance ()

    int
    vips_globalbalance (VipsImage *in,
                        VipsImage **out,
                        ...);

Optional arguments:

- `gamma` : gamma of source images

- `int_output` : `TRUE` for integer image output

vips_globalbalance() can be used to remove contrast differences in an assembled mosaic.

It reads the History field attached to `in` and builds a list of the source images that were used to make the mosaic and the position that each ended up at in the final image.

It opens each of the source images in turn and extracts all parts which overlap with any of the other images. It finds the average values in the overlap areas and uses least-mean-square to find a set of correction factors which will minimise overlap differences. It uses `gamma` to gamma-correct the source images before calculating the factors. A value of 1.0 will stop this.

Each of the source images is transformed with the appropriate correction factor, then the mosaic is reassembled. `out` is VIPS_FORMAT_FLOAT, but if `int_output` is set, the output image is the same format as the input images.

There are some conditions that must be met before this operation can work: the source images must all be present under the filenames recorded in the history on `in` , and the mosaic must have been built using only operations in this package.

See also: `vips_remosaic()`.

[method]

#### Parameters

in | mosaic to rebuild |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_remosaic ()

    int
    vips_remosaic (VipsImage *in,
                   VipsImage **out,
                   const char *old_str,
                   const char *new_str,
                   ...);

vips_remosaic() works rather as `vips_globalbalance()`. It takes apart the mosaiced image `in` and rebuilds it, substituting images.

Unlike `vips_globalbalance()`, images are substituted based on their file‐ names. The rightmost occurrence of the string `old_str` is swapped for `new_str` , that file is opened, and that image substituted for the old image.

It's convenient for multispectral images. You can mosaic one band, then use that mosaic as a template for mosaicing the others automatically.

See also: `vips_globalbalance()`.

[method]

#### Parameters

in | mosaic to rebuild |
out | output image. | [out]
old_str | gamma of source images |
new_str | gamma of source images |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_matrixinvert ()

    int
    vips_matrixinvert (VipsImage *m,
                       VipsImage **out,
                       ...);

This operation calculates the inverse of the matrix represented in `m` . The scale and offset members of the input matrix are ignored.

See also: `vips_matrixload()`.

[method]

#### Parameters

m | matrix to invert |
out | output matrix. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error