USAGE: bokeh [-d domain] [-s shape] [-r radius] [-p percent] [-t thresh] [-g gain] [-S sharp] [-T type] [-G graphic] infile outfile USAGE: bokeh [-h or -help]

-d ... domain .... convolution domain; choices are: spatial (s) or fourier (f);
.................. default=spatial
-s ... shape ..... shape of convolution kernel; choices are: triangle, square,
.................. pentagon, hexagon, circle, ring, star; default=pentagon
-r ... radius .... radius of shape; width and height of shape image will be
.................. approximately twice the radius; integer>0; default=15
-p ... percent ... percent of radius to use for the inner radius of the ring;
.................. 0<integer<100; default=85; unused for other shapes
-t ... thresh .... threshold to select only highlights in the image to apply the
.................. bokeh effect; 0<=integer<=100; default indicates no thresholding;
.................. nominal value is 90
-g ... gain ...... gain to apply to emphasize bokeh effect; float>=0; default=0
.................. (no emphasis); nominal is 2 when thresh not specified and 10
.................. when a threshold value is supplied
-S ... sharp ..... sharpening of bokeh effect; integer>=0; default=10
-T ... type ...... type of bokeh coloring when thresh is supplied; choices are:
.................. grayscale, truecolor or some actual color specification as name,
.................. hex or rgb values
-g ... graphic ... graphic mode; choices are: view (v) or save (s) shape image; if
.................. save, the graphic will be saved as shapename.gif, where shapename
.................. is the name of the shape as listed above

PURPOSE: To apply a bokeh blurring effect to an image.

DESCRIPTION: BOKEH applies a bokeh blurring effect to an image. This can be applied to the whole image or to just the image highlights. A choice of numerous shapes and sizes may be selected. The coloring of the bokeh effect may also be specified.

ARGUMENTS:

-d domain ... DOMAIN is the convolution domain for applying the bokeh blurring. The choices are: spatial (s) or fourier (f). The default=spatial. Use fourier, when applying the bokeh effect to large images, if speed is an issue. Different artifacts may be observe at the sides of the image when processing with one or the other domain.

-s shape ... SHAPE of the convolution kernel. The choices are: triangle, square, pentagon, hexagon, circle, ring and star. The default=pentagon. Note that small circles will not be perfectly round.

-r radius ... RADIUS of the shape. The width and height of the shape image will be approximately twice the radius. Values are integer>0. The default=15.

-p percent ... PERCENT of the (outer) radius to use for the inner radius of the ring. Values are 0<integer<100. The default=85. Not unused for other shapes.

-t thresh ... THRESH is the threshold used to select only highlights in the image to apply the bokeh effect. Values are 0<=integer<=100. The default indicates no thresholding, so that the bokeh effect is applied to the whole image. Nominal values are approximately 90.

-g gain ... GAIN to apply to emphasize (brighten) the bokeh effect. Values are float>=0. The default=0 (no emphasis). Nominal value is 2 when a threshold value is not specified and 10 when a threshold value is supplied. Gain when no thesholding will brighten the image, but to a lesser extent than in the highlight regions.

-S sharp ... SHARP applies a sharpening of the bokeh effect. Values are integer>=0. The default=10.

-T type ... TYPE of bokeh coloring when thresh is supplied. The choices are: grayscale, truecolor or some actual opaque color specification as a color name, hex value or rgb values. Grayscale will apply a grayscale brokeh effect. Truecolor will apply the bokeh effect using the image's color in that region. A color specification will colorize the bokeh effect using that color. The default=truecolor

-G graphic ... GRAPHIC mode. The choices are: view (v) or save (s) the shape image. The default is neither. If save is specified, then the graphic image will be saved as shapename.gif to the current directory, where shapename is the name of the shape as listed above.

REQUIREMENTS: NetPBM (PGM image format) for domain=spatial. Imagemagick 6.8.7-1 or higher (due to the use of -complex) and HDRI compiled for domain=fourier.

REFERENCES:
https://en.wikipedia.org/wiki/Bokeh

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.