1.1.1.0 image.putchunk

NRAO Home > CASA > CASA Toolkit Reference Manual

image.putchunk - Function

1.1.1 Put pixels from an array into a regular region of the image

Description

This function puts an 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 zero. Any illegal inc values are set to unity.

An error 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. 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.

Arguments


Inputs
pixels	Numeric array. Required input.
	allowed:	any
	Default:	variant
blc	Bottom-Left-Corner (start) of location in image. Default is start of image.
	allowed:	intArray
	Default:	-1
inc	increment (stride) along axes
	allowed:	intArray
	Default:	1
list	List bounding box to logger?
	allowed:	bool
	Default:	false
locking	Unlock image after use?
	allowed:	bool
	Default:	true
replicate	Replicate array through image
	allowed:	bool
	Default:	false

Returns
bool

Example

We can clip all pixels to be {\tt <= } 5 as follows.

"""
#
print "\t----\t putchunk Ex 1 \t----"
ia.fromshape(shape=[10,10])   # create an example image
pix = ia.getchunk()           # get pixels to modify from example image
for i in range(len(pix)):
  pix[i] = list(pix[i])       # convert tuple to list so it can be modified
  for j in range(len(pix[i])):
    pix[i][j] = i*10 + j
  pix[i] = tuple(pix[i])      # convert list back to tuple
ia.putchunk(pix)              # put pixels back into example image
print pix                     # pixels have values 0-99
pix2 = ia.getchunk()          # get all pixels into an array (again)
for i in range(len(pix2)):
  pix2[i] = list(pix2[i])     # convert tuple to list so it can be modified
  for j in range(len(pix2[i])):
    if pix2[i][j] > 5:
      pix2[i][j] = 5          # clip values to 5
  pix2[i] = tuple(pix2[i])    # convert list back to tuple
ia.putchunk(pix2)             # put array back into image
print ia.getchunk()
ia.close()
#
"""

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

We could do so as follows:

"""
#
print "\t----\t putchunk Ex 2 \t----"
ia.fromshape(shape=[10,10,10])
imshape = ia.shape()
pix = ia.makearray(1, [imshape[0],imshape[1]])
ia.putchunk(pix, blc=[0,0,4])
print ia.getchunk()[0:3]
ia.close()
#
"""

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

"""
#
print "\t----\t putchunk Ex 3 \t----"
ia.fromshape(shape=[10,10,10])
imshape = ia.shape()
pix = ia.makearray(2, [1,imshape[1],imshape[2]])
ia.putchunk(pix)
print ia.getchunk()[0:3]
ia.close()
#
"""

__________________________________________________________________

[next] [prev] [prev-tail] [front] [up]

More information about CASA may be found at the CASA web page

This code is available under the terms of the GNU General Public Lincense