GradientVectorSobel

Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference

Download PDF

ID 790148

Date 6/24/2024

Version

Public

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

Visible to Intel only — GUID: GUID-FAD741A0-8044-4DF5-B514-71F96E696D51

View Details

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

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.

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 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 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 Performance 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 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 Performance 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;
}

Parent topic: Image Gradients

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference

GradientVectorSobel

Syntax

Include Files

Domain Dependencies

Parameters

Description

Return Values

Example

See Also