DistanceTransform

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-D3089E19-7D05-4606-AE7C-20C163EC814A

View Details

DistanceTransform

Calculates distance to the closest zero pixel for all non-zero pixels of source image.

Syntax

Case 1: Not-in-place operations

IppStatus ippiDistanceTransform_3x3_<mod>(const Ipp8u* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize, Ipp32s* pMetrics);

IppStatus ippiDistanceTransform_5x5_<mod>(const Ipp8u* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize, Ipp32s* pMetrics);

Supported values for mod:

8u_C1R

8u16u_C1R

IppStatus ippiDistanceTransform_3x3_8u32f_C1R(const Ipp8u* pSrc, int srcStep, Ipp32f* pDst, int dstStep, IppiSize roiSize, Ipp32f* pMetrics);

IppStatus ippiDistanceTransform_5x5_8u32f_C1R(const Ipp8u* pSrc, int srcStep, Ipp32f* pDst, int dstStep, IppiSize roiSize, Ipp32f* pMetrics);

Case 2: In-place operations

IppStatus ippiDistanceTransform_3x3_8u_C1IR(Ipp8u* pSrcDst, int srcDstStep, IppiSize roiSize, Ipp32s* pMetrics);

IppStatus ippiDistanceTransform_5x5_8u_C1IR(Ipp8u* pSrcDst, int srcDstStep, IppiSize roiSize, Ipp32s* pMetrics);

Include Files

ippcv.h

Domain Dependencies

Headers: ippcore.h, ippvm.h, ipps.h, ippi.h

Libraries: ippcore.lib, ippvm.lib, ipps.lib, ippi.lib

Parameters

pSrc: Pointer to the source image ROI.
srcStep: Distance in bytes between starts of consecutive lines in the source image.
pDst: Pointer to the ROI in the destination distance image.
dstStep: Distance in bytes between starts of consecutive lines in the destination image.
pSrcDst: Pointer to the source and destination image ROI for in-place operation.
srcDstStep: Distance in bytes between starts of consecutive lines in the source and destination image for in-place operation.
roiSize: Size of the image ROI in pixels.
pMetrics: Pointer to the array that specifies used metrics.

Description

This function operates with ROI (see Regions of Interest in Intel IPP).

This function approximates the actual distance from the closest zero pixel to each certain pixel with the sum of atomic distances from the fixed set. The set consists of two values for a 3x3 mask and three values for a 5x5 mask.

Figure “3x3 Mask” shows the result of the distance transform of a 7x7 image with zero point in the center. This example corresponds to a 3x3 mask. Two numbers specify metrics in case of the 3x3 mask:

distance between two pixels that share an edge,
distance between the pixels that share a corner.

In this case the values are 1 and 1.5 correspondingly.

3x3 Mask
4.5	4	3.5	3	3.5	4	4.5
4	3	2.5	2	2.5	3	4
3.5	2.5	1.5	1	1.5	2.5	3.5
3	2	1	0	1	2	3
3.5	2.5	1.5	1	1.5	2.5	3.5
4	3	2.5	2	2.5	3	4
4.5	4	3.5	3	3.5	4	4.5

Figure “5x5 Mask” shows the distance transform for the same image, but for a 5x5 mask.

For this mask yet another number is added to specify metrics - the additional distance, i.e., the distance between pixels corresponding to the chess knight move.

In this example, the additional distance is equal to 2.

5x5 Mask
4	3.5	3	3	3	3.5	4
3.5	3	2	2	2	3	3.5
3	2	1.5	1	1.5	2	3
3	2	1	0	1	2	3
3	2	1.5	1	1.5	2	3
3.5	3	2	2	2	3	3.5
4	3.5	3	3	3	3.5	4

Return Values

ippStsNoErr	Indicates no error. Any other value indicates an error or a warning.
ippStsNullPtrErr	Indicates an error condition if one of the specified pointers is `NULL`.
ippStsSizeErr	Indicates an error condition if roiSize has a field with zero or negative value.
ippStsStepErr	Indicates an error condition if srcStep or dstStep is less than roiSize.width*<pixelSize>.
ippStsNotEvenStepErr	Indicates an error condition if step value is not divisible by 2 for 16u images, and by 4 for 32f images.
ippStsCoeffErr	Indicates an error condition if at least one element of pMetrics array has zero or negative value.

Example

/*******************************************************************************
* 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 calculating distance between pixels 
// using Intel(R) Integrated Performance Primitives (Intel(R) IPP) function:
//     ippiDistanceTransform_3x3_8u_C1R


#include <stdio.h>
#include "ipp.h"

/* 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 */

int main(void)
{
    IppStatus status = ippStsNoErr;
    Ipp8u pSrc[7 * 7] = {     /* Pointer to source image */
        1, 2, 3, 4, 5, 6, 7,
        1, 0, 3, 4, 5, 6, 7,
        1, 2, 3, 4, 5, 6, 7,
        1, 2, 3, 0, 5, 6, 7,
        1, 2, 3, 4, 5, 6, 7,
        1, 2, 3, 4, 5, 0, 7,
        1, 2, 3, 4, 5, 6, 7
    };
    Ipp8u pDst[7 * 7];             /* Pointer to destination image */
    int srcStep = 7, dstStep = 7;  /* Steps, in bytes, through the source/destination images */
    IppiSize roiSize   = { 7, 7 }; /* Size of source/destination ROI in pixels */
    Ipp32s pMetrics[2] = { 2, 2 }; /* Array that determines metrics used */
    /* For every non-zero pixel in the source image, the functions calculate   */
    /*                     distance between that pixel and nearest zero pixel. */
    check_sts( status = ippiDistanceTransform_3x3_8u_C1R(pSrc, srcStep, pDst, dstStep, roiSize, pMetrics) )

EXIT_MAIN
    printf("Exit status %d (%s)\n", (int)status, ippGetStatusString(status));
    return (int)status;
}

Result:

1 2 3 4 5 6 7 
1 0 3 4 5 6 7 
1 2 3 4 5 6 7 
1 2 3 0 5 6 7    src 
1 2 3 4 5 6 7 
1 2 3 4 5 0 7 
1 2 3 4 5 6 7

2 2 2 4 6 6 6 
2 0 2 4 4 4 6 
2 2 2 2 2 4 6 
4 4 2 0 2 4 4    dst 
6 4 2 2 2 2 2 
6 4 4 4 2 0 2 
6 6 6 4 2 2 2

Parent topic: Distance Transform Functions

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

DistanceTransform

Syntax

Include Files

Domain Dependencies

Parameters

Description

Return Values

Example