Image convolution in libprofit happens optionally
as part of a
Model uses a
to perform convolution.
Supported convolution methods¶
Convolvers are objects that carry out convolution
Depending on the size of the problem,
and on the libraries available on the system,
different convolver types will be available to be used:
BRUTE_OLDis the simplest convolver. It implements a simple, brute-force 2D convolution algorithm.
BRUTEis a brute-force convolver that performs better that
BRUTE_OLD, but still implements simple, brute-force 2D convolution. It is the default convolver used by a
Modelthat hasn’t been assigned one, but requires one.
FFTis a convolver that uses Fast Fourier transformations to perform convolution. Its complexity is lower than the
BRUTE, but its creation can be more expensive.
OPENCLis a brute-force convolver implemented in OpenCL. It offers both single and double floating-point precision and its performance is usually better that that of the
Creating a Convolver¶
Instead of manually selecting the class that should be used,
create_convolver() lets the user specify
which type of convolver should be created
(either using an enumeration, or a standard string value),
and a set of creation preferences
that apply differently to different types of Convolvers.
Model needs to perform convolution
Convolver has been set
then that convolver is used.
If no convolver has been set,
it creates a new
and uses that to perform the convolution.
Using a convolver¶
users can call the
directly on the resulting convolver,
(or assign it to a
Model instance for it to use it).
Convolver::convolve() methods needs at least three parameters:
an image, a kernel and a mask.
Convolvers will convolve the image with the kernel
only for the pixels in which the mask is set,
or for all pixels if an empty mask is passed.
This implies that the mask, if not empty,
must have the same dimensions that the image.
Some convolvers internally work with images that are larger than the original source image (mostly due to efficiency reasons). After this internal image expansion occurs, and the convolution takes place, the resulting image is usually cropped at the corresponding point to match original source image size and positioning before being returned to the user.
However, users might want to pick
into this internal, non-cropped result
of the convolution process.
To do this,
determines whether the convolver should return
the original, and potentially bigger, image.
When a non-cropped image is returned,
can be given to find out the offset
at which cropping would have started.
The cropping dimensions do not need to be queried,
as they always are the same
of the original source image given to the convolver.
During model evaluation (i.e., a call to
users might want to be able to retrieve the non-cropped result
of the internal convolution that takes place
during model evaluation
(as explained in Image cropping).
To do this, users must first
Model::set_crop() with a
users must then also give a
to retrieve the offset at which
cropping should be done
to remove the image padding
added by the convolution process.