Convolvers¶
-
enum
profit
::
ConvolverType
¶ The types of convolvers supported by libprofit
Values:
-
BRUTE_OLD
= 0¶ A brute-force convolver. It optionally uses OpenMP to accelerate the convolution.
-
BRUTE
¶ A faster brute-force convolver. It optionally uses OpenMP to accelerate the convolution.
The difference between this and the BruteForceConvolver is that this convolver explicitly states that the sums of the dot products that make up the result of a single pixel are associative, and can be computed separately, which enables better pipelining in most CPUs and thus faster compute times (we have seen up to ~3x speedups). The result is not guaranteed to be the exact same as the one coming from BruteForceConvolver. This is not because one of them is mathematically incorrect (neither is actually), but because IEEE floating-point math is not associative, and therefore different operation sequences might yield different results.
The internal loop structure of this class is also slightly different from BruteForceConvolver, but is still pure CPU-based code.
Additionally, and depending on the underlying CPU support, this convolver can use dot product implementations based on SIMD operations available in different CPU extended instruction sets. The default is to use the fastest one available, although users might want to use a different one.
-
OPENCL
¶ A brute-force convolver that is implemented using OpenCL
Depending on the floating-point support found at runtime in the given OpenCL environment this convolver will use a float-based or a double-based kernel.
-
FFT
¶ A convolver that uses an FFTPlan to carry out FFT-based convolution.
The result of the convolution of images im1 and im2 is::
res = iFFT(FFT(im1) * FFT(im2))
To do this, this convolver creates extended versions of the input images. The size of the new images is 4 times that of the source image, which is assumed to be larger than the kernel. The extended version of the source image contains the original image at (0,0), while the extended version of the kernel image contains the original kernel centered at the original image’s new mapping (i.e.,
((src_width-krn_width)/2, (src_height-krn_height)/2)
). After convolution the result is cropped back (if required) to the original image’s dimensions starting at the center of the original image’s mapping on the extended image (i.e.,(src_width/2, src_height/2)
minus one if the original dimensions are odd).This convolver has been implemented in such a way that no memory allocation happens during convolution (other than the final Image’s allocation) to improve performance.
-
-
class
Convolver
¶ A convolver object convolves two images.
This is the base class for all Convolvers. Deriving classes must implement the convolve method, which performs the actual operation.
Subclassed by profit::AssociativeBruteForceConvolver< SIMD >, profit::BruteForceConvolver, profit::FFTConvolver, profit::OpenCLConvolver, profit::OpenCLLocalConvolver
Public Functions
-
Image
convolve
(const Image &src, const Image &krn, const Mask &mask, bool crop = true, Point &offset_out = NO_OFFSET)¶ Convolves image
src
with the kernelkrn
. A mask parameter also controls which pixels from the original image should be convolved. If empty, all pixels are convolved.If the convolver extends the original image to perform the convolution, users might want to have the extended image returned, instead of getting a cropped image (that will be the same size as
src
). This behaviour is controlled with thecrop
parameter. If the image is not cropped, the offset of the otherwise cropped result with respect to the uncropped one is optionally stored in offset_out.- Return
- The convolved image, optionally without the cropping caused due to internal implementation details of the convolver. The potential offset is written into offset_out.
- Parameters
src
: The source imagekrn
: The convolution kernelmask
: An mask indicating which pixels of the resulting image should be convolvedcrop
: Iftrue
return an image with the same dimensions ofsrc
. Iffalse
the image returned might be potentially bigger, depending on the internal workings of the convolver.offset_out
: Ifcrop
isfalse
andoffset
is different from NO_OFFSET, stores the potential offset of the original image with respect to the uncropped image returned by this method.
-
Image
-
class
ConvolverCreationPreferences
¶ A set of preferences used to create convolvers.
Public Members
-
Dimensions
src_dims
¶ The dimensions of the image being convolved.
-
Dimensions
krn_dims
¶ The dimensions of the convolution kernel.
-
unsigned int
omp_threads
¶ The amount of OpenMP threads (if OpenMP is available) to use by the convolver. Used by the FFT convolver (to create and execute the plan using OpenMP, when available) and the brute-force convolvers.
-
OpenCLEnvPtr
opencl_env
¶ A pointer to an OpenCL environment. Used by the OPENCL convolvers.
-
simd_instruction_set
instruction_set
¶ The extended instruction set to use. Used by the BRUTE convolver.
-
Dimensions
-
ConvolverPtr
profit
::
create_convolver
(const ConvolverType type, const ConvolverCreationPreferences &prefs = ConvolverCreationPreferences()) Creates a new convolver of type
type
with preferencesprefs
- Return
- A shared pointer to a new convolver
- Parameters
type
: The type of convolver to createprefs
: The creation preferences used to create the new convolver
-
ConvolverPtr
profit
::
create_convolver
(const std::string &type, const ConvolverCreationPreferences &prefs = ConvolverCreationPreferences()) Like create_convolver(ConvolverType, const ConvolverCreationPreferences &), but indicating the convolver type as a string.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.