Intel® Integrated Performance Primitives Developer Guide and Reference

ID 790148
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

GradientVectorScharr

Computes gradient vectors of an image using the Scharr operator.

Syntax

IppStatus ippiGradientVectorScharr_<mod> (const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pGx, int gxStep, Ipp<dstDatatype>* pGy, int gyStep, Ipp<dstDatatype>* pMag, int magStep, Ipp32f* pAngle, int angleStep, IppiSize dstRoiSize, IppiMaskSize maskSize, IppNormType normType, IppiBorderType borderType, Ipp<srcDatatype> borderValue, Ipp8u* pBuffer);

Supported values for mod:

8u16s_C1R 16s32f_C1R 16u32f_C1R 32f_C1R

IppStatus ippiGradientVectorScharr_<mod> (const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pGx, int gxStep, Ipp<dstDatatype>* pGy, int gyStep, Ipp<dstDatatype>* pMag, int magStep, Ipp32f* pAngle, int angleStep, IppiSize dstRoiSize, IppiMaskSize maskSize, IppNormType normType, IppiBorderType borderType, const Ipp<srcDatatype> borderValue[3], Ipp8u* pBuffer);

Supported values for mod:

8u16s_C3C1R 16s32f_C3C1R 16u32f_C3C1R 32f_C3C1R

Include Files

ippi.h

Domain Dependencies

Headers: ippcore.h, ippvm.h, ipps.h

Libraries: ippcore.lib, ippvm.lib, ipps.lib

Parameters

pSrc

Pointer to the source image ROI.

srcStep

Distance, in bytes, between the starting points of consecutive lines in the source image.

pGx

Pointer to the destination image ROI for the X component of the gradient vector (in Cartesian form).

gxStep

Distance, in bytes, between the starting points of consecutive lines in the X-component destination image.

pGy

Pointer to the destination image ROI for the Y component of the gradient vector (in Cartesian form).

gyStep

Distance, in bytes, between the starting points of consecutive lines in the Y-component destination image.

pMag

Pointer to the magnitude of the gradient destination image ROI (in polar gradient form).

magStep

Distance, in bytes, between the starting points of consecutive lines in the magnitude of the gradient destination image.

pAngle

Pointer to the destination image ROI for the angle (in polar gradient form).

angleStep

Distance, in bytes, between the starting points of consecutive lines in the angle destination image.

dstRoiSize

Size of the source and destination image ROI in pixels.

maskSize

Predefined mask of IppiMaskSize type.

normType

Normalization mode of IppNormType type.

borderType

Type of border. Possible values are:

ippBorderConst

Values of all border pixels are set to constant.

ippBorderRepl

Border is replicated from the edge pixels.

ippBorderInMem

Border is obtained from the source image pixels in memory.

ippBorderMirror

Border pixels are mirrored from the source image boundary pixels.

borderValue

Constant value to assign to pixels in the constant border (not applicable for other border types).

pBuffer

Pointer to the work buffer.

Description

This function operates with ROI (see Regions of Interest in Intel IPP).

Before using this function, compute the size of the work buffer using the ippiGradientVectorGetBufferSize function.

NOTE:

Any of the pGx, pGy, pMag, and pAngle output parameters can be NULL. This means that the parameter(s) is not requested.

This function operates on "gray" single-channel (C1 flavors) and color (C3 flavors) images.

Single-channel image (C1) input :

If input is a single-channel image, the ippiGradientVectorScharr function computes the gradient vector at each pixel of the source image ROI and stores the result either in Cartesian (pGx and pGy) and/or polar (pMag and pAngle) form, or any combination of these possible outputs.

Cartesian projections Gx and Gy are stored in the pGx and pGy buffers, respectively. The formulas below describe the algorithm for the 3x3 Scharr operator:

where

  • A is the source image

  • * means two-dimensional convolution

  • Gx and Gy are X and Y components of the gradient

The magnitude of the gradient is computed according to the normType value by the following formulas:

L1 normalization:

L2 normalization:

The value of angle between Gx and Gy is computed by the formula:

Color image (C3) input :

If input is a color image, the ippiGradientVectorScharr function computes the spatial image derivatives Gx and Gy for each channel of the image using the specified differential operator. For each pixel (x, y) this function chooses the derivatives for which L2(Gx, Gy) is the maximal value and stores them in the pGx and pGy output arrays. In other words, for each pixel of a color image the function returns the derivatives composing the largest gradient across all channels.

The examples of using this function are similar to the examples provided with the GradientVectorSobel function description.

Return Values

ippStsNoErr

Indicates no error.

ippStsNullPtrErr

Indicates an error when pSrc or pBuffer is NULL.

ippStsSizeErr

Indicates an error when one of the fields of dstRoiSize has a zero or negative value.

ippStsMaskSizeErr

Indicates an error when maskSize has an illegal value.

ippStsStepErr

Indicates an error when:

  • srcStep, gxStep, gyStep, magStep, or angleStep has a zero or negative value

  • srcStep, gxStep, gyStep, magStep, or angleStep is not a multiple of the image data size (4 for floating-point images or 2 for short integer images)

ippStsBadArgErr

Indicates an error when normType has an illegal value.

ippStsBorderErr

Indicates an error when borderType has an incorrect value.

See Also