draw: libvips Reference Manual

draw

draw — drawing operations: flood, paste, line, circle

Stability Level

Stable, unless otherwise indicated

Functions

int	vips_draw_rect ()
int	vips_draw_rect1 ()
int	vips_draw_point ()
int	vips_draw_point1 ()
int	vips_draw_image ()
int	vips_draw_mask ()
int	vips_draw_mask1 ()
int	vips_draw_line ()
int	vips_draw_line1 ()
int	vips_draw_circle ()
int	vips_draw_circle1 ()
int	vips_draw_flood ()
int	vips_draw_flood1 ()
int	vips_draw_smudge ()

Types and Values

enum	VipsCombineMode

Includes

#include <vips/vips.h>

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.

libvips operations are all functional: they take zero or more existing input images and generate zero or more new output images. Images are never altered, you always create new images. This means libvips can cache and thread very agressively.

The downside is that creating entirely fresh images each time can be very slow. libvips has a range of tricks to avoid these problems, but there are still times when you really have to be able to modify an image. An example might be drawing a curved line from a set of straight line segments: if you need to draw 1,000 straight lines, a 1,000 operation-deep pipeline is going to be a slow way to do it. This is where the draw operations come in.

To use these operations, use vips_copy() to make a copy of the image you want to modify to ensure that no one else is using it, then call a series of draw operations. Once you are done drawing, return to normal use of vips operations. Any time you want to start drawing again, you'll need to copy again.

Functions

vips_draw_rect ()

int
vips_draw_rect (VipsImage *image,
                double *ink,
                int n,
                int left,
                int top,
                int width,
                int height,
                ...);

Optional arguments:

fill : fill the rect

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

Parameters

image	image to draw on
ink	value to draw.	[array length=n]
n	length of ink array
left	area to paint
top	area to paint
width	area to paint
height	area to paint
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_rect1 ()

int
vips_draw_rect1 (VipsImage *image,
                 double ink,
                 int left,
                 int top,
                 int width,
                 int height,
                 ...);

Optional arguments:

fill : fill the rect

As vips_draw_rect(), but just take a single double for ink .

Parameters

image	image to draw on
ink	value to draw
left	area to paint
top	area to paint
width	area to paint
height	area to paint
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_point ()

int
vips_draw_point (VipsImage *image,
                 double *ink,
                 int n,
                 int x,
                 int y,
                 ...);

As vips_draw_rect(), but draw a single pixel at x , y .

Parameters

image	image to draw on
ink	value to draw.	[array length=n]
n	length of ink array
x	point to paint
y	point to paint
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_point1 ()

int
vips_draw_point1 (VipsImage *image,
                  double ink,
                  int x,
                  int y,
                  ...);

As vips_draw_point(), but just take a single double for ink .

Parameters

image	image to draw on
ink	value to draw
x	point to draw
y	point to draw
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_image ()

int
vips_draw_image (VipsImage *image,
                 VipsImage *sub,
                 int x,
                 int y,
                 ...);

Optional arguments:

mode : how to combine pixels

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 vips_cast().

Use mode to set how pixels are combined. If you use VIPS_COMBINE_MODE_ADD, both images muct be uncoded.

[method]

Parameters

image	image to draw on
sub	image to paint
x	draw `sub` here
y	draw `sub` here
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_mask ()

int
vips_draw_mask (VipsImage *image,
                double *ink,
                int n,
                VipsImage *mask,
                int x,
                int y,
                ...);

Draw mask on the image. mask 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 vips_text() to draw text on an image. Use in a vips_draw_line() subclass to draw an object along a line.

ink is an array of double containing values to draw.

[method]

Parameters

image	image to draw on
ink	value to draw.	[array length=n]
n	size of ink array
mask	mask of 0/255 values showing where to plot
x	draw mask here
y	draw mask here
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_mask1 ()

int
vips_draw_mask1 (VipsImage *image,
                 double ink,
                 VipsImage *mask,
                 int x,
                 int y,
                 ...);

As vips_draw_mask(), but just takes a single double for ink .

Parameters

image	image to draw on
ink	value to draw
mask	mask of 0/255 values showing where to plot
x	draw mask here
y	draw mask here
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_line ()

int
vips_draw_line (VipsImage *image,
                double *ink,
                int n,
                int x1,
                int y1,
                int x2,
                int y2,
                ...);

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

ink is an array of double containing values to draw.

[method]

Parameters

image	image to draw on
ink	value to draw.	[array length=n]
n	length of ink array
x1	start of draw_line
y1	start of draw_line
x2	end of draw_line
y2	end of draw_line
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_line1 ()

int
vips_draw_line1 (VipsImage *image,
                 double ink,
                 int x1,
                 int y1,
                 int x2,
                 int y2,
                 ...);

As vips_draw_line(), but just take a single double for ink .

Parameters

image	image to draw on
ink	value to draw
x1	start of draw_line
y1	start of draw_line
x2	end of draw_line
y2	end of draw_line
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_circle ()

int
vips_draw_circle (VipsImage *image,
                  double *ink,
                  int n,
                  int cx,
                  int cy,
                  int radius,
                  ...);

Optional arguments:

fill : fill the draw_circle

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 double containing values to draw.

[method]

Parameters

image	image to draw on
ink	value to draw.	[array length=n]
n	length of ink array
cx	centre of draw_circle
cy	centre of draw_circle
radius	draw_circle radius
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_circle1 ()

int
vips_draw_circle1 (VipsImage *image,
                   double ink,
                   int cx,
                   int cy,
                   int radius,
                   ...);

Optional arguments:

fill : fill the draw_circle

As vips_draw_circle(), but just takes a single double for ink .

Parameters

image	image to draw on
ink	value to draw
cx	centre of draw_circle
cy	centre of draw_circle
radius	draw_circle radius
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_flood ()

int
vips_draw_flood (VipsImage *image,
                 double *ink,
                 int n,
                 int x,
                 int y,
                 ...);

Optional arguments:

test : test this image
equal : fill while equal to edge
left : output left edge of bounding box of modified area
top : output top edge of bounding box of modified area
width : output width of bounding box of modified area
height : output height of bounding box of modified area

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 an edge of ink .

If equal is set, it instead searches for pixels which are equal to the start point and fills them with ink .

Normally it will test and set pixels in image . If test is set, it will test pixels in test and set pixels in image . This lets you search an image (test ) for continuous areas of pixels without modifying it.

left , top , width , height output the bounding box of the modified pixels.

ink is an array of double containing values to draw.

Parameters

image	image to draw on
ink	value to draw.	[array length=n]
n	length of ink array
x	centre of circle
y	centre of circle
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_flood1 ()

int
vips_draw_flood1 (VipsImage *image,
                  double ink,
                  int x,
                  int y,
                  ...);

Optional arguments:

test : test this image
equal : fill while equal to edge
left : output left edge of bounding box of modified area
top : output top edge of bounding box of modified area
width : output width of bounding box of modified area
height : output height of bounding box of modified area

As vips_draw_flood(), but just takes a single double for ink .

Parameters

image	image to draw on
ink	value to draw
x	centre of circle
y	centre of circle
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

vips_draw_smudge ()

int
vips_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.

Parameters

image	image to draw on
left	point to paint
top	point to paint
width	area to paint
height	area to paint
...	`NULL`-terminated list of optional named arguments

Returns

0 on success, or -1 on error.

Types and Values

enum VipsCombineMode

See vips_draw_image() and so on.

Operations like vips_draw_image() need to be told how to combine images from two sources.

Members

VIPS_COMBINE_MODE_SET	set pixels to the new value
VIPS_COMBINE_MODE_ADD	add pixels
VIPS_COMBINE_MODE_LAST