NumPy frombuffer()

# byte string behaves like a buffer
buf = b'HelloWorld'

# import numpy
import numpy as np

# load from the buffer
array1 = np.frombuffer(buf, dtype = 'S1')

print(array1)

# Output : [b'H' b'e' b'l' b'l' b'o' b'W' b'o' b'r' b'l' b'd']

frombuffer() Syntax

The syntax of frombuffer() is:

numpy.frombuffer(buffer, dtype=float, count=-1, offset=0, like=None)

frombuffer() Argument

The frombuffer() method takes the following arguments:

• buffer- the buffer to read (buffer_like)
• dtype(optional)- type of output array(dtype)
• count(optional)- number of items to read(int)
• offset(optional)- start reading buffer from this offset(int)
• like(optional)- reference object used for the creation of non-NumPy arrays(array_like)

Note: The default value of count is -1, which means all data in the buffer.

frombuffer() Return Value

The frombuffer() method returns an array from a buffer.

Example 1: Create an Array Using frombuffer()

# byte string behaves like a buffer
buf = b'HelloWorld'

# import numpy
import numpy as np

# load from buffer with element size 2
array1 = np.frombuffer(buf, dtype = 'S2')

print(array1)

# load from buffer with element size 3
array2 = np.frombuffer(buf, dtype = 'S3')

print(array2)

Output

[b'He' b'll' b'oW' b'or' b'ld']
ValueError: buffer size must be a multiple of element size

Here, the length of the buffer is 10. In the case of array1, the size of element is 2 which means it can divide the buffer into 5 elements.

However, in the case of array2, 10 is not a multiple of 3. Thus, the array cannot be created.

Example 2: Use dtype Argument to Specify Data Types

The dtype argument helps specify the required datatype of created numpy arrays.

# byte string behaves like a buffer
buf = b'\x01\x02\x03\x04'

# import numpy
import numpy as np

# load from the buffer as int8
array1 = np.frombuffer(buf, dtype = np.uint8)

print(array1)

# load from the buffer as int16
array2 = np.frombuffer(buf, dtype = np.uint16)

print(array2)

Output

[1 2 3 4]
[ 513 1027]

To understand the output, we need to understand how the buffer works. Since this tutorial is for NumPy and not a buffer, we'll not go too deep. However, you can visit the official Python documentation.

First of all, \x represents the hexadecimal format.

When dtype = np.unit8, each byte in the byte string is interpreted as an 8-bit unsigned integer. Thus, array1 becomes [1 2 3 4].

When dtype = np.unit16, a byte-pair in byte string is interpreted as a 16-bit unsigned integer. Thus, array2 has 2 elements \x01\x02 i.e. 2 * 256 + 1 = 513 and \x03\x04 i.e. 4 * 256 + 3 = 1027 and becomes [513 1027].

Example 3: Use count Argument to Limit the Data to Read

The count argument helps specify the number of items to read from the buffer.

# byte string behaves like a buffer
buf = b'\x01\x02\x03\x04'

# import numpy
import numpy as np

# load the first 2 items from the buffer 
array1 = np.frombuffer(buf, dtype = np.uint8, count = 2)

print(array1)

# load the first 3 items from the buffer
array2 = np.frombuffer(buf, dtype = np.uint8, count = 3)

print(array2)

Output

[1 2]
[1 2 3]

Example 3: Use offset Argument to Specify the Buffer Offset

The offset argument helps specify the number of items to skip before starting to read from the buffer.

# byte string behaves like a buffer
buf = b'\x01\x02\x03\x04'

# import numpy
import numpy as np

# load the first 2 items from the buffer with no offset
array1 = np.frombuffer(buf, dtype = np.uint8, count = 2)

# load 2 items from the buffer after skipping the first item
array2 = np.frombuffer(buf, dtype = np.uint8, count = 2, offset = 1)

# load 2 items from the buffer after skipping the first 2 items
array3 = np.frombuffer(buf, dtype = np.uint8, count = 2, offset = 2)

print(array1)
print(array2)
print(array3)

Output

[1 2]
[2 3]
[3 4]