Developer Reference

  • 2020
  • 10/21/2020
  • Public Content
Contents

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 3
x
3 mask. Two numbers specify metrics in case of the 3
x
3 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 5
x
5 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-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 calculating distance between pixels // using Intel(R) Integrated 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

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