image.getregion - Function

Get pixels and mask from a region-of-interest of the image

Synopsis
getregion(pixels, pixelmask, region, axes, mask, list, dropdeg)

Arguments

pixels	out	The recovered pixel values
		Allowed:	Glish array
pixelmask	out	The recovered pixel mask values
		Allowed:	Glish array
region	in	The region of interest
		Allowed:	Region tool
		Default:	Whole image
axes	in	Axes to average over
		Allowed:	Vector of positive integers
		Default:	None
mask	in	OTF mask
		Allowed:	Boolean LEL expression or mask region
		Default:	None
list	in	List the bounding box to the logger
		Allowed:	T or F
		Default:	F
dropdeg	in	Drop degenerate axes
		Allowed:	T or F
		Default:	F

Returns
T or fail

Description

This function recovers the image pixel and pixel mask values in the given region-of-interest. You can recover either or both of these by specifying the appropriate argument. Regardless of the shape of the region you have specified, the shape of the pixels and pixelmask arrays must necessarily be the bounding box of the specified region. If the region extends beyond the image, it is truncated.

Recall that the recovered pixel mask will reflect both the pixel mask stored in the image, and the region-of-interest (their masks are `anded') - see the discussion in the introduction about this.

The argument axes can be used to reduce the dimensionality of the output array. It specifies which pixel axes of the image average the data over. For example, consider a 3-D image. With axes=[1,2] and all other arguments left at their defaults, the result would be a 1-D vector, a profile along the third axis, with the data averaged over the first two axes.

This function differs in three ways from getchunk. First, the region can be much more complex (e.g. a union of polygons) than the simple blc, trc, and inc of getchunk (although such a region can be created of course). Second, it recovers the pixel mask as well as the pixels. Third, it is less efficient than getchunk for doing the same thing as getchunk. So if you are interested in say, iterating through an image, getting a regular hyper-cube of pixels and doing something with them, then getchunk will be faster. This would be especially noticeable if you iterated line by line through a large image.

Example
Suppose that we have a 3-dimensional image called cube and wish to recover the pixel and pixel mask values from a simple regular region.

- im := image('cube')
- r1 := drm.box(blc=[10,10,10], trc=[30,40])  # Create region 
- local pixels, pixelmask
- im.getregion(pixels, pixelmask, r1)

Example

- im := image('cube')
- local mm, pp
- im.getregion(pixels=pp)  
- im.getregion(pixelmask=mm)

In these examples we recover first the pixels only and then the pixel mask only.

Next: image.getslice - Function Up: image - Tool Previous: image.getchunk - Function Contents Index

	Package	general
	Module	images
	Tool	image