image.putregion - Function

Put pixels and mask into a region-of-interest of the image

Synopsis
putregion(pixels, pixelmask, region, list, usemask, locking, replicate)

Arguments

pixels	in	The pixel values
		Allowed:	Glish numeric array
		Default:	None
pixelmask	in	The pixel mask values
		Allowed:	Glish Boolean array
		Default:	None
region	in	The region of interest
		Allowed:	Region tool
		Default:	Whole image
list	in	List the bounding box and any mask creation to the logger
		Allowed:	T or F
		Default:	F
usemask	in	Honour the mask when putting pixels
		Allowed:	T or F
		Default:	T
locking	in	Unlock image after use ?
		Allowed:	T or F
		Default:	T
replicate	in	Replicate array through image
		Allowed:	T or F
		Default:	F

Returns
T or fail

Description

This function replaces data and/or pixel mask values in the image in the specified region-of-interest. The pixels and/or pixelmask arrays must be the shape of the bounding box, and the whole bounding box is replaced in the image. The region-of-interest is really only used to specify the bounding box. If the region extends beyond the image, it is truncated. If the pixels or pixelmask array shapes do not match the bounding box, an error will result.

When you put a pixel mask, it either replaces the current default pixel mask, or is created. The pixel mask is put before the pixels.

The argument usemask is only relevant when you are putting pixel values and there is a pixel mask (meaning also the one you might have just put in place). If usemask=T then only pixels for which the mask is good (T) are altered. If usemask=F then all the pixels in the region are altered - the mask is ignored.

The argument replicate can be used to replicate the array throughout the image (from the blc to the trc). For example, if you provide a 2D array to a 3D image, you can replicate it through the third axis by setting replicate=T. The replication is done in the specified region.

The argument locking controls two things. If True, then after the function is called, the image is unlocked (so some other process can acquire a lock) and it is indicated that the image has changed (causes function view to redisplay the image if it is has been called). The reason for having this argument is that the unlocking and updating processes are quite expensive. If you are repeatedly calling putchunk in a for loop, you would be advised to use this switch.

See the related functions putchunk, set and calc.

Example

Suppose that we have a 2-dimensional image. First we recover the pixel and pixel mask values from a polygonal region. Then we change the values in the array that are within the region to zero and replace the data.

- im := image('myimage')                      # Create image tool
- x := dq.quantity([3,6,9,6,5,5,3],'pix')       # X vector, in absolute pixels
- y := dq.quantity([3,4,7,9,7,5,5],'pix')       # Y vector, in absolute pixels
- r1 := drm.wpoly(x,y,csys=im.coordsys())     # Create polygonal world region
- local pixels, pixelmask
- im.getregion(pixels, pixelmask, r1, F)      # Recover pixels and mask
- pixels[pixelmask] := 0                      # Set pixels where mask is T to zero
- im.putregion(pixels=pixels, region=r1)      # Replace pixels only

Next: image.rebin - Function Up: image - Tool Previous: image.putchunk - Function Contents Index

	Package	general
	Module	images
	Tool	image