opencv/doc/gpu_image_processing.tex

\section{Image Processing}


\cvCppFunc{gpu::meanShiftFiltering}
Performs mean-shift filtering for each point of the source image. It maps each point of the source image into another point, and as the result we have new color and new position of each point.

\cvdefCpp{void meanShiftFiltering(const GpuMat\& src, GpuMat\& dst,\par
  int sp, int sr,\par
  TermCriteria criteria = TermCriteria(TermCriteria::MAX\_ITER\par
  + TermCriteria::EPS, 5, 1));}

\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC4} images are supported for now.}
\cvarg{dst}{Destination image, containing color of mapped points. Will have the same size and type as \texttt{src}.}
\cvarg{sp}{Spatial window radius.}
\cvarg{sr}{Color window radius.}
\cvarg{criteria}{Termination criteria. See \hyperref[TermCriteria]{cv::TermCriteria}.}
\end{description}


\cvCppFunc{gpu::meanShiftProc}
Performs mean-shift procedure and stores information about processed points (i.e. their colors and positions) into two images. 

\cvdefCpp{void meanShiftProc(const GpuMat\& src, GpuMat\& dstr, GpuMat\& dstsp,\par
  int sp, int sr,\par
  TermCriteria criteria = TermCriteria(TermCriteria::MAX\_ITER\par
  + TermCriteria::EPS, 5, 1));}

\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC4} images are supported for now.}
\cvarg{dstr}{Destination image, containing color of mapped points. Will have the same size and type as \texttt{src}.}
\cvarg{dstsp}{Destination image, containing position of mapped points. Will have the same size as \texttt{src} and \texttt{CV\_16SC2} type.}
\cvarg{sp}{Spatial window radius.}
\cvarg{sr}{Color window radius.}
\cvarg{criteria}{Termination criteria. See \hyperref[TermCriteria]{cv::TermCriteria}.}
\end{description}

See also: \cvCppCross{gpu::meanShiftFiltering}.


\cvCppFunc{gpu::meanShiftSegmentation}
Performs mean-shift segmentation of the source image and eleminates small segments.

\cvdefCpp{void meanShiftSegmentation(const GpuMat\& src, Mat\& dst,\par
  int sp, int sr, int minsize,\par
  TermCriteria criteria = TermCriteria(TermCriteria::MAX\_ITER\par
  + TermCriteria::EPS, 5, 1));}

\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC4} images are supported for now.}
\cvarg{dst}{Segmented image. Will have the same size and type as \texttt{src}.}
\cvarg{sp}{Spatial window radius.}
\cvarg{sr}{Color window radius.}
\cvarg{minsize}{Minimum segment size. Smaller segements will be merged.}
\cvarg{criteria}{Termination criteria. See \hyperref[TermCriteria]{cv::TermCriteria}.}
\end{description}


\cvCppFunc{gpu::integral}
Computes integral image and squared integral image.

\cvdefCpp{void integral(const GpuMat\& src, GpuMat\& sum);\newline
void integral(const GpuMat\& src, GpuMat\& sum, GpuMat\& sqsum);}

\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC1} images are supported for now.}
\cvarg{sum}{Integral image. Will contain 32-bit unsigned integer values packed into \texttt{CV\_32SC1}.}
\cvarg{sqsum}{Squared integral image. Will have \texttt{CV\_32FC1} type.}
\end{description}

See also: \cvCppCross{integral}.


\cvCppFunc{gpu::sqrIntegral}
Computes squared integral image.

\cvdefCpp{void sqrIntegral(const GpuMat\& src, GpuMat\& sqsum);}
\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC1} images are supported for now.}
\cvarg{sqsum}{Squared integral image. Will contain 64-bit unsigned integer values packed into \texttt{CV\_64FC1}.}
\end{description}


\cvCppFunc{gpu::columnSum}
Computes vertical (column) sum.

\cvdefCpp{void columnSum(const GpuMat\& src, GpuMat\& sum);}
\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_32FC1} images are supported for now.}
\cvarg{sum}{Destination image. Will have \texttt{CV\_32FC1} type.}
\end{description}


\cvCppFunc{gpu::cornerHarris}
Computes Harris cornerness criteria at each image pixel.

\cvdefCpp{void cornerHarris(const GpuMat\& src, GpuMat\& dst,\par
  int blockSize, int ksize, double k,\par
  int borderType=BORDER\_REFLECT101);}

\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC1} and \texttt{CV\_32FC1} images are supported for now.}
\cvarg{dst}{Destination image. Will have the same size and \texttt{CV\_32FC1} type and contain cornerness values.}
\cvarg{blockSize}{Neighborhood size.}
\cvarg{ksize}{Aperture parameter for the Sobel operator.}
\cvarg{k}{Harris detector free parameter.}
\cvarg{borderType}{Pixel extrapolation method. Only \texttt{BORDER\_REFLECT101} and \texttt{BORDER\_REPLICATE} are supported for now.}
\end{description}

See also: \cvCppCross{cornerHarris}.


\cvCppFunc{gpu::cornerMinEigenVal}
Computes minimum eigen value of 2x2 derivative covariation matrix at each pixel - the cornerness criteria.

\cvdefCpp{void cornerMinEigenVal(const GpuMat\& src, GpuMat\& dst,\par
  int blockSize, int ksize,\par
  int borderType=BORDER\_REFLECT101);}

\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC1} and \texttt{CV\_32FC1} images are supported for now.}
\cvarg{dst}{Destination image. Will have the same size and \texttt{CV\_32FC1} type and contain cornerness values.}
\cvarg{blockSize}{Neighborhood size.}
\cvarg{ksize}{Aperture parameter for the Sobel operator.}
\cvarg{k}{Harris detector free parameter.}
\cvarg{borderType}{Pixel extrapolation method. Only \texttt{BORDER\_REFLECT101} and \texttt{BORDER\_REPLICATE} are supported for now.}
\end{description}

See also: \cvCppCross{cornerMinEigenValue}.


\cvCppFunc{gpu::mulSpectrums}
Performs per-element multiplication of two Fourier spectrums.

\cvdefCpp{void mulSpectrums(const GpuMat\& a, const GpuMat\& b,\par
  GpuMat\& c, int flags, bool conjB=false);}

\begin{description}
\cvarg{a}{First spectrum.}
\cvarg{b}{Second spectrum. Must have the same size and type as \texttt{a}.}
\cvarg{c}{Destination spectrum.}
\cvarg{flags}{Mock paramter is kept for CPU/GPU interfaces similarity.}
\cvarg{conjB}{Optional flag which indicates the second spectrum must be conjugated before the multiplication.}
\end{description}

Only full (i.e. not packed) \texttt{CV\_32FC2} complex spectrums in the interleaved format are supported for now.

See also: \cvCppCross{mulSpectrums}.


\cvCppFunc{gpu::mulAndScaleSpectrums}
Performs per-element multiplication of two Fourier spectrums and scales the result.

\cvdefCpp{void mulAndScaleSpectrums(const GpuMat\& a, const GpuMat\& b,\par
  GpuMat\& c, int flags, float scale, bool conjB=false);}

\begin{description}
\cvarg{a}{First spectrum.}
\cvarg{b}{Second spectrum. Must have the same size and type as \texttt{a}.}
\cvarg{c}{Destination spectrum.}
\cvarg{flags}{Mock paramter is kept for CPU/GPU interfaces similarity.}
\cvarg{scale}{Scale constant.}
\cvarg{conjB}{Optional flag which indicates the second spectrum must be conjugated before the multiplication.}
\end{description}

Only full (i.e. not packed) \texttt{CV\_32FC2} complex spectrums in the interleaved format are supported for now.

See also: \cvCppCross{mulSpectrums}.


\cvCppFunc{gpu::dft}
Performs a forward or inverse discrete Fourier transform (1D or 2D) of floating point matrix. Can handle real matrices (\texttt{CV\_32FC1}) and complex matrices in the interleaved format (\texttt{CV\_32FC2}).

\cvdefCpp{void dft(const GpuMat\& src, GpuMat\& dst, Size dft\_size, int flags=0);}

\begin{description}
\cvarg{src}{Source matrix (real or complex).}
\cvarg{dst}{Destination matrix (real or complex).}
\cvarg{dft\_size}{Size of discrete Fourier transform.}
\cvarg{flags}{Optional flags:
\begin{description}
  \cvarg{DFT\_ROWS}{Transform each individual row of the source matrix.}
  \cvarg{DFT\_SCALE}{Scale the result: divide it by the number of elements in the transform (it's obtained from \texttt{dft\_size}).
  \cvarg{DFT\_INVERSE}{Inverse DFT must be perfromed for complex-complex case (real-complex and complex-real cases are respectively forward and inverse always).}}
  \cvarg{DFT\_REAL\_OUTPUT}{The source matrix is the result of real-complex transform, so the destination matrix must be real.}
\end{description}}
\end{description}

The source matrix should be continuous, otherwise reallocation and data copying will be performed. Function chooses the operation mode depending on the flags, size and channel count of the source matrix:
\begin{itemize}
  \item If the source matrix is complex and the output isn't specified as real then the destination matrix will be complex, will have \texttt{dft\_size} size and \texttt{CV\_32FC2} type. It will contain full result of the DFT (forward or inverse).
  \item If the source matrix is complex and the output is specified as real then function assumes that its input is the result of the forward transform (see next item). The destionation matrix will have \texttt{dft\_size} size and \texttt{CV\_32FC1} type. It will contain result of the inverse DFT.
  \item If the source matrix is real (i.e. its type is \texttt{CV\_32FC1}) then forward DFT will be performed. The result of the DFT will be packed into complex (\texttt{CV\_32FC2}) matrix so its width will be \texttt{dft\_size.width / 2 + 1}, but if the source is a single column then height will be reduced instead of width.
\end{itemize}

See also: \cvCppCross{dft}.


\cvCppFunc{gpu::convolve}
Computes convolution (or cross-correlation) of two images.

\cvdefCpp{void convolve(const GpuMat\& image, const GpuMat\& templ, GpuMat\& result,\par
  bool ccorr=false);\newline
void convolve(const GpuMat\& image, const GpuMat\& templ, GpuMat\& result,\par
  bool ccorr, ConvolveBuf\& buf);}

\begin{description}
\cvarg{image}{Source image. Only \texttt{CV\_32FC1} images are supported for now.}
\cvarg{templ}{Template image. Must have size not greater then \texttt{image} size and be the same type as \texttt{image}.}
\cvarg{result}{Result image. Will have the same size and type as \texttt{image}.}
\cvarg{ccorr}{Flags which indicates cross-correlation must be evaluated instead of convolution.}
\cvarg{buf}{Optional buffer to avoid extra memory allocations (for many calls with the same sizes).}
\end{description}


\cvclass{gpu::ConvolveBuf}
Memory buffer for the \cvCppCross{gpu::convolve} function.

\begin{lstlisting}
struct CV_EXPORTS ConvolveBuf
{
    ConvolveBuf() {}
    ConvolveBuf(Size image_size, Size templ_size) 
        { create(image_size, templ_size); }
    void create(Size image_size, Size templ_size);

private:
    // Hidden
};
\end{lstlisting}


\cvCppFunc{gpu::ConvolveBuf::ConvolveBuf}

\cvdefCpp{ConvolveBuf::ConvolveBuf();}
Constructs an empty buffer which will be properly resized after first call of the convolve function.

\cvdefCpp{ConvolveBuf::ConvolveBuf(Size image\_size, Size templ\_size);}
Constructs a buffer for the convolve function with respectively arguments.


\cvCppFunc{gpu::matchTemplate}
Computes a proximity map for a raster template and an image where the template is searched for.

\cvdefCpp{void matchTemplate(const GpuMat\& image, const GpuMat\& templ,\par
  GpuMat\& result, int method);}

\begin{description}
\cvarg{image}{Source image. \texttt{CV\_32F} and \texttt{CV\_8U} depth images (1..4 channels) are supported for now.}
\cvarg{templ}{Template image. Must have the same size and type as \texttt{image}.}
\cvarg{result}{Map containing comparison results (\texttt{CV\_32FC1}). If \texttt{image} is $W \times H$ and
\texttt{templ} is $w \times h$ then \texttt{result} must be $(W-w+1) \times (H-h+1)$.}
\cvarg{method}{Specifies the way which the template must be compared with the image.}
\end{description}

Following methods are supported for the \texttt{CV\_8U} depth images for now:
\begin{itemize}
\item CV\_TM\_SQDIFF \item CV\_TM\_SQDIFF\_NORMED \item CV\_TM\_CCORR \item CV\_TM\_CCORR\_NORMED \item CV\_TM\_CCOEFF \item CV\_TM\_CCOEFF\_NORMED 
\end{itemize}
Following methods are supported for the \texttt{CV\_32F} images for now:
\begin{itemize}
\item CV\_TM\_SQDIFF \item CV\_TM\_CCORR
\end{itemize}

See also: \cvCppCross{matchTemplate}. 


\cvCppFunc{gpu::remap}
Applies a generic geometrical transformation to an image.

\cvdefCpp{
void remap(const GpuMat\& src, GpuMat\& dst, \par const GpuMat\& xmap, const GpuMat\& ymap);
}

\begin{description}
\cvarg{src}{Source image. Only \texttt{CV\_8UC1} and \texttt{CV\_8UC3} source types are supported.}
\cvarg{dst}{Destination image. It will have the same size as \texttt{xmap} and the same type as \texttt{src}.}
\cvarg{xmap}{X values. Only \texttt{CV\_32FC1} type is supported.}
\cvarg{ymap}{Y values. Only \texttt{CV\_32FC1} type is supported.}
\end{description}

The function transforms the source image using the specified map:
\[
\texttt{dst}(x,y) = \texttt{src}(xmap(x,y), ymap(x,y))
\]

Values of pixels with non-integer coordinates are computed using bilinear interpolation.

See also: \cvCppCross{remap}.


\cvCppFunc{gpu::cvtColor}
Converts image from one color space to another.

\cvdefCpp{
void cvtColor(const GpuMat\& src, GpuMat\& dst, int code, int dcn = 0);\newline
void cvtColor(const GpuMat\& src, GpuMat\& dst, int code, int dcn, \par const Stream\& stream);
}

\begin{description}
\cvarg{src}{Source image with \texttt{CV\_8U}, \texttt{CV\_16U} or \texttt{CV\_32F} depth and 1, 3 or 4 channels.}
\cvarg{dst}{Destination image; will have the same size and the same depth as \texttt{src}.}
\cvarg{code}{Color space conversion code. For details see \cvCppCross{cvtColor}. Conversion to/from Luv and Bayer color spaces doesn't supported.}
\cvarg{dcn}{Number of channels in the destination image; if the parameter is 0, the number of the channels will be derived automatically from \texttt{src} and the \texttt{code}.}
\cvarg{stream}{Stream for the asynchronous version.}
\end{description}

3-channel color spaces (like \texttt{HSV}, \texttt{XYZ}, etc) can be stored to 4-channel image for better perfomance.

See also: \cvCppCross{cvtColor}.


\cvCppFunc{gpu::threshold}
Applies a fixed-level threshold to each array element.

\cvdefCpp{
double threshold(const GpuMat\& src, GpuMat\& dst, double thresh);
}

\begin{description}
\cvarg{src}{Source array. Supports only \texttt{CV\_32FC1} type.}
\cvarg{dst}{Destination array; will have the same size and the same type as \texttt{src}.}
\cvarg{thresh}{Threshold value.}
\end{description}

See also: \cvCppCross{threshold}.


\cvCppFunc{gpu::resize}
Resizes an image.

\cvdefCpp{
void resize(const GpuMat\& src, GpuMat\& dst, Size dsize, \par double fx=0, double fy=0, \par int interpolation = INTER\_LINEAR);
}

\begin{description}
\cvarg{src}{Source image. Supports \texttt{CV\_8UC1} and \texttt{CV\_8UC4} types.}
\cvarg{dst}{Destination image. It will have size \texttt{dsize} (when it is non-zero) or the size computed from \texttt{src.size()} and \texttt{fx} and \texttt{fy}. The type of \texttt{dst} will be the same as of \texttt{src}.}
\cvarg{dsize}{Destination image size. If it is zero, then it is computed as: 
\[
\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}
\]
Either \texttt{dsize} or both \texttt{fx} or \texttt{fy} must be non-zero.}
\cvarg{fx}{Scale factor along the horizontal axis. When 0, it is computed as 
\[
\texttt{(double)dsize.width/src.cols}
\]} 
\cvarg{fy}{Scale factor along the vertical axis. When 0, it is computed as 
\[
\texttt{(double)dsize.height/src.rows}
\]}
\cvarg{interpolation}{Interpolation method. Supports only \texttt{INTER\_NEAREST} and \texttt{INTER\_LINEAR}.}
\end{description}

See also: \cvCppCross{resize}.


\cvCppFunc{gpu::warpAffine}
Applies an affine transformation to an image.

\cvdefCpp{
void warpAffine(const GpuMat\& src, GpuMat\& dst, const Mat\& M, \par Size dsize, int flags = INTER\_LINEAR);
}

\begin{description}
\cvarg{src}{Source image. Supports \texttt{CV\_8U}, \texttt{CV\_16U}, \texttt{CV\_32S} or \texttt{CV\_32F} depth and 1, 3 or 4 channels.}
\cvarg{dst}{Destination image; will have size \texttt{dsize} and the same type as \texttt{src}.}
\cvarg{M}{$2\times 3$ transformation matrix.}
\cvarg{dsize}{Size of the destination image.}
\cvarg{flags}{Combination of interpolation methods, see \cvCppCross{resize}, and the optional flag \texttt{WARP\_INVERSE\_MAP} that means that \texttt{M} is the inverse transformation ($\texttt{dst}\rightarrow\texttt{src}$). Supports only \texttt{INTER\_NEAREST}, \texttt{INTER\_LINEAR} and \texttt{INTER\_CUBIC} interpolation methods.}
\end{description}

See also: \cvCppCross{warpAffine}.


\cvCppFunc{gpu::warpPerspective}
Applies a perspective transformation to an image.

\cvdefCpp{
void warpPerspective(const GpuMat\& src, GpuMat\& dst, const Mat\& M, \par Size dsize, int flags = INTER\_LINEAR);
}

\begin{description}
\cvarg{src}{Source image. Supports \texttt{CV\_8U}, \texttt{CV\_16U}, \texttt{CV\_32S} or \texttt{CV\_32F} depth and 1, 3 or 4 channels.}
\cvarg{dst}{Destination image; will have size \texttt{dsize} and the same type as \texttt{src}.}
\cvarg{M}{$2
 3$ transformation matrix.}
\cvarg{dsize}{Size of the destination image.}
\cvarg{flags}{Combination of interpolation methods, see \cvCppCross{resize}, and the optional flag \texttt{WARP\_INVERSE\_MAP} that means that \texttt{M} is the inverse transformation ($\texttt{dst}\rightarrow\texttt{src}$). Supports only \texttt{INTER\_NEAREST}, \texttt{INTER\_LINEAR} and \texttt{INTER\_CUBIC} interpolation methods.}
\end{description}

See also: \cvCppCross{warpPerspective}.


\cvCppFunc{gpu::rotate}
Rotates an image around the origin (0,0) and then shifts it.

\cvdefCpp{
void rotate(const GpuMat\& src, GpuMat\& dst, Size dsize, \par double angle, double xShift = 0, double yShift = 0, \par int interpolation = INTER\_LINEAR);
}

\begin{description}
\cvarg{src}{Source image. Supports \texttt{CV\_8UC1} and \texttt{CV\_8UC4} types.}
\cvarg{dst}{Destination image; will have size \texttt{dsize} and the same type as \texttt{src}.}
\cvarg{dsize}{Size of the destination image.}
\cvarg{angle}{Angle of rotation in degrees.}
\cvarg{xShift}{Shift along horizontal axis.}
\cvarg{yShift}{Shift along vertical axis.}
\cvarg{interpolation}{Interpolation method. Supports only \texttt{INTER\_NEAREST}, \texttt{INTER\_LINEAR} and \texttt{INTER\_CUBIC}.}
\end{description}

See also: \cvCppCross{gpu::warpAffine}.


\cvCppFunc{gpu::copyMakeBorder}
Copies 2D array to a larger destination array and pads borders with the given constant.

\cvdefCpp{
void copyMakeBorder(const GpuMat\& src, GpuMat\& dst, \par int top, int bottom, int left, int right, \par const Scalar\& value = Scalar());
}

\begin{description}
\cvarg{src}{Source image. Supports \texttt{CV\_8UC1}, \texttt{CV\_8UC4}, \texttt{CV\_32SC1} and \texttt{CV\_32FC1} types.}
\cvarg{dst}{The destination image; will have the same type as \texttt{src} and the size \texttt{Size(src.cols+left+right, src.rows+top+bottom)}.}
\cvarg{top, bottom, left, right}{Specify how much pixels in each direction from the source image rectangle one needs to extrapolate, e.g. \texttt{top=1, bottom=1, left=1, right=1} mean that 1 pixel-wide border needs to be built.}
\cvarg{value}{Border value.}
\end{description}

See also: \cvCppCross{copyMakeBorder}


\cvCppFunc{gpu::rectStdDev}
Computes standard deviation of integral images. 

\cvdefCpp{
void rectStdDev(const GpuMat\& src, const GpuMat\& sqr, GpuMat\& dst, \par const Rect\& rect);
}

\begin{description}
\cvarg{src}{Source image. Supports only \texttt{CV\_32SC1} type.}
\cvarg{sqr}{Squared source image. Supports only \texttt{CV\_32FC1} type.}
\cvarg{dst}{Destination image; will have the same type and the same size as \texttt{src}.}
\cvarg{rect}{Rectangular window.}
\end{description}


\cvCppFunc{gpu::evenLevels}
Computes levels with even distribution.

\cvdefCpp{
void evenLevels(GpuMat\& levels, int nLevels, \par int lowerLevel, int upperLevel);
}

\begin{description}
\cvarg{levels}{Destination array. \texttt{levels} will have 1 row and \texttt{nLevels} cols and \texttt{CV\_32SC1} type.}
\cvarg{nLevels}{Number of levels being computed. \texttt{nLevels} must be at least 2.}
\cvarg{lowerLevel}{Lower boundary value of the lowest level.}
\cvarg{upperLevel}{Upper boundary value of the greatest level.}
\end{description}

\cvCppFunc{gpu::histEven}
Calculates histogram with evenly distributed bins.

\cvdefCpp{
void histEven(const GpuMat\& src, GpuMat\& hist, \par int histSize, int lowerLevel, int upperLevel);\newline
void histEven(const GpuMat\& src, GpuMat hist[4], \par int histSize[4], int lowerLevel[4], int upperLevel[4]);
}

\begin{description}
\cvarg{src}{Source image. Supports \texttt{CV\_8U}, \texttt{CV\_16U} or \texttt{CV\_16S} depth and 1 or 4 channels. For four-channel image all channels are processed separately.}
\cvarg{hist}{Destination histogram. Will have one row, \texttt{histSize} cols and \texttt{CV\_32S} type.}
\cvarg{histSize}{Size of histogram.}
\cvarg{lowerLevel}{Lower boundary of lowest level bin.}
\cvarg{upperLevel}{Upper boundary of highest level bin.}
\end{description}

\cvCppFunc{gpu::histRange}
Calculates histogram with bins determined by levels array.

\cvdefCpp{
void histRange(const GpuMat\& src, GpuMat\& hist, const GpuMat\& levels);\newline
void histRange(const GpuMat\& src, GpuMat hist[4], \par const GpuMat levels[4]);
}

\begin{description}
\cvarg{src}{Source image. Supports \texttt{CV\_8U}, \texttt{CV\_16U} or \texttt{CV\_16S} depth and 1 or 4 channels. For four-channel image all channels are processed separately.}
\cvarg{hist}{Destination histogram. Will have one row, \texttt{(levels.cols-1)} cols and \texttt{CV\_32SC1} type.}
\cvarg{levels}{Number of levels in histogram.}
\end{description}