How to manipulate images from python

You can use the C++ APIs to manipulate images and bits of images from python, e.g.

import lsst.afw.geom as afwGeom
import lsst.afw.image as afwImage
im = afwImage.ImageF(10, 20)
 
bbox = afwGeom.BoxI(afwGeom.PointI(1, 2), afwGeom.ExtentI(4, 6))
sim = im.Factory(im, bbox)
sim.set(100)
del sim

sets a 4x10 portion of image im to 100 (I used im.Factory to avoid repeating afwImage.ImageF, rendering the code non-generic). I can't simply say sim = 100 as that'd make sim an integer rather than setting the pixel values to 100. I used an Image, but a Mask or a MaskedImage would work too (and I can create a sub-Exposure, although I can't assign to it).

This syntax gets boring fast.

We accordingly added some syntactic sugar at the swig level. I can write the preceeding example as:

im[1:5, 2:8] = 100

i.e. create a subimage and assign to it. afw's image slices are always shallow (but you can clone them as we shall see).

Note that the order is [x, y]**. This is consistent with our C++ code (e.g. it's PointI(x, y)), but different from numpy's matrix-like [row, column].

This opens up various possiblities; the following all work:

im[-1, :] =  -5
im[..., 18] =   -5      # the same as im[:, 18]
im[4,  10]   =  10
im[-3:, -2:] = 100
im[-2, -2]   = -10
sim = im[1:4, 6:10]
sim[:] = -1
im[0:4, 0:4] = im[2:6, 8:12]

You might expect to be able to say print im[0,20] but you won't get what you expect (it's an image, not a pixel value); say print float(im[0,20]) instead.

The one remaining thing that you can't do it make a deep copy (the left-hand-side has to pre-exist), but fortunately

im2 = im[0:3, 0:5].clone()

works.

numpy

You will remember that the previous section used [x, y] whereas numpy uses [row, column] which is different; you have been warned.

You can achieve similar effects using numpy. For example, after creating im as above, I can use getArray to return a view of the image (i.e. the numpy object shares memory with the C++ object), so:

import numpy as np
nim = im.getArray()
nim[1:5, 2:8] = 100

will also set a sub-image's value (but a different sub-image from im[1:5, 2:8]). You can do more complex operations using numpy syntax, e.g.

nim = im.getArray()

nim[:] = 100 + np.sin(nim) - 2*nim

which is very convenient, although there's a good chance that you'll be creating temporaries the size of im.