Label

group NVCV_C_ALGORITHM_LABEL

Functions

NVCVStatus cvcudaLabelCreate(NVCVOperatorHandle *handle)

Constructs an instance of the Label operator.

Parameters:

handle – [out] Where the operator instance handle will be written to.

  • Must not be NULL.

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Handle is null.

  • NVCV_ERROR_OUT_OF_MEMORY – Not enough memory to create the operator.

  • NVCV_SUCCESS – Operation executed successfully.

NVCVStatus cvcudaLabelSubmit(NVCVOperatorHandle handle, cudaStream_t stream, NVCVTensorHandle in, NVCVTensorHandle out, NVCVTensorHandle bgLabel, NVCVTensorHandle minThresh, NVCVTensorHandle maxThresh, NVCVTensorHandle minSize, NVCVTensorHandle count, NVCVTensorHandle stats, NVCVTensorHandle mask, NVCVConnectivityType connectivity, NVCVLabelType assignLabels, NVCVLabelMaskType maskType)

Executes the Label operation on the given cuda stream. This operation does not wait for completion.

This operation computes the connected-component labeling of one or more input images (in 2D) or volumes (in 3D) inside the input tensor, yielding labels in the output tensor with same rank and shape. Labels are numbers uniquely assigned to each connected region, for example: 

Input   0 0 0 0  Output   0 0 0 0
image:  1 1 0 1  labels:  4 4 0 7
        0 0 0 1           0 0 0 7
        0 1 1 1           0 7 7 7
In the above example, three distinct regions were identified and labeled as 0, 4 and 7. Note that the region labeled with 0 remained with the same value as the input, and label numbers 4 and 7 were assigned in non-consecutive ordering. Some values in the input may be ignored, i.e. not labeled, using the bgLabel tensor to define those values as background, which usually is set to the value zero. For example: 
Input   0 0 1 0  Output   0 0 2 3  Zeros in  0 0 2 0
image:  0 1 0 1  labels:  0 5 6 7  bgLabel:  0 5 0 7
        0 0 1 1           0 0 7 7            0 0 7 7
        0 1 1 1           0 7 7 7            0 7 7 7
Limitations:

Input: Data Layout: [HWC], [NHWC], [DHWC], [NDHWC] Channels: [1]

Data Type

Allowed

8bit Unsigned

Yes

8bit Signed

Yes

16bit Unsigned

Yes

16bit Signed

Yes

32bit Unsigned

Yes

32bit Signed

Yes

32bit Float

No

64bit Float

No

Output: Data Layout: [HWC], [NHWC], [DHWC], [NDHWC] Channels: [1]

Data Type

Allowed

8bit Unsigned

No

8bit Signed

No

16bit Unsigned

No

16bit Signed

No

32bit Unsigned

Yes

32bit Signed

Yes

32bit Float

No

64bit Float

No

Input/Output dependency

Property

Input == Output

Data Layout

Yes

Data Type

No

Number

Yes

Channels

Yes

Width

Yes

Height

Yes

Depth

Yes

Note

The number of elements (pixels or voxels) in input and output tensors must be at most \( 2^31 - 1 \).

Parameters:

  • handle – [in] Handle to the operator.

    • Must not be NULL.

  • stream – [in] Handle to a valid CUDA stream.

  • in – [in] Input tensor. The expected layout is [HWC] or [NHWC] for 2D labeling or [DHWC] or [NDHWC] for 3D labeling, with either explicit C dimension or missing C with channels embedded in the data type. The N dimension is the number of samples, i.e. either 2D images with height H and width W or 3D volumes with depth D and height H and width W, inside the tensor. This operator labels regions, i.e. connected components, of each input image or volume read from the in tensor.

    • Check above limitations table to the input tensor data layout, number of channels and data type.

  • out – [out] Output tensor. The expected layout is [HWC] or [NHWC] for 2D labeling or [DHWC] or [NDHWC] for 3D labeling, with either explicit C dimension or missing C with channels embedded in the data type. The N dimension is the number of samples, i.e. either 2D images with height H and width W or 3D volumes with depth D and height H and width W, inside the tensor. This operator labels regions, i.e. connected components, on the input writing the labels to the out tensor.

    • Check above limitations table to the output tensor data layout, number of channels and data type.

  • bgLabel – [in] Background label tensor. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as the number of samples N, matching input and output tensors, and a potential last dimension C with number of channels. If present, this tensor is used by the operator to define background values in the input tensor to be ignored during labeling. If not present, all values in the input are labeled.

    • It must have the same number of samples as input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have data type the same as the input.

    • It may be NULL to consider all values in the input as valid values to be labeled.

  • minThresh – [in] Minimum-threshold value tensor. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as the number of samples N, matching input and output tensors, and a potential last dimension C with number of channels. If present, this tensor is used by the operator as a pre-filter step to define minimum values in the input tensor to be thresholded into a binary image, i.e. values below it are set to 0 and above or equal it are set to 1. Labeling is done after this pre-filter step, where bgLabel may be applied for instance to ignore zeroes as background.

    • It must have the same number of samples as input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have data type the same as the input.

    • It may be NULL to not apply minimum thresholding as a pre-filter.

  • maxThresh – [in] Maximum-threshold value tensor. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as the number of samples N, matching input and output tensors, and a potential last dimension C with number of channels. If present, this tensor is used by the operator as a pre-filter step to define maximum values in the input tensor to be thresholded into a binary image, i.e. values above it are set to 0 and below or equal it are set to 1. Labeling is done after this pre-filter step, where bgLabel may be applied for instance to ignore zeroes as background.

    • It must have the same number of samples as input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have data type the same as the input.

    • It may be NULL to not apply maximum thresholding as a pre-filter.

  • minSize – [in] Minimum-size value tensor. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as the number of samples N, matching input and output tensors, and a potential last dimension C with number of channels. If present, this tensor is used by the operator as a post-filter step to define minimum-size regions in the output tensor to keep their labels, i.e. connected-component regions with less than this minimum number of elements are set to the background value defined in the bgLabel value. Labeling is done before this post-filter step, also known as island-removal step.

    • It must have the same number of samples as input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have S32 or U32 data type.

    • It may be NULL to not apply minimum size regions removal as a post-filter.

    • If not NULL, the bgLabel and stats tensors must not be NULL as well.

  • count – [out] Count of labels tensor. The expected layout is [N] or [NC], meaning rank-1 or rank-2 tensor with first dimension as the number of samples N, matching input and output tensors, and a potential last dimension C with number of channels. If present, this tensor is used by the operator to store the number of connected regions, or components, labeled. The background label is ignored and thus not counted. It counts regions that may be beyond the maximum capacity of stats tensor, and regions potentially removed by minSize tensor.

    • It must have the same number of samples as input and output tensors.

    • It must have one element per sample, i.e. number of channels must be 1 in a [NC] tensor.

    • It must have S32 or U32 data type.

    • It may be NULL to disregard counting the number of different labels found.

  • stats – [out] Statistics tensor. The expected layout is [NMA], meaning rank-3 tensor with first dimension as the number of samples N, matching input and output tensors, second dimension M as maximum number of different labels statistics to be computed, and a third dimension A as the amount of statistics to be computed per label (fixed as 7 for 2D or 9 for 3D). If present, this tensor is used by the operator to store information per connected-component label. The background label is ignored and thus its statistics is not computed.

    • It must have the same number of samples as input and output tensors.

    • It must have a number of statistics M per sample N equal to the maximum allowed number of label statistics that can be computed by the Label operator per sample image (or volume). The actual number of labels found is stored in count (see above).

    • For 2D labeling, it must have in the last dimension A=7 elements to store at: (0) the original label number; (1) leftmost position; (2) topmost position; (3) width size; (4) height size; (5) count of pixels (i.e. size of the labeled region); (6) region marks (0 means no marks, 1 means region was removed, 2 means region inside the mask will not be removed). And for 3D labeling, it must have in the last dimension A=9 elements to store at: (0) the original label number; (1) leftmost position; (2) topmost position; (3) shallowmost position; (4) width size; (5) height size; (6) depth size; (7) count of voxels (i.e. size of the labeled region); (8) region marks (0 means no marks, 1 means region was removed, 2 means region inside the mask will not be removed).

    • It must have S32 or U32 data type.

    • It may be NULL to disregard computing statistics information on different labels found.

    • It must not be NULL if assignLabel is NVCV_LABEL_SEQUENTIAL, the index of each label statistics is used as the new sequential label replacing the original label in the output, the sequential labels are up to the maximum capacity M

    • If not NULL, the count tensor must not be NULL as well.

  • mask – [in] Mask tensor. The expected layout is [HWC] or [NHWC] for 2D masking or [DHWC] or [NDHWC] for 3D masking, with either explicit C dimension or missing C with channels embedded in the data type. The N dimension is the number of samples, if missing it is considered to be N=1, in case N=1 and in and out tensors have N>1 the same mask is to be applied to all images (2D) or volumes (3D). A value of zero in the mask is considered to be outside the mask and non-zero is inside. The mask behavior is controlled by maskType.

    • If number of samples N is present in the layout, it must be either 1 or equal to N in the in out tensors.

    • It must have the same height H and width W as in and out tensors.

    • It must have the same depth D as in and out tensors in case of 3D.

    • If channel C is present in the layout, it must be 1.

    • It must have S8 or U8 data type.

    • If not NULL and maskType is NVCV_REMOVE_ISLANDS_OUTSIDE_MASK_ONLY, the minSize tensor must not be NULL as well.

  • connectivity – [in] Specify connectivity of elements for the operator, see NVCVConnectivityType.

    • It must conform with in and out tensors, i.e. 3D labeling requires [DHWC] or [NDHWC] tensor layouts and 2D labeling requires [HWC] or [NHWC], where the C channel may be missing as embedded in data type.

  • assignLabels – [in] Specify how labels are assigned by the operator, see NVCVLabelType. Use NVCV_LABEL_FAST to do fast labeling, i.e. assign non-consecutive label numbers fast. Use NCVC_LABEL_SEQUENTIAL to have consecutive label numbers instead.

  • maskType – [in] Specify how the mask tensor affects this operator, see NVCVLabelMaskType. Use NVCV_REMOVE_ISLANDS_OUTSIDE_MASK_ONLY to only remove islands, i.e. regions with less than minSize elements, that are outside the mask (defined by zeros in the mask).

Return values:

  • NVCV_ERROR_INVALID_ARGUMENT – Some parameter is outside valid range.

  • NVCV_ERROR_INTERNAL – Internal error in the operator, invalid types passed in.

  • NVCV_SUCCESS – Operation executed successfully.