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

LabelMarkers

Labels markers in image with different values.

Syntax

IppStatus ippiLabelMarkers_8u_C1IR(Ipp8u* pMarker, int markerStep, IppiSize roiSize, int minLabel, int maxLabel, IppiNorm norm, int* pNumber, Ipp8u* pBuffer);

IppStatus ippiLabelMarkers_8u32s_C1R(Ipp8u* pSrcMarker, int srcMarkerStep, Ipp32s* pDstMarker, int dstMarkerStep, IppiSize roiSize, int minLabel, int maxLabel, IppiNorm norm, int* pNumber, Ipp8u* pBuffer);

IppStatus ippiLabelMarkers_16u_C1IR(Ipp16u* pMarker, int markerStep, IppiSize roiSize, int minLabel, int maxLabel, IppiNorm norm, int* pNumber, Ipp8u* pBuffer);

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

pMarker
Pointer to the source and destination image ROI (for in-place flavors).
markerStep
Distance in bytes between starts of consecutive lines in the source and destination image.
pSrcMarker

Pointer to the source image ROI (for not-in-place flavors).

srcMarkerStep

Distance, in bytes, between the starting points of consecutive lines in the source image (for not-in-place flavors).

pDstMarker

Pointer to the source and destination image ROI (for not-in-place flavors).

dstMarkerStep

Distance, in bytes, between the starting points of consecutive lines in the destination image (for not-in-place flavors).

minLabel
Minimal value of the marker label (0 <minLabelmaxLabel).
maxLabel
Maximal value of the marker label (minLabelmaxLabel< 255 for 8-bit markers, and minLabelmaxLabel< 65535 for 16-bit markers, and minLabelmaxLabel< (231-1) for 32-bit markers).
roiSize
Size of the source and destination image ROI in pixels.
norm
Specifies type of the norm to form the mask for marker propagation:

ippiNormInf

Infinity norm (8-connectivity);

ippiNormL1

L1 norm (4-connectivity).
pNumber
Pointer to the number of markers.
pBuffer
Pointer to the working buffer.

Description

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

This function labels markers in the destination image with different integer values. Each connected set of non-zero image pixels is treated as the separate marker. 4- or 8-connectivity can be used depending on the norm type. All pixels belonging to the same marker are set to the same value from the interval [minLabel, maxLabel]. Two markers can be labeled with the same value if the number of connected components exceeds minLabel-maxLabel+1. The image with labeled markers can be used as the seed image for segmentation by functions ippiSegmentWatershed or ippiSegmentGradient functions.

The function requires the working buffer pBuffer whose size should be computed by the function ippiLabelMarkersGetBufferSize beforehand.

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 markerStep is less than roiSize.width * < pixelSize>.

ippStsNotEvenStepErr

Indicates an error condition if markerStep, srcMarkerStep, or dstMarkerStep is not divisible by respective <pixelSize>.

ippStsBadArgErr

Indicates an error condition if one of the minLabel, maxLabel, and norm has an illegal 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 labelling connected non-zero components with 
// different label values using Intel(R) Integrated Primitives (Intel(R) IPP) functions:
//     ippiLabelMarkersGetBufferSize_16u_C1R
//     ippiLabelMarkers_16u_C1IR


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

#define WIDTH   8  /* source image width */
#define HEIGHT  8  /* source image height */

/* 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 Ipp16u pMarker[WIDTH*HEIGHT] = /* Pointer to source and destination marker image */
{ 0, 12, 13,  0,  0,  0,  0,  0,
  0, 22, 23, 24,  0,  0,  0,  0,
  0, 32, 33, 34,  0,  0,  0,  0,
  0, 42, 43, 44,  0,  0,  0,  0,
  0,  0, 53, 54,  0, 56, 57, 58,
  0,  0,  0,  0,  0, 66,  0, 68,
  0,  0,  0, 57,  0, 76, 77, 78,
  0,  0,  0,  0, 68,  0,  0,  0
};

/* 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 markerStep = WIDTH*sizeof(Ipp16u); /* Steps, in bytes, through the source images */
    IppiSize roiSize = { WIDTH, HEIGHT };  /* Size of source ROI in pixels */
    int minLabel = 1;                      /* Minimal label value */
    int maxLabel = 30000;                  /* Maximal label value */
    int markersNum = 0;                    /* Pointer to number of markers */
    Ipp8u* pBuffer = NULL;                 /* Pointer to the work buffer */
    int bufferSize = 0;

    /* Calculate size of temporary buffer */
    check_sts( status = ippiLabelMarkersGetBufferSize_16u_C1R(roiSize, &bufferSize) )

    pBuffer = ippsMalloc_8u(bufferSize);

    /* Label connected non-zero components with different label values */
    check_sts( status = ippiLabelMarkers_16u_C1IR(pMarker, markerStep, roiSize, minLabel, maxLabel, ippiNormL1, &markersNum, pBuffer) )

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