Convolvers

enum profit::ConvolverType

The types of convolvers supported by libprofit

Values:

enumerator BRUTE_OLD

A brute-force convolver. It optionally uses OpenMP to accelerate the convolution.

enumerator 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.

enumerator 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.

enumerator 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.

enumerator NO_OP

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::NullConvolver, 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 kernel krn. 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 the crop 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.

Parameters:

• src – The source image

• krn – The convolution kernel

• mask – An mask indicating which pixels of the resulting image should be convolved

• crop – If true return an image with the same dimensions of src. If false the image returned might be potentially bigger, depending on the internal workings of the convolver.

• offset_out – If crop is false and offset is different from NO_OFFSET, stores the potential offset of the original image with respect to the uncropped image returned by this method.

Returns:

The convolved image, optionally without the cropping caused due to internal implementation details of the convolver. The potential offset is written into offset_out.

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.

effort_t effort

The amount of effort to put into the plan creation. Used by the FFT convolver.

bool reuse_krn_fft

Whether to reuse or not the FFT’d kernel or not. Used by the FFT convolver.

simd_instruction_set instruction_set

The extended instruction set to use. Used by the BRUTE convolver.

ConvolverPtr profit::create_convolver(const ConvolverType type, const ConvolverCreationPreferences &prefs)

Creates a new convolver of type type with preferences prefs

Parameters:

• type – The type of convolver to create

• prefs – The creation preferences used to create the new convolver

Returns:

A shared pointer to a new convolver

ConvolverPtr profit::create_convolver(const std::string &type, const ConvolverCreationPreferences &prefs)

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.