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.