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

CrossCorrNorm

Computes a normalized cross-correlation between an image and a template.

Syntax

Case 1: Operating on data with integer output

IppStatus ippiCrossCorrNorm_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 ippiCrossCorrNorm_<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

Case 3: Operating on data with integer output with TL functions

IppStatus ippsCrossCorrNorm_ 8u_C1RSfs_T (const Ipp8u* pSrc, int srcStep, IppiSizesrcRoiSize, const Ipp8u* pTpl, int tplStep, IppiSize tplRoiSize, Ipp8u* pDst, int dstStep, int scaleFactor, IppEnum algType, Ipp8u* pBuffer);

Case 4: Operating on data with floating-point output with TL functions

IppStatus ippsCrossCorrNorm_ <mod>_T (const Ipp<srcDatatype>* pSrc, int srcStep, IppiSizesrcRoiSize, 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

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

Cross-correlation values Rtx(r,c)

ippiNorm

Normalized cross-correlation values ρtx(r,c)

ippiNormCoefficient

Normalized correlation coefficients γtx(r,c)

For more information about 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

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

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:

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

ippStsAlgTypeErr

Indicates an error when:

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

Example

The code example below demonstrates how to use the ippiCrossCorrNormGetBufferSize and ippiCrossCorrNorm 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;
    IppiSize srcRoiSize = { 5,4 };
    IppiSize tplRoiSize = { 3,3 };
    IppiSize dstRoiSize = { 5,4 };// same as src
    
    Ipp32f pSrc[5 * 4] = {  1.0f, 2.0f, 1.5f, 4.1f,  3.6f,
                            0.2f, 3.2f, 2.5f, 1.5f, 10.0f,
                            5.0f, 6.8f, 0.5f, 4.1f,  1.1f,
                            7.1f, 4.2f, 2.2f, 8.7f, 10.0f };
    
    Ipp32f pTpl[3 * 3] = {  2.1f, 3.5f, 7.7f,
                            0.4f, 2.3f, 5.5f,
                            1.4f, 2.8f, 3.1f };
    Ipp32f pDst[5 * 4];
    int srcStep = 5 * sizeof(Ipp32f);
    int tplStep = 3 * sizeof(Ipp32f);
    int dstStep = 5 * sizeof(Ipp32f);
    IppEnum funCfg = (IppEnum)(ippAlgAuto | ippiROISame | ippiNorm);
    Ipp8u* pBuffer;
    int bufSize;

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

    pBuffer = ippsMalloc_8u(bufSize);

    status = ippiCrossCorrNorm_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 ->
  0.53 0.54 0.58 0.50 0.30
  0.68 0.62 0.68 0.83 0.38
  0.77 0.55 0.60 0.81 0.42
  0.81 0.46 0.70 0.62 0.24