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

SqrDistanceNorm

Computes Euclidean distance between an image and a template.

Syntax

Case 1: Operating with integer output

IppStatus ippiSqrDistanceNorm_8u_C1RSfs(const Ipp8u* pSrc, int srcStep, IppiSize srcRoiSize, const Ipp8u* pTpl, int tplStep, IppiSize tplRoiSize, Ipp8u* pDst, int dstStep, int scaleFactor, IppEnum algType, Ipp8u* pBuffer);

Case 2: Operating on data with floating-point output

IppStatus ippiSqrDistanceNorm_<mod>(const Ipp<srcDatatype>* pSrc, int srcStep, IppiSize srcRoiSize, const Ipp<srcDatatype>* pTpl, int tplStep, IppiSize tplRoiSize, Ipp32f* pDst, int dstStep, IppEnum algType, Ipp8u* pBuffer);

Supported values for mod:

32f_C1R

8u32f_C1R

16u32f_C1R

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.

srcRoiSize

Size of the source ROI in pixels.

pTpl

Pointer to the template image.

tplStep

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

tplRoiSize

Size of the template ROI in pixels.

pDst

Pointer to the destination image ROI.

dstStep

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

scaleFactor

Scale factor.

algType

Bit-field mask for the algorithm type definition. Possible values are the results of composition of the IppAlgType, IppiROIShape, and IppiNormOp values.

pBuffer

Pointer to the work buffer.

Description

Before using this function, you need to compute the size of the work buffer using the ippiSqrDistanceNormGetBufferSize function.

This function operates with ROI.

Depending on the IppiNormOp value set to the algType parameter, the function calculates the following results:

IppiNormOp Value

Result

ippiNormNone

Squared Euclidean distances Stx(r,c)

ippiNorm

Normalized squared Euclidean distances σtx(r,c)

For more information on how each value is calculated, see Image Proximity Measures.

The size of the resulting matrix depends on the IppiROIShape value:

IppiROIShape Value

Matrix Size

ippiROIFull

(Ws + Wt - 1) * (Hs + Ht - 1)

ippiROISame Ws*Hs
ippiROIValid

(Ws -Wt + 1) * (Hs -Ht +1)

where

  • Ws , Hs is the width and height of the source image
  • Wt , Ht is the width and height of the template image

Return Values

ippStsNoErr

Indicates no error.

ippStsNullPtrErr

Indicates an error when any of the specified pointers is NULL.

ippStsStepErr

Indicates an error when the value of srcStep, tplStep, or dstStep is negative, or equal to zero.

ippStsSizeErr

Indicates an error when:

  • srcRoiSize or tplRoiSize is negative, or equal to zero
  • the value of srcRoiSize is less than the corresponding value of tplRoiSize

ippStsAlgTypeErr

Indicates an error when:

  • the result of the bitwise AND operation between the algType and ippAlgMask values differs from the ippAlgAuto, ippAlgDirect, or ippAlgFFT values;
  • the result of the bitwise AND operation between the algType and ippiROIMask values differs from the ippiROIFull, ippiROISame, or ippiROIValid values;
  • the result of the bitwise AND operation between the algType and ippiNormMask values differs from the ippiNormNone or ippiNorm values;

Example

The code example below demonstrates how to use the ippiSqrDistanceNormGetBufferSize and ippiSqrDistanceNorm functions.

#include "ipps.h"
#include "ippi.h"
#include <iostream>
#include <iomanip>

void print_dst_2D_32f(Ipp32f* pDst, int dstStep, IppiSize roiSize) {
    std::cout << "pDst ->\n";
    std::cout.precision(2);
    for (int h = 0; h < roiSize.height; h++) {
        for (int w = 0; w < roiSize.width; w++) {
            std::cout << std::setw(6) << std::fixed << pDst[w];
        }
        pDst = (Ipp32f*)((Ipp8u*)pDst + dstStep);
        std::cout << std::endl;
    }
}

IppStatus main() {
    IppStatus status;
    Ipp32f pSrc[5 * 4];
    Ipp32f pTpl[5 * 4];
    Ipp32f pDst[9 * 7];//(5+5-1) x (4+4-1)

    IppiSize srcRoiSize = { 5,4 };
    IppiSize tplRoiSize = { 5,4 };
    IppiSize dstRoiSize = { 9,7 };
    int srcStep = 5 * sizeof(Ipp32f);
    int tplStep = 5 * sizeof(Ipp32f);
    int dstStep = 9 * sizeof(Ipp32f);
    IppEnum funCfg = (IppEnum)(ippAlgAuto | ippiNorm | ippiROIFull);
    Ipp8u* pBuffer;
    int bufSize = 0;

    ippiSet_32f_C1R(2.0, pSrc, srcStep, srcRoiSize);
    ippiSet_32f_C1R(1.0, pTpl, tplStep, tplRoiSize);

    status = ippiSqrDistanceNormGetBufferSize(srcRoiSize, tplRoiSize, funCfg, &bufSize);
    if (status != ippStsNoErr) return status;

    pBuffer = ippsMalloc_8u(bufSize);

    status = ippiSqrDistanceNorm_32f_C1R(pSrc, srcStep, srcRoiSize, pTpl, tplStep, tplRoiSize, pDst, dstStep, funCfg, pBuffer);
    print_dst_2D_32f(pDst, dstStep, dstRoiSize);

    ippsFree(pBuffer);
    return status;
}

The result is as follows:

 pDst ->
  2.24 1.58 1.29 1.12 1.00 1.12 1.29 1.58 2.24
  1.58 1.12 0.91 0.79 0.71 0.79 0.91 1.12 1.58
  1.29 0.91 0.75 0.65 0.58 0.65 0.75 0.91 1.29
  1.12 0.79 0.65 0.56 0.50 0.56 0.65 0.79 1.12
  1.29 0.91 0.75 0.65 0.58 0.65 0.75 0.91 1.29
  1.58 1.12 0.91 0.79 0.71 0.79 0.91 1.12 1.58
  2.24 1.58 1.29 1.12 1.00 1.12 1.29 1.58 2.24

See Also