Back to FabImage Library website

You are here: Start » Function Reference » Image » Image Local Transforms » ConvolveImage

ConvolveImage


Header: FIL.h
Namespace: fil
Module: FoundationLite

Computes a convolution of the input image with a user-specified mask.

Applications: Non-standard local transforms defined by the user.

Syntax

C++
C#
 
void fil::ConvolveImage
(
	const fil::Image& inImage,
	ftl::Optional<const fil::Region&> inRoi,
	const fil::Matrix& inMask,
	bool inNormalizeMaskValues,
	ftl::Optional<const fil::Location&> inMaskOrigin,
	fil::Image& outImage
)

Parameters

Name Type Default Description
Input value inImage const Image& Input image
Input value inRoi Optional<const Region&> NIL Range of outImage pixels to be computed
Input value inMask const Matrix& Image convolution kernel
Input value inNormalizeMaskValues bool False Normalize sum of weights in mask to one
Input value inMaskOrigin Optional<const Location&> NIL Relative location of point to its mask
Output value outImage Image& Output image

Description

The operation computes new value of pixel as a convolution of inImage pixels and the inMask values. Pixels which mask exceeds inRoi region are set to black. Input and output pixel have the same type. If result value does not fit into pixel type you should use ConvertPixelType.

Examples

ConvolveImage performed on the sample image with inMask \( \begin{pmatrix} -1 & -2 & -1 \\ 0 & 0 & 0 \\ 1 & 2 & 1 \\ \end{pmatrix} \).

Hardware Acceleration

This operation supports automatic parallelization for multicore and multiprocessor systems.

This operation supports processing on OpenCL compatible device (when inRoi=NIL).

Errors

List of possible exceptions:

Error type Description
DomainError Empty convolution mask on input in ConvolveImage.
DomainError Mask origin is outside the dimensions of the mask in ConvolveImage.
DomainError Region exceeds an input image in ConvolveImage.
DomainError Sum of weights in Mask is equal zero. Cannot normalize values in ConvolveImage.