Normalize

group Normalize

Unnamed Group

NVCVStatus cvcudaNormalizeSubmit(NVCVOperatorHandle handle, cudaStream_t stream, NVCVTensorHandle in, NVCVTensorHandle base, NVCVTensorHandle scale, NVCVTensorHandle out, float global_scale, float shift, float epsilon, uint32_t flags)

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

Data normalization is done using externally provided base (typically: mean or min) and scale (typically reciprocal of standard deviation or 1/(max-min)). The normalization follows the formula: 

out[data_idx] = (in[data_idx] - base[param_idx]) * scale[param_idx] * global_scale + shift
Where data_idx is a position in the data tensor (in, out) and param_idx is a position in the base and scale tensors (see below for details). The two additional constants, global_scale and shift can be used to adjust the result to the dynamic range and resolution of the output type.

The scale parameter may also be interpreted as standard deviation - in that case, its reciprocal is used and optionally, a regularizing term is added to the variance. 

m = 1 / sqrt(square(stddev[param_idx]) + epsilon)
out[data_idx] = (in[data_idx] - mean[param_idx]) * m * global_scale + shift

param_idx is calculated as follows (where axis = N,H,W,C): 

param_idx[axis] = param_shape[axis] == 1 ? 0 : data_idx[axis]

Limitations:

Input: Data Layout: [kNHWC, kHWC, kNCHW, kCHW] Channels: [1, 3, 4]

Data Type

Allowed

8bit Unsigned

Yes

8bit Signed

Yes

16bit Unsigned

Yes

16bit Signed

Yes

32bit Unsigned

No

32bit Signed

Yes

16bit Float

No

32bit Float

Yes

64bit Float

No

Output: Data Layout: [kNHWC, kHWC, kNCHW, kCHW] Channels: [1, 3, 4]

Data Type

Allowed

8bit Unsigned

Yes

8bit Signed

Yes

16bit Unsigned

Yes

16bit Signed

Yes

32bit Unsigned

No

32bit Signed

Yes

16bit Float

No

32bit Float

Yes

64bit Float

No

Input/Output dependency 

 Property      |  Input == Output
-------------- | -------------
 Data Layout   | Yes
 Data Type     | Yes
 Number        | Yes
 Channels      | Yes
 Width         | Yes
 Height        | Yes

Scale/Base Tensor: 

 Scale and Base may be a tensor the same shape as the input/output tensors, or it can be a scalar each dimension.
 Dimensions with extent 1 are broadcast over the corresponding input axis.

 For varshape variant with interleaved input, scale and base may represent either a scalar with shape [1,1,1,1],
 or a tensor with shape [1,1,1,C], where C is the number of channels in the input format. Varshape scale and
 base are always broadcast over the image batch.

 For planar (kNCHW / kCHW) tensor input, scale and base must use a planar layout that matches the input
 for non-scalar parameters (e.g. [1,C,1,1] for per-channel parameters). Tensor input supports the same
 per-axis broadcasting rule above. For planar varshape input, scale and base must be batch and spatial
 broadcasted, so use [1,1,1,1] for scalar parameters or [1,C,1,1] for per-channel parameters. A truly
 scalar parameter tensor (numChannels == 1) is also accepted in either layout because both encode the same
 bytes.

Parameters:

  • handle – [in] Handle to the operator.

    • Must not be NULL.

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

  • in – [in] input tensor.

  • base – [in] Base tensor.

  • scale – [in] Scale tensor.

  • out – [out] Output tensor.

  • global_scale – [in] Additional scale value to be used in addition to scale.

  • shift – [in] Additional bias value to be used in addition to base.

  • epsilon – [in] Epsilon to use when CVCUDA_NORMALIZE_SCALE_IS_STDDEV flag is set as a regularizing term to be added to variance.

  • flags – [in] Algorithm flags, use CVCUDA_NORMALIZE_SCALE_IS_STDDEV if scale passed as argument is standard deviation instead or 0 if it is scaling.

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.

NVCVStatus cvcudaNormalizeVarShapeSubmit(NVCVOperatorHandle handle, cudaStream_t stream, NVCVImageBatchHandle in, NVCVTensorHandle base, NVCVTensorHandle scale, NVCVImageBatchHandle out, float global_scale, float shift, float epsilon, uint32_t flags)

Defines

CVCUDA_NORMALIZE_SCALE_IS_STDDEV

Functions

NVCVStatus cvcudaNormalizeCreate(NVCVOperatorHandle *handle)

Constructs and an instance of the normalize operator.

Parameters:

handle – [out] Where the image 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 cvcudaNormalizeScalarSubmit(NVCVOperatorHandle handle, cudaStream_t stream, NVCVTensorHandle in, float4 base, float4 scale, int32_t baseChannels, int32_t scaleChannels, NVCVTensorHandle out, float global_scale, float shift, float epsilon, uint32_t flags)

Executes the normalize operation on the given cuda stream, taking base and scale by value instead of as tensors. This operation does not wait for completion.

This is a “tensor-free” variant of cvcudaNormalizeSubmit: the base (typically: mean or min) and scale (typically reciprocal of standard deviation or 1/(max-min)) values are passed by value in base and scale (each a float4 holding up to four channels) instead of being read from device tensors, so the caller does not allocate or upload any parameter tensor (avoiding a host-to-device copy). The normalization follows the same formula: 

out[data_idx] = (in[data_idx] - base[channel]) * scale[channel] * global_scale + shift
The two additional constants, global_scale and shift, can be used to adjust the result to the dynamic range and resolution of the output type.

The scale parameter may also be interpreted as standard deviation - in that case, its reciprocal is used and optionally, a regularizing term is added to the variance. 

m = 1 / sqrt(square(stddev[channel]) + epsilon)
out[data_idx] = (in[data_idx] - mean[channel]) * m * global_scale + shift

baseChannels and scaleChannels give how many leading lanes of the corresponding float4 are meaningful: 

channel_idx = count == 1 ? 0 : channel
A count of 1 broadcasts a single value to every channel; a count equal to the input channel count supplies one value per channel. Any other count is rejected. Results are bit-identical to cvcudaNormalizeSubmit for the same values.

Limitations:

Input: Data Layout: [kNHWC, kHWC, kNCHW, kCHW] Channels: [1, 3, 4]

Data Type

Allowed

8bit Unsigned

Yes

8bit Signed

Yes

16bit Unsigned

Yes

16bit Signed

Yes

32bit Unsigned

No

32bit Signed

Yes

16bit Float

No

32bit Float

Yes

64bit Float

No

Output: Data Layout: [kNHWC, kHWC, kNCHW, kCHW] Channels: [1, 3, 4]

Data Type

Allowed

8bit Unsigned

Yes

8bit Signed

Yes

16bit Unsigned

Yes

16bit Signed

Yes

32bit Unsigned

No

32bit Signed

Yes

16bit Float

No

32bit Float

Yes

64bit Float

No

Input/Output dependency 

 Property      |  Input == Output
-------------- | -------------
 Data Layout   | Yes
 Data Type     | Yes
 Number        | Yes
 Channels      | Yes
 Width         | Yes
 Height        | Yes

Base/Scale: 

 Base and scale are supplied by value (up to four channels packed in a float4). Each may represent
 a scalar broadcast over every channel (baseChannels / scaleChannels == 1) or a per-channel value
 (count equal to the number of channels in the input). Interleaved (kNHWC / kHWC) and planar
 (kNCHW / kCHW) tensor input are both supported. Unlike #cvcudaNormalizeSubmit, per-axis spatial
 (width/height) parameters are not available; use #cvcudaNormalizeSubmit with parameter tensors
 for spatial parameters. CUDA launch limits require N <= 65535 for interleaved input and
 N*C <= 65535 for planar input.

Parameters:

  • handle – [in] Handle to the operator.

    • Must not be NULL.

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

  • in – [in] input tensor.

  • base – [in] Base values, passed by value (up to four channels in a float4).

  • scale – [in] Scale values, passed by value (up to four channels in a float4).

  • baseChannels – [in] Number of meaningful base lanes: 1 (broadcast) or the input channel count.

  • scaleChannels – [in] Number of meaningful scale lanes: 1 (broadcast) or the input channel count.

  • out – [out] Output tensor.

  • global_scale – [in] Additional scale value to be used in addition to scale.

  • shift – [in] Additional bias value to be used in addition to base.

  • epsilon – [in] Epsilon to use when CVCUDA_NORMALIZE_SCALE_IS_STDDEV flag is set as a regularizing term to be added to variance.

  • flags – [in] Algorithm flags, use CVCUDA_NORMALIZE_SCALE_IS_STDDEV if scale passed as argument is standard deviation instead or 0 if it is scaling.

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.