KJB
kjb::Fftw_image_convolution Class Reference

this is a simple adaptation of Fftw_convolution_2d to Image input. More...

`#include <i_mt_convo.h>`

## Public Member Functions

please see ctor of class Fftw_convolution_2d More...

set mask, which must fit with mask size maxima given to ctor More...

set mask to a circular gaussian kernel of given sigma (pixels) More...

Fftw_convolution_2d::Work_buffer allocate_work_buffer () const

const Fftw_convolution_2d::Sizesget_sizes () const

read access of the flag indicating whether the mask has been set More...

void reflect_and_convolve (const Image &, Image &, Fftw_convolution_2d::Work_buffer) const
reentrant convolution based on reflecting the input at borders More...

void convolve (const Image &, Image &, Fftw_convolution_2d::Work_buffer) const
reentrant convolution based on reflecting the input at borders More...

## Detailed Description

this is a simple adaptation of Fftw_convolution_2d to Image input.

Formerly this was a child class of Fftw_convolution_2d but now I see that was a poor design decision. Their interfaces are very similar, but these classes do not have a sensible IS-A relationship.

The optimum use case for this class is when you must convolve (e.g., blur) a lot of images with a single large convolutional kernel (a.k.a. mask). The same mask is applied to each color channel (red, green, and blue). If the mask is a Gaussian, there is a convenience function to make it easier – just tell us the sigma size.

You can use an object of this class in a multithreaded context. The recommended way to do so is to have one thread instantiate the object and set the mask. Each worker thread needs its own work buffer, but allocation of the work buffer is NOT guaranteed reentrant, so the allocations must be serialized somehow. Once these preliminaries are handled, each worker thread can convolve images with the predefined mask at will, in parallel. Only the following functions are promised to be reentrant in this class:

To clarify, the above paradigm is for many images, and one thread per image, i.e., one thread per convolution. That is the computing paradigm we support here. This is in contrast to another popular unsupported alternative: multiple threads computing in parallel the convolution of a single image. We don't do that!

## Constructor & Destructor Documentation

 kjb::Fftw_image_convolution::Fftw_image_convolution ( int img_num_rows, int img_num_cols, int mask_max_rows, int mask_max_cols, int fft_alg_type = `FFTW_MEASURE` )
inline

please see ctor of class Fftw_convolution_2d

## Member Function Documentation

 Fftw_convolution_2d::Work_buffer kjb::Fftw_image_convolution::allocate_work_buffer ( ) const
inline
 void kjb::Fftw_image_convolution::convolve ( const Image & in, Image & out, Fftw_convolution_2d::Work_buffer buf ) const

reentrant convolution based on reflecting the input at borders

Parameters
 [in] in input image to be filtered/blurred/convolved [out] out reference to output image object to which to write results [in] buf individual working memory for (this thread's) computations

This method will emulate the behavior of kjb_c::fourier_convolve_image(), i.e., it assumes the borders of the image are surrounded by zeros. This is usually a poor assumption for images; you might prefer to use reflect_and_convolve(). See Two ways to handle boundary conditions.

Note that 'buf' must not be shared across threads. It is a smart pointer so it is lightweight and safe to copy by value. This method is one of the few reentrant methods of this class. See Convolution using multiple threads.

It is perfectly fine to make 'in' and 'out' refer to the same Image.

 const Fftw_convolution_2d::Sizes& kjb::Fftw_image_convolution::get_sizes ( ) const
inline

inline

read access of the flag indicating whether the mask has been set

 void kjb::Fftw_image_convolution::reflect_and_convolve ( const Image & in, Image & out, Fftw_convolution_2d::Work_buffer buf ) const

reentrant convolution based on reflecting the input at borders

Parameters
 [in] in input image to be filtered/blurred/convolved [out] out reference to output image object to which to write results [in] buf individual working memory for (this thread's) computations

This method will emulate the behavior of kjb_c::convolve_image(), i.e., it assumes the borders of the image are surrounded by reflection. This is a common assumption for images. See Two ways to handle boundary conditions.

Note that 'buf' must not be shared across threads. It is a smart pointer so it is lightweight and safe to copy by value. This method is one of the few reentrant methods of this class. See Convolution using multiple threads.

It is perfectly fine to make 'in' and 'out' refer to the same Image.

 void kjb::Fftw_image_convolution::set_gaussian_mask ( double sigma )
inline

set mask to a circular gaussian kernel of given sigma (pixels)

 void kjb::Fftw_image_convolution::set_mask ( const Matrix & m )
inline

set mask, which must fit with mask size maxima given to ctor

The documentation for this class was generated from the following files:
{"ft_lang_label":"__label__en","ft_lang_prob":0.82520014,"math_prob":0.80472744,"size":4767,"snap":"2022-05-2022-21","text_gpt3_token_len":1168,"char_repetition_ratio":0.13457905,"word_repetition_ratio":0.44596443,"special_character_ratio":0.22970422,"punctuation_ratio":0.14518002,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9696742,"pos_list":[0],"im_url_duplicate_count":[null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2022-05-16T12:52:32Z\",\"WARC-Record-ID\":\"<urn:uuid:685e9a62-cc25-495e-8f34-43a91c033426>\",\"Content-Length\":\"27306\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:6502d5de-68f1-498e-81b6-8650c365160a>\",\"WARC-Concurrent-To\":\"<urn:uuid:0bb04d4d-bdd1-4934-be5e-83a95e642d20>\",\"WARC-IP-Address\":\"150.135.82.165\",\"WARC-Target-URI\":\"http://kobus.ca/research/resources/doc/doxygen/classkjb_1_1Fftw__image__convolution.html\",\"WARC-Payload-Digest\":\"sha1:ZIZRNR27XCMF232P6LS7LNABSE3MYFHJ\",\"WARC-Block-Digest\":\"sha1:GMMLSJWRLZEDLNI3BKH7WKO5KALJ5MDQ\",\"WARC-Identified-Payload-Type\":\"application/xhtml+xml\",\"warc_filename\":\"/cc_download/warc_2022/CC-MAIN-2022-21/CC-MAIN-2022-21_segments_1652662510117.12_warc_CC-MAIN-20220516104933-20220516134933-00056.warc.gz\"}"}