r17506 adds this option to the format pipe. I thought about adding it as a separate pipe, which may be useful in the case that you have to apply one mask, then another, etc. But for now it is easiest as option to apply only one mask in the existing format pipe.
I tested it for the command line case, so it should be easy enough to add it to php
Two new parameters you can now specify to your redux request: overlay and overlaycolor
overlay is the image file name (JPEG,PNG, or anything acceptable to PIL) that contains the mask. It can be either a 1 bit image (ones and zeros), 8 bit grey, or a RGBA image (with transparency mask). In the case of RGBA mask, the mask is pasted on top of the base image and can included colors with transparency. In the case of 1 bit or 8 bit, it represents the alpha channel (opacity value) and then you specify the color of the overlay with the overlaycolor option, which is an rgb value like "0,0,255" for blue.
It will always automatically resize the mask to match the final resized base image.
Here is an example where someone masked out the carbon in the corner of an image. I use redux to draw the mask in red:
redux --pipeline=leginon --filename=13mar29a_gr1_00035gr_00061sq_v02_00007hl_00004en --shape=512x512 --overlay=/ami/data00/appion/13mar29a/mask/manualrun1/masks/13mar29a_gr1_00035gr_00061sq_v02_00007hl_00004en_mask.png --scaletype=stdev --scalemax=5 --scalemin=-5 --oformat=PNG --overlaycolor=255,0,0 > test.png