Vips.Region¶

Subclasses:: None

Methods¶

Inherited:: Vips.Object (27), GObject.Object (37)
Structs:: Vips.ObjectClass (1), GObject.ObjectClass (5)

class	`new` (image)
	`black` ()
	`buffer` (r)
	`copy` (dest, r, x, y)
	`equalsregion` (reg2)
	`fetch` (left, top, width, height, len)
	`height` ()
	`image` (r)
	`invalidate` ()
	`paint` (r, value)
	`paint_pel` (r, ink)
	`position` (x, y)
	`prepare` (r)
	`prepare_to` (dest, r, x, y)
	`region` (dest, r, x, y)
	`shrink_method` (to, target, method)
	`width` ()

Virtual Methods¶

Inherited:: Vips.Object (9), GObject.Object (7)

Properties¶

Inherited:: Vips.Object (2)

Signals¶

Inherited:: Vips.Object (4), GObject.Object (1)

Fields¶

Inherited:: Vips.Object (4), GObject.Object (1)

Name	Type	Access
bpl	`int`	r
data	`int`	r
im	`Vips.Image`	r
invalid	`bool`	r
parent_object	`Vips.Object`	r
seq	`object`	r
thread	`GLib.Thread`	r
type	`object`	r
valid	`Vips.Rect`	r
window	`object`	r

Class Details¶

class Vips.Region(**kwargs)¶

Bases:: Vips.Object
Abstract:: No
Structure:: Vips.RegionClass

A [class`Region`] represents a small, rectangular part of an image.

You use regions to read pixels out of images without having to have the whole image in memory at once.

A region can be a memory buffer, part of a memory-mapped file, part of some other image, or part of some other region.

Regions must be created, used and freed all within the same thread, since they can reference private per-thread caches. libvips sanity-checks region ownership in various places, so you are likely to see [func`GLib`.assert] errors if you don’t follow this rule.

There is API to transfer ownership of regions between threads, but (hopefully) this is only needed within libvips, so we don’t expose it.

classmethod new(image)¶

Parameters:: image (Vips.Image) – image to create this region on
Return type:: Vips.Region

Create a region. [class`Region`] start out empty, you need to call [method`Region`.prepare] to fill them with pixels.

::: seealso [method`Region`.prepare].

black()¶

Paints 0 into the valid part of self.

::: seealso [method`Region`.paint].

buffer(r)¶

Parameters:: r (Vips.Rect) – [struct`Rect`] of pixels you need to be able to address
Returns:: 0 on success, or -1 for error.
Return type:: int

The region is transformed so that at least r pixels are available as a memory buffer that can be written to.

copy(dest, r, x, y)¶

Parameters:

dest (Vips.Region) – destination region
r (Vips.Rect) – [struct`Rect`] of pixels you need to copy
x (int) – position of r in dest
y (int) – position of r in dest

Returns:

destination region

Return type:

dest: Vips.Region

Copy from one region to another. Copy area r from inside self to dest, positioning the area of pixels at x, y. The two regions must have pixels which are the same size.

::: seealso [method`Region`.paint].

equalsregion(reg2)¶

Parameters:: reg2 (Vips.Region) – region to test
Returns:: non-zero on equality.
Return type:: int

Do two regions point to the same piece of image? ie.

``c VIPS_REGION_ADDR(reg1, x, y) == VIPS_REGION_ADDR(reg2, x, y) && *VIPS_REGION_ADDR(reg1, x, y) ==

*VIPS_REGION_ADDR(reg2, x, y) for all x, y, reg1, reg2.

``

fetch(left, top, width, height, len)¶

Parameters:

left (int) – area of pixels to fetch
top (int) – area of pixels to fetch
width (int) – area of pixels to fetch
height (int) – area of pixels to fetch
len (int) –

Returns:

A copy of the pixel data.

Return type:

int

Generate an area of pixels and return a copy. The result must be freed with [func`GLib`.free]. The requested area must be completely inside the image.

This is equivalent to [method`Region`.prepare], followed by a memcpy. It is convenient for language bindings.

height()¶

Returns:: Height of the pixels held in region.
Return type:: int

image(r)¶

Parameters:: r (Vips.Rect) – [struct`Rect`] of pixels you need to be able to address
Returns:: 0 on success, or -1 for error.
Return type:: int

The region is transformed so that at least r pixels are available to be read from the image. The image needs to be a memory buffer or represent a file on disc that has been mapped or can be mapped.

invalidate()¶

Mark a region as containing invalid pixels. Calling this function means that the next time [method`Region`.prepare] is called, the region will be recalculated.

This is faster than calling [method`Image`.invalidate_all], but obviously only affects a single region.

::: seealso [method`Image`.invalidate_all], [method`Region`.prepare].

paint(r, value)¶

Parameters:

r (Vips.Rect) – area to paint
value (int) – value to paint

Paints value into self covering rectangle r. r is clipped against self->valid.

For int images, value is passed to memset()), so it usually needs to be 0 or 255. For float images, value is cast to a float and copied in to each band element.

r is clipped against self->valid.

::: seealso [method`Region`.black].

paint_pel(r, ink)¶

Parameters:

r (Vips.Rect) – area to paint
ink (int) – value to paint

Paints ink into self covering rectangle r. r is clipped against self->valid.

ink should be a byte array of the same size as an image pixel containing the binary value to write into the pixels.

::: seealso [method`Region`.paint].

position(x, y)¶

Parameters:

x (int) – position to move to
y (int) – position to move to

Returns:

0 on success, or -1 for error.

Return type:

int

Set the position of a region. This only affects reg->valid, ie. the way pixels are addressed, not reg->data, the pixels which are addressed. Clip against the size of the image. Do not allow negative positions, or positions outside the image.

prepare(r)¶

Parameters:: r (Vips.Rect) – [struct`Rect`] of pixels you need to be able to address
Returns:: 0 on success, or -1 on error.
Return type:: int

[method`Region`.prepare] fills self with pixels. After calling, you can address at least the area r with [funcREGION_ADDR] and get valid pixels.

[method`Region`.prepare] runs in-line, that is, computation is done by the calling thread, no new threads are involved, and computation blocks until the pixels are ready.

Use [method`Image`.sink_screen] to calculate an area of pixels in the background.

::: seealso [method`Image`.sink_screen], [method`Region`.prepare_to].

prepare_to(dest, r, x, y)¶

Parameters:

dest (Vips.Region) – region to write to
r (Vips.Rect) – [struct`Rect`] of pixels you need to be able to address
x (int) – position of r in dest
y (int) – position of r in dest

Returns:

0 on success, or -1 on error

Return type:

int

Like [method`Region`.prepare]: fill self with the pixels in area r.

Unlike [method`Region`.prepare], rather than writing the result to self, the pixels are written into dest at offset x, y.

Also unlike [method`Region`.prepare], dest is not set up for writing for you with [method`Region`.buffer]. You can point dest at anything, and pixels really will be written there. This makes [method`Region`.prepare_to] useful for making the ends of pipelines.

::: seealso [method`Region`.prepare], [method`Image`.sink_disc].

region(dest, r, x, y)¶

Parameters:

dest (Vips.Region) – region to connect to
r (Vips.Rect) – [struct`Rect`] of pixels you need to be able to address
x (int) – position of r in dest
y (int) – position of r in dest

Returns:

0 on success, or -1 for error.

Return type:

int

Make [funcREGION_ADDR] on self go to dest instead.

r is the part of self which you want to be able to address (this effectively becomes the valid field), (x, y) is the top LH corner of the corresponding area in dest.

Performs all clipping necessary to ensure that self->valid is indeed valid.

If the region we attach to is moved or destroyed, we can be left with dangling pointers! If the region we attach to is on another image, the two images must have the same sizeof(pel).

shrink_method(to, target, method)¶

Parameters:

to (Vips.Region) – destination region
target (Vips.Rect) – [struct`Rect`] of pixels you need to copy
method (Vips.RegionShrink) – method to use when generating target pixels

Returns:

to:: destination region

Return type:

(int, to: Vips.Region)

Write the pixels target in to from the x2 larger area in self. Non-complex uncoded images and LABQ only.

method selects the method used to do the 2x2 shrink.

::: seealso [method`Region`.copy].

width()¶

Returns:: Width of the pixels held in region.
Return type:: int