uencode

Quantize and encode floating-point inputs to integer outputs

Syntax

y = uencode(x,n)

y = uencode(x,n,v)

y = uencode(x,n,v,outputSign)

Description

y = uencode(x,n) quantizes the entries in a multidimensional array of floating-point numbers x in the range [-1, 1], and encodes them as integers using 2ⁿ-level quantization. The elements of the output y are unsigned integers with magnitudes in the range [0, 2ⁿ – 1].

y = uencode(x,n,v) allows the input x to have entries with floating-point values in the range [-v,v] before saturating them.

y = uencode(x,n,v,outputSign) specifies the option outputSign to generate signed or unsigned integer outputs.

Examples

Map Floating-Point Scalars to Integers

Map floating-point scalars in [-1, 1] to uint8 (unsigned) integers. Produce a staircase plot. The horizontal axis ranges from -1 to 1 and the vertical axis from 0 to 7 (i.e., $$2^3-1$$).

u = -1:0.01:1;
y = uencode(u,3);
plot(u,y,'.')

Look at saturation effects when you underspecify the peak value for the input.

u = -2:0.5:2;
y = uencode(u,5,1)

y = 1x9 uint8 row vector

    0    0    0    8   16   24   31   31   31

Specify you want signed output.

u = -2:0.5:2;
y = uencode(u,5,2,'signed')

y = 1x9 int8 row vector

   -16   -12    -8    -4     0     4     8    12    15

Input Arguments

x — Floating-point inputs

vector | matrix | multidimensional array

Floating-point inputs, specified as a vector, as a matrix, or as a multidimensional array. The uencode function treats elements from x outside of the range [-v, v] as overflows and saturates them as follows:

• For input elements that are less than -v, uencode returns an output value of 0 (unsigned output) or -2^n/2 (signed output).

• For input elements that are greater than v, uencode returns an output value of 2^n-1 (unsigned output) or 2^n/2-1 (signed output).

The uencode function encodes the real and imaginary components of complex-valued inputs x independently.

Data Types: single | double
Complex Number Support: Yes

n — Measure of number of quantization levels

positive integer scalar

Measure of number of quantization levels, specified as a positive integer scalar. n must be an integer between 2 and 32 (inclusive). The value of 2ⁿ indicates the number of quantization levels established for the quantized array y, and defines a quantization range for y.

The quantization range depends on the value of n and the sign nature of y:

• Signed inputs — from -2ⁿ/2 to (2ⁿ/2)–1.

• Unsigned inputs — from 0 to (2ⁿ–1).

v — Unsaturation amplitude

1 (default) | positive scalar

Unsaturation amplitude, specified as a positive scalar. The function treats elements of x outside of the range [-v,v] as saturation and encodes them as follows:

• For input elements that are less than -v, uencode returns an output value of 0 (unsigned output) or -2^n/2 (signed output).

• For input elements that are greater than v, uencode returns an output value of 2^n-1 (unsigned output) or 2^n/2-1 (signed output).

outputSign — Sign of output

"unsigned" (default) | "signed"

Sign of output, specified as "unsigned" or "signed". The integer type of the output depends on the number of quantization levels 2ⁿ and the value of outputSign, which can be one of these:

• "signed" — Outputs are signed integers with magnitudes in the range [–2ⁿ/2, (2ⁿ/2) – 1].

• "unsigned" — Outputs are unsigned integers with magnitudes in the range [0, 2ⁿ – 1].

Output Arguments

y — Encoded integer outputs

vector | matrix | multidimensional array

Encoded integer outputs, returned as a vector, matrix, or multidimensional array. The output array y has the same dimension as x.

Algorithms

The uencode function maps the floating-point input value to an integer value determined by the requirement for 2ⁿ levels of quantization. This encoding adheres to the definition for uniform encoding specified in ITU-T Recommendation G.701. The input range [-v,v] is divided into 2ⁿ evenly spaced intervals. Input entries in the range [-v,v] are first quantized according to this subdivision of the input range, and then mapped to one of 2ⁿ integers. The range of the output depends on whether you specify that you want signed integers.

The function optimizes the output data types for the number of bits as shown in this table.

n	Unsigned Integer	Signed Integer
2 to 8	uint8	int8
9 to 16	uint16	int16
17 to 32	uint32	int32

References

[1] International Telecommunication Union. General Aspects of Digital Transmission Systems: Vocabulary of Digital Transmission and Multiplexing, and Pulse Code Modulation (PCM) Terms. ITU-T Recommendation G.701. March, 1993.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Input n must be a compile-time constant.

• Optional arguments must be compile-time constants.

Version History

Introduced before R2006a

R2022b: Generate C and C++ code

The uencode function supports C/C++ code generation.