draw

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

Stability Level

Stable, unless otherwise indicated

Types and Values

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.

See also: vips_draw_circle().

[method]

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 .

See also: vips_draw_rect().

[method]

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 .

See also: vips_draw_rect().

[method]

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 .

See also: vips_draw_point().

[method]

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.

See also: vips_draw_mask(), vips_insert().

[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.

See also: vips_text(), vips_draw_line().

[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 .

See also: vips_draw_mask().

[method]

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.

See also: vips_draw_line1(), vips_draw_circle(), vips_draw_mask().

[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 .

See also: vips_draw_line().

[method]

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.

See also: vips_draw_circle1(), vips_draw_line().

[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 .

See also: vips_draw_circle().

[method]

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.

See also: vips_draw_flood1().

[method]

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 .

See also: vips_draw_flood().

[method]

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.

See also: vips_draw_line().

[method]

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.

See also: vips_join().

Members

VIPS_COMBINE_MODE_SET

set pixels to the new value

 

VIPS_COMBINE_MODE_ADD

add pixels

 

VIPS_COMBINE_MODE_LAST