image.putchunk - Function

Put pixels from a Glish array into a regular region of the image

Synopsis
putchunk(pixels, blc, inc, list, locking, replicate)

Arguments

pixels	in	Glish numeric array
blc	in	Bottom-Left-Corner (start) of location in image
		Allowed:	Vector of integers
		Default:	Start of image
inc	in	increment (stride) along axes
		Allowed:	Vector of integers
		Default:	1
list	in	List bounding box to logger ?
		Allowed:	T or F
		Default:	F
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 puts a Glish array into the image file. If there is a default pixel mask it is ignored in this process. It is the complement of the getchunk function. You can specify the blc and inc if desired. If they are unspecified, they default to the beginning of the image and an increment of one.

Any illegal blc values are set to unity. Any illegal inc values are set to unity.

A fail will result if you attempt to put an array beyond the extent of the image (i.e., it is not truncated or decimated).

If there are fewer axes in the array than in the image, the array is assumed to have trailing axes of length unity. Thus, if you have a 2D array and want to put it in as the YZ plane rather than the XY plane, you must ensure that the shape of the array is [1,nx,ny].

However, 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 from the specified blc to the end of the image. Use function putregion if you want to terminate the replication at a trc value.

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.

A related function is putregion which puts the pixels and masks into a more complex region-of-interest. Function putchunk is retained because it is faster and therefore preferable for repeated operation in loops if the pixel mask is not required.

See also the functions set and calc which can also change pixel values.

Example

We can clip all pixels to be <= 5 as follows.

- pix := im.getchunk()               # get all pixels into a Glish array
- pix[pix > 5] := 5                  # clip values to 5
- im.putchunk(pix)                   # put array back into image

The above example shows how you could clip an image to a value. If all the pixels didn't easily fit in memory, you would iterate through the image chunk by chunk to avoid exhausting virtual memory. Better would be to do this via LEL through function calc.

Suppose we wanted to set the fifth XY plane to 0.

We could do so as follows:

- im := image('myimage')
- imshape := im.shape()
- pix := array(0, imshape[1], imshape[2])
- im.putchunk(pix, blc=[1,1,5])

Suppose we wanted to set the first YZ plane to 0.

- pix := array(0, 1, imshape[2], imshape[3])
- im.putchunk(pix)

Next: image.putregion - Function Up: image - Tool Previous: image.pixelvalue - Function Contents Index

	Package	general
	Module	images
	Tool	image