inplace

inplace — in-place paintbox operations: flood, paste, line, circle

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

int                 im_draw_rect                        (VipsImage *image,
                                                         int left,
                                                         int top,
                                                         int width,
                                                         int height,
                                                         int fill,
                                                         PEL *ink);
int                 im_draw_circle                      (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         int radius,
                                                         gboolean fill,
                                                         PEL *ink);
int                 im_draw_image                       (VipsImage *image,
                                                         VipsImage *sub,
                                                         int x,
                                                         int y);
int                 (*VipsPlotFn)                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         void *a,
                                                         void *b,
                                                         void *c);
int                 im_draw_line_user                   (VipsImage *image,
                                                         int x1,
                                                         int y1,
                                                         int x2,
                                                         int y2,
                                                         VipsPlotFn plot,
                                                         void *a,
                                                         void *b,
                                                         void *c);
int                 im_draw_line                        (VipsImage *image,
                                                         int x1,
                                                         int y1,
                                                         int x2,
                                                         int y2,
                                                         PEL *ink);
int                 im_lineset                          (VipsImage *in,
                                                         VipsImage *out,
                                                         VipsImage *mask,
                                                         VipsImage *ink,
                                                         int n,
                                                         int *x1v,
                                                         int *y1v,
                                                         int *x2v,
                                                         int *y2v);
int                 im_draw_flood                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink,
                                                         VipsRect *dout);
int                 im_draw_flood_blob                  (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink,
                                                         VipsRect *dout);
int                 im_draw_flood_other                 (VipsImage *image,
                                                         VipsImage *test,
                                                         int x,
                                                         int y,
                                                         int serial,
                                                         VipsRect *dout);
int                 im_draw_mask                        (VipsImage *image,
                                                         VipsImage *mask_im,
                                                         int x,
                                                         int y,
                                                         PEL *ink);
int                 im_draw_point                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink);
int                 im_read_point                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink);
int                 im_draw_smudge                      (VipsImage *image,
                                                         int left,
                                                         int top,
                                                         int width,
                                                         int height);

Description

These operations directly modify the image. They do not thread, on 32-bit machines they will be limited to 2GB images, and a little care needs to be taken if you use them as part of an image pipeline.

They are mostly supposed to be useful for paintbox-style programs.

Details

im_draw_rect ()

int                 im_draw_rect                        (VipsImage *image,
                                                         int left,
                                                         int top,
                                                         int width,
                                                         int height,
                                                         int fill,
                                                         PEL *ink);

Paint pixels within left, top, width, height in image with ink. If fill is zero, just paint a 1-pixel-wide outline.

See also: im_draw_circle().

image :

image to draw on

left :

area to paint

top :

area to paint

width :

area to paint

height :

area to paint

fill :

fill the rect

ink :

paint with this colour

Returns :

0 on success, or -1 on error.

im_draw_circle ()

int                 im_draw_circle                      (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         int radius,
                                                         gboolean fill,
                                                         PEL *ink);

Draws a circle on image. If fill is TRUE then the circle is filled, otherwise a 1-pixel-wide perimeter is drawn.

ink is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( image ) bytes.

See also: im_draw_line().

image :

image to draw on

x :

centre of circle

y :

centre of circle

radius :

circle radius

fill :

fill the circle

ink :

value to draw

Returns :

0 on success, or -1 on error.

im_draw_image ()

int                 im_draw_image                       (VipsImage *image,
                                                         VipsImage *sub,
                                                         int x,
                                                         int y);

Draw sub on top of image at position x, y. The two images must have the same Coding. If sub has 1 band, the bands will be duplicated to match the number of bands in image. sub will be converted to image's format, see im_clip2fmt().

See also: im_insert().

image :

image to draw on

sub :

image to draw

x :

position to insert

y :

position to insert

Returns :

0 on success, or -1 on error.

VipsPlotFn ()

int                 (*VipsPlotFn)                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         void *a,
                                                         void *b,
                                                         void *c);

A plot function, as used by im_draw_line_user() to draw on an image.

image :

image to draw on

x :

position to draw at

y :

position to draw at

a :

user data

b :

user data

c :

user data

im_draw_line_user ()

int                 im_draw_line_user                   (VipsImage *image,
                                                         int x1,
                                                         int y1,
                                                         int x2,
                                                         int y2,
                                                         VipsPlotFn plot,
                                                         void *a,
                                                         void *b,
                                                         void *c);

Calls plot for every point on the line connecting x1, y1 and x2, y2. If you pass im_draw_mask() as the plot operation, you can draw wide lines or lines with various brushes.

See also: im_draw_mask(), im_draw_line(), im_draw_circle().

image :

image to draw on

x1 :

start point

y1 :

start point

x2 :

end point

y2 :

end point

plot :

draw operation

a :

draw operation parameter

b :

draw operation parameter

c :

draw operation parameter

Returns :

0 on success, or -1 on error.

im_draw_line ()

int                 im_draw_line                        (VipsImage *image,
                                                         int x1,
                                                         int y1,
                                                         int x2,
                                                         int y2,
                                                         PEL *ink);

Draws a 1-pixel-wide line on an image.

ink is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( image ) bytes.

See also: im_draw_circle().

image :

image to draw on

x1 :

start point

y1 :

start point

x2 :

end point

y2 :

end point

ink :

value to draw

Returns :

0 on success, or -1 on error.

im_lineset ()

int                 im_lineset                          (VipsImage *in,
                                                         VipsImage *out,
                                                         VipsImage *mask,
                                                         VipsImage *ink,
                                                         int n,
                                                         int *x1v,
                                                         int *y1v,
                                                         int *x2v,
                                                         int *y2v);

im_draw_flood ()

int                 im_draw_flood                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink,
                                                         VipsRect *dout);

Flood-fill image with ink, starting at position x, y. The filled area is bounded by pixels that are equal to the ink colour, in other words, it searches for pixels enclosed by a line of ink.

The bounding box of the modified pixels is returned in dout. dout may be NULL.

See also: im_draw_flood_blob(), im_draw_flood_other().

image :

image to fill

x :

position to start fill

y :

position to start fill

ink :

colour to fill with

dout :

output the bounding box of the filled area

Returns :

0 on success, or -1 on error.

im_draw_flood_blob ()

int                 im_draw_flood_blob                  (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink,
                                                         VipsRect *dout);

Flood-fill image with ink, starting at position x, y. The filled area is bounded by pixels that are equal to the start pixel, in other words, it searches for a blob of same-coloured pixels.

The bounding box of the modified pixels is returned in dout. dout may be NULL.

See also: im_draw_flood(), im_draw_flood_other(), im_draw_flood_blob().

image :

image to fill

x :

position to start fill

y :

position to start fill

ink :

colour to fill with

dout :

output the bounding box of the filled area

Returns :

0 on success, or -1 on error.

im_draw_flood_other ()

int                 im_draw_flood_other                 (VipsImage *image,
                                                         VipsImage *test,
                                                         int x,
                                                         int y,
                                                         int serial,
                                                         VipsRect *dout);

Flood-fill image with serial, starting at position x, y. The filled area is bounded by pixels in test that are equal to the start pixel, in other words, it searches test for a blob of same-coloured pixels, marking those pixels in image with serial.

The bounding box of the modified pixels is returned in dout. dout may be NULL.

See also: im_draw_flood(), im_label_regions(), im_draw_flood_blob().

image :

image to mark

test :

image to test

x :

position to start fill

y :

position to start fill

serial :

mark pixels with this number

dout :

output the bounding box of the filled area

Returns :

0 on success, or -1 on error.

im_draw_mask ()

int                 im_draw_mask                        (VipsImage *image,
                                                         VipsImage *mask_im,
                                                         int x,
                                                         int y,
                                                         PEL *ink);

Draw a mask on the image. mask_im is a monochrome 8-bit image with 0/255 for transparent or ink coloured points. Intermediate values blend the ink with the pixel. Use with im_text() to draw text on an image.

ink is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( image ) bytes.

See also: im_draw_circle(), im_text(), im_draw_line_user().

image :

image to draw on

x :

draw mask here

y :

draw mask here

ink :

value to draw

mask_im :

mask of 0/255 values showing where to plot

Returns :

0 on success, or -1 on error.

im_draw_point ()

int                 im_draw_point                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink);

Draws a single point on an image.

ink is an array of bytes containing a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( im ) bytes.

See also: im_draw_line().

image :

image to draw on

x :

position to draw

y :

position to draw

ink :

value to draw

Returns :

0 on success, or -1 on error.

im_read_point ()

int                 im_read_point                       (VipsImage *image,
                                                         int x,
                                                         int y,
                                                         PEL *ink);

Reads a single point on an image.

ink is an array of bytes to contain a valid pixel for the image's format. It must have at least IM_IMAGE_SIZEOF_PEL( im ) bytes.

See also: im_draw_point().

image :

image to read from

x :

position to read

y :

position to read

ink :

read value here

Returns :

0 on success, or -1 on error.

im_draw_smudge ()

int                 im_draw_smudge                      (VipsImage *image,
                                                         int left,
                                                         int top,
                                                         int width,
                                                         int height);

Smudge a section of image. Each pixel in the area left, top, width, height is replaced by the average of the surrounding 3x3 pixels.

This an inplace operation, so image is changed. It does not thread and will not work well as part of a pipeline. On 32-bit machines it will be limited to 2GB images.

See also: im_draw_line().

image :

image to smudge

left :

area to smudge

top :

area to smudge

width :

area to smudge

height :

area to smudge

Returns :

0 on success, or -1 on error.