Apply a functor to each pixel in an Image

afw supports for_each_pixel as a way to process each pixel in an Image, in a similar way to the STL's for_each. The name doesn't follow the LSST C++ guidelines, but in this case I felt that conformity to the spirit of the STL was more important. There are variants of for_each_pixel corresponding to setting a pixel to a function, setting it to a function of an Image, and setting it to a function of its value and a second Image's pixel value. The selection of which of these operations is desired is done by requiring the functor to inherit from a class such as pixelOp0 or pixelOp1XY, each of which is a std::function with a virtual operator() added.

for_each_pixel(Image<LhsT> &lhs, pixelOp0<LhsT> const& func)

Set each pixel in lhs to the value of func.

for_each_pixel(Image<LhsT> &lhs, pixelOp1<LhsT> const& func)

Set each pixel in lhs to the value of func(lhs).

for_each_pixel(Image<LhsT> &lhs, pixelOp1XY<LhsT> const& func)

Set each pixel in lhs to the value of func(x, y, lhs).

for_each_pixel(Image<LhsT> &lhs, Image<RhsT> const& rhs, pixelOp1<RhsT> const& func)

Set each pixel in lhs to the value of func(lhs).

for_each_pixel(Image<LhsT> &lhs, Image<RhsT> const& rhs, pixelOp2<Lhs, RhsT> const& func)

Set each pixel in lhs to the value of func(lhs, rhs).

for_each_pixel(Image<LhsT> &lhs, Image<RhsT> const& rhs, pixelOp2XY<Lhs, RhsT> const& func)

Set each pixel in lhs to the value of func(x, y, lhs, rhs).

Example of using for_each_pixel

This code is in forEachPixel.cc.

#include "lsst/afw/image/ImageAlgorithm.h"
 
namespace afwImage = lsst::afw::image;

Include needed header file, and define a namespace alias

template <typename T>
struct erase : public afwImage::pixelOp0<T> {
    T operator()() const { return 0; }
};

Here's the simplest possible functor, simply setting each pixel to 0. Note that operator() is declared const, as we pass these functors by (const) reference. If this surprises you, take a look at Meyers, Effective STL, Item 38.

 
template <typename T>
struct setVal
        : public afwImage::pixelOp0<T> {  // don't call it fill as people like to say using namespace std
    setVal(T val) : _val(val) {}
    T operator()() const { return _val; }
 
private:
    T _val;
};

This one's a bit more interesting. We save a value in the constructor, and use it to set each pixel. It's analogous to std::fill, but if I called it fill then following a using namespace std; the compiler would complain about ambiguity; it's simpler just to use a different name.

 
template <typename T>
struct addOne : public afwImage::pixelOp1<T> {
    T operator()(T val) const { return val + 1; }
};
 
template <typename T1, typename T2>
struct divide : public afwImage::pixelOp2<T1, T2> {
    T1 operator()(T1 lhs, T2 rhs) const { return lhs / rhs; }
};

Here are examples of pixelOp1 and pixelOp2.

 
template <typename T>
struct Gaussian : public afwImage::pixelOp1XY<T> {
    Gaussian(float a, float xc, float yc, float alpha) : _a(a), _xc(xc), _yc(yc), _alpha(alpha) {}
    T operator()(int x, int y, T val) const {
        float const dx = x - _xc;
        float const dy = y - _yc;
        return val + _a * ::exp(-(dx * dx + dy * dy) / (2 * _alpha * _alpha));
    }
 
private:
    float _a, _xc, _yc, _alpha;
};

A functor designed to add a Gaussian to an image

 
using namespace std;
 
int main() {
    afwImage::Image<float> img1(lsst::geom::Extent2I(10, 6));
    afwImage::Image<int> img2(img1.getDimensions());

Declare a couple of Images to play with

    // set img1 to 0 (actually, the constructor already did this)
    lsst::afw::image::for_each_pixel(img1, erase<float>());
 
    // Set img2 to 10
    lsst::afw::image::for_each_pixel(img2, setVal<int>(10));
    cout << img1(0, 0) << " " << img2(0, 0) << endl;
 
    // Set img1 += 1
    lsst::afw::image::for_each_pixel(img1, addOne<float>());
    cout << img1(0, 0) << " " << img2(0, 0) << endl;
 
    // Set img1 = img2 + 1
    lsst::afw::image::for_each_pixel(img1, img2, addOne<int>());
    cout << img1(0, 0) << " " << img2(0, 0) << endl;
 
    // Set img1 = 10, img2 = 3 then img1 /= img2
    lsst::afw::image::for_each_pixel(img1, setVal<float>(10));
    lsst::afw::image::for_each_pixel(img2, setVal<int>(3));
 
    lsst::afw::image::for_each_pixel(img1, img2, divide<float, int>());
    cout << img1(0, 0) << " " << img2(0, 0) << endl;

Apply erase to each pixel in img1, setVal to each pixel in img2, set img1 = img2 + 1, and finally img1 /= img1

 
    // Set img1 = 10 + Gaussian()
    float const peak = 1000.0;  // peak value
    float const xc = 5.0;       // center of Gaussian
    float const yc = 3.0;       //
    float const alpha = 1.5;    // "sigma" for Gaussian
 
    lsst::afw::image::for_each_pixel(img1, setVal<float>(10));
    lsst::afw::image::for_each_pixel(img1, Gaussian<float>(peak, xc, yc, alpha));
    cout << img1(0, 0) << " " << img1(xc, yc) << endl;

Add a Gaussian to the image, centered at (xc, yc) and with central intensity 1000.

}