There might be cases, when the format of your data does not conform to ulab
, i.e., there is no obvious way to map the data to any of the five supported dtype
s. A trivial example is an ADC or microphone signal with 32-bit resolution. For such cases, ulab
defines the utils
module, which, at the moment, has four functions that are not numpy
compatible, but which should ease interfacing ndarray
s to peripheral devices.
The utils
module can be enabled by setting the ULAB_HAS_UTILS_MODULE
constant to 1 in ulab.h:
#ifndef ULAB_HAS_UTILS_MODULE
#define ULAB_HAS_UTILS_MODULE (1)
#endif
This still does not compile any functions into the firmware. You can add a function by setting the corresponding pre-processor constant to 1. E.g.,
#ifndef ULAB_UTILS_HAS_FROM_INT16_BUFFER
#define ULAB_UTILS_HAS_FROM_INT16_BUFFER (1)
#endif
With the help of utils.from_int32_buffer
, and utils.from_uint32_buffer
, it is possible to convert 32-bit integer buffers to ndarrays
of float type. These functions have a syntax similar to numpy.frombuffer
; they support the count=-1
, and offset=0
keyword arguments. However, in addition, they also accept out=None
, and byteswap=False
.
Here is an example without keyword arguments
# code to be run in micropython
from ulab import numpy as np
from ulab import utils
a = bytearray([1, 1, 0, 0, 0, 0, 0, 255])
print('a: ', a)
print()
print('unsigned integers: ', utils.from_uint32_buffer(a))
b = bytearray([1, 1, 0, 0, 0, 0, 0, 255])
print('\nb: ', b)
print()
print('signed integers: ', utils.from_int32_buffer(b))
a: bytearray(b'x01x01x00x00x00x00x00xff')
unsigned integers: array([257.0, 4278190080.000001], dtype=float64)
b: bytearray(b'x01x01x00x00x00x00x00xff')
signed integers: array([257.0, -16777216.0], dtype=float64)
The meaning of count
, and offset
is similar to that in numpy.frombuffer
. count
is the number of floats that will be converted, while offset
would discard the first offset
number of bytes from the buffer before the conversion.
In the example above, repeated calls to either of the functions returns a new ndarray
. You can save RAM by supplying the out
keyword argument with a pre-defined ndarray
of sufficient size, in which case the results will be inserted into the ndarray
. If the dtype
of out
is not float
, a TypeError
exception will be raised.
# code to be run in micropython
from ulab import numpy as np
from ulab import utils
a = np.array([1, 2], dtype=np.float)
b = bytearray([1, 0, 1, 0, 0, 1, 0, 1])
print('b: ', b)
utils.from_uint32_buffer(b, out=a)
print('a: ', a)
b: bytearray(b'x01x00x01x00x00x01x00x01') a: array([65537.0, 16777472.0], dtype=float64)
Finally, since there is no guarantee that the endianness of a particular peripheral device supplying the buffer is the same as that of the microcontroller, from_(u)intbuffer
allows a conversion via the byteswap
keyword argument.
# code to be run in micropython
from ulab import numpy as np
from ulab import utils
a = bytearray([1, 0, 0, 0, 0, 0, 0, 1])
print('a: ', a)
print('buffer without byteswapping: ', utils.from_uint32_buffer(a))
print('buffer with byteswapping: ', utils.from_uint32_buffer(a, byteswap=True))
a: bytearray(b'x01x00x00x00x00x00x00x01') buffer without byteswapping: array([1.0, 16777216.0], dtype=float64) buffer with byteswapping: array([16777216.0, 1.0], dtype=float64)
These two functions are identical to utils.from_int32_buffer
, and utils.from_uint32_buffer
, with the exception that they convert 16-bit integers to floating point ndarray
s.
# code to be run in CPython