Developer Reference

  • 2020
  • 07/15/2020
  • Public Content
Contents

GradientVectorSobel

Computes gradient vectors of an image using the Sobel operator.

Syntax

IppStatus ippiGradientVectorSobel_<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 ippiGradientVectorSobel_<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 GradientVectorGetBufferSize 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
ippiGradientVectorSobel
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 Sobel operator:
for the 5x5 Sobel 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
ippiGradientVectorSobel
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.
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.

Example

GradientVectorSobel1
:
/******************************************************************************* * Copyright 2015-2020 Intel Corporation. * * This software and the related documents are Intel copyrighted materials, and * your use of them is governed by the express license under which they were * provided to you (License). Unless the License provides otherwise, you may not * use, modify, copy, publish, distribute, disclose or transmit this software or * the related documents without Intel's prior written permission. * * This software and the related documents are provided as is, with no express * or implied warranties, other than those that are expressly stated in the * License. *******************************************************************************/ // A simple example of gradient vectors computation over an image with the Sobel // operator using Intel(R) Integrated Primitives (Intel(R) IPP) functions: // ippiGradientVectorGetBufferSize // ippiGradientVectorSobel_8u16s_C3C1R #include <stdio.h> #include "ipp.h" #define WIDTH 8 /* source image width */ #define HEIGHT 4 /* source image height */ #define ROI_WIDTH 8 /* source image ROI width */ #define ROI_HEIGHT 4 /* source image ROI height */ #define NUMCHN 1 /* number of channels */ /* Next two defines are created to simplify code reading and understanding */ #define EXIT_MAIN exitLine: /* Label for Exit */ #define check_sts(st) if((st) != ippStsNoErr) goto exitLine; /* Go to Exit if Intel(R) IPP function returned status different from ippStsNoErr */ static Ipp8u pSrc[(NUMCHN * WIDTH + 1)* HEIGHT] = /* Pointer to source image */ { 1, 2, 3, 4, 8, 8, 8, 8, 1, 2, 3, 4, 8, 8, 8, 8, 1, 2, 3, 4, 8, 8, 8, 8, 1, 2, 3, 4, 8, 8, 8, 8 }; /* Results of ippMalloc() are not validated because Intel(R) IPP functions perform bad arguments check and will return an appropriate status */ int main(void) { IppStatus status = ippStsNoErr; int srcStep = WIDTH*NUMCHN; /* Steps, in bytes, through the source images */ Ipp8u* psrc = pSrc + 1*srcStep + 1 * NUMCHN; /* Pointer to source ROI image */ IppiSize roiSize = { ROI_WIDTH, ROI_HEIGHT }; /* Size of source ROI in pixels */ Ipp16s pGx[4 * 7], pGy[4 * 7]; /* Define x and y gradient components */ int gxStep = 4 * sizeof(Ipp16s), gyStep = 4 * sizeof(Ipp16s);/* Steps through the X and Y component image */ Ipp8u* pBuffer = NULL; /* Pointer to the work buffer */ Ipp8u borderValue = 0; int bufferSize = 0; Ipp16s pMag[ROI_WIDTH*ROI_HEIGHT]; /* Pointer to the magnitude of computed gradient */ int magStep = ROI_WIDTH*sizeof(Ipp16s); /* Step through the magnitude image */ Ipp32f pAngle[ROI_WIDTH*ROI_HEIGHT]; /* Pointer to the angle of computed gradient */ int angleStep = ROI_WIDTH*sizeof(Ipp32f);/* Step through the magnitude image */ IppiMaskSize maskSize = ippMskSize3x3; IppiBorderType borderType = ippBorderConst; check_sts( status = ippiGradientVectorGetBufferSize(roiSize, maskSize, ipp8u, NUMCHN, &bufferSize) ) pBuffer = ippsMalloc_8u(bufferSize); /* Compute gradient using 3x3 Sobel operator (source ROI at point x=1, y=1) */ check_sts( status = ippiGradientVectorSobel_8u16s_C1R(psrc, srcStep, pGx, gxStep, pGy, gyStep, pMag, magStep, pAngle, angleStep, roiSize, maskSize, ippNormL2, borderType, borderValue, pBuffer) ) EXIT_MAIN ippsFree(pBuffer); printf("Exit status %d (%s)\n", (int)status, ippGetStatusString(status)); return (int)status; }
GradientVectorSobel2
:
/******************************************************************************* * Copyright 2015-2020 Intel Corporation. * * This software and the related documents are Intel copyrighted materials, and * your use of them is governed by the express license under which they were * provided to you (License). Unless the License provides otherwise, you may not * use, modify, copy, publish, distribute, disclose or transmit this software or * the related documents without Intel's prior written permission. * * This software and the related documents are provided as is, with no express * or implied warranties, other than those that are expressly stated in the * License. *******************************************************************************/ // A simple example of gradient vectors computation over an image using Sobel // using Intel(R) Integrated Primitives (Intel(R) IPP) functions: // ippiGradientVectorGetBufferSize // ippiGradientVectorSobel_8u16s_C3C1R #include <stdio.h> #include "ipp.h" #define WIDTH 5 /* source image width */ #define HEIGHT 9 /* source image height */ #define ROI_WIDTH 3 /* source image ROI width */ #define ROI_HEIGHT 7 /* source image ROI height */ #define NUMCHN 3 /* number of channels */ /* Next two defines are created to simplify code reading and understanding */ #define EXIT_MAIN exitLine: /* Label for Exit */ #define check_sts(st) if((st) != ippStsNoErr) goto exitLine; /* Go to Exit if Intel(R) IPP function returned status different from ippStsNoErr */ static Ipp8u pSrc[(NUMCHN * WIDTH + 1)* HEIGHT] = /* Pointer to source image */ { 0x62, 0xd6, 0x4b, 0x23, 0xc4, 0x66, 0x20, 0x1a, 0x15, 0x0e, 0xf1, 0xd5, 0x42, 0x4e, 0x5a, 0x00, 0x86, 0x1e, 0xb5, 0x2d, 0x16, 0xfd, 0x30, 0xc7, 0x5e, 0x04, 0x1d, 0x36, 0x82, 0x9c, 0xb6, 0x00, 0x97, 0xd6, 0x16, 0x57, 0x3a, 0x1e, 0x0a, 0x55, 0xa0, 0xf3, 0xc5, 0x97, 0x68, 0xe6, 0x64, 0x00, 0xde, 0x7d, 0x1c, 0x43, 0x4d, 0x57, 0xf8, 0xec, 0xe0, 0x9c, 0x30, 0xc3, 0xb9, 0xa2, 0x8c, 0x00, 0x58, 0xb3, 0x10, 0x27, 0xac, 0x32, 0x59, 0x82, 0xaa, 0xe5, 0x24, 0x62, 0xd2, 0x26, 0x78, 0x00, 0x2f, 0x05, 0xd9, 0x90, 0x01, 0x70, 0xd9, 0x5a, 0xdb, 0x36, 0x80, 0xca, 0xf7, 0x2f, 0x66, 0x00, 0xb6, 0x13, 0x6e, 0x5f, 0x72, 0x85, 0xc8, 0x97, 0x66, 0x8b, 0x93, 0x9c, 0x74, 0x4b, 0x23, 0x00, 0x5d, 0xd3, 0x4a, 0x18, 0x43, 0x6e, 0xe9, 0x4b, 0xac, 0xdf, 0xc3, 0xa7, 0xef, 0x69, 0xe1, 0x00, 0xdc, 0xfe, 0x20, 0x30, 0x55, 0x7a, 0x48, 0x90, 0xd7, 0x5e, 0xfd, 0x9d, 0xc5, 0x6d, 0x15, 0x00, }; /* Results of ippMalloc() are not validated because Intel(R) IPP functions perform bad arguments check and will return an appropriate status */ int main(void) { IppStatus status = ippStsNoErr; int srcStep = WIDTH*NUMCHN; /* Steps, in bytes, through the source images */ Ipp8u* psrc = pSrc + 1*srcStep + 1 * NUMCHN; /* Pointer to source ROI image */ IppiSize roiSize = { ROI_WIDTH, ROI_HEIGHT }; /* Size of source ROI in pixels */ Ipp16s pGx[4 * 7], pGy[4 * 7]; /* Define x and y gradient components */ int gxStep = 4 * sizeof(Ipp16s), gyStep = 4 * sizeof(Ipp16s);/* Steps through the X and Y component image */ Ipp8u* pBuffer = NULL; /* Pointer to the work buffer */ Ipp8u borderValue[3] = { 0, 0, 0 }; int bufferSize = 0; Ipp16s pMag[ROI_WIDTH*ROI_HEIGHT]; /* Pointer to the magnitude of computed gradient */ int magStep = ROI_WIDTH*sizeof(Ipp16s); /* Step through the magnitude image */ Ipp32f pAngle[ROI_WIDTH*ROI_HEIGHT]; /* Pointer to the angle of computed gradient */ int angleStep = ROI_WIDTH*sizeof(Ipp32f);/* Step through the magnitude image */ IppiMaskSize maskSize = ippMskSize3x3; IppiBorderType borderType = ippBorderInMem; check_sts( status = ippiGradientVectorGetBufferSize(roiSize, maskSize, ipp8u, NUMCHN, &bufferSize) ) pBuffer = ippsMalloc_8u(bufferSize); /* Compute gradient using 3x3 Sobel operator (source ROI at point x=1, y=1) */ check_sts( status = ippiGradientVectorSobel_8u16s_C3C1R(psrc, srcStep, pGx, gxStep, pGy, gyStep, pMag, magStep, pAngle, angleStep, roiSize, maskSize, ippNormL1, borderType, borderValue, pBuffer) ) EXIT_MAIN ippsFree(pBuffer); printf("Exit status %d (%s)\n", (int)status, ippGetStatusString(status)); return (int)status; }

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