Developer Reference

  • 2020
  • 10/21/2020
  • Public Content
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.
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
G
x
and
G
y
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
  • G
    x
    and
    G
    y
    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
G
x
and
G
y
is computed by the formula:
Color image (C3) input :
If input is a color image, the
ippiGradientVectorScharr
function computes the spatial image derivatives
G
x
and
G
y
for each channel of the image using the specified differential operator. For each pixel (
x
,
y
) this function chooses the derivatives for which
L2
(
G
x
,
G
y
) 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.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804