dsp.BinaryFileReader - Read data from binary file - MATLAB (original) (raw)
Read data from binary file
Description
The dsp.BinaryFileReader
System object™ reads multichannel signal data from a binary file. If the header is not empty, then the header precedes the signal data. The System object specifies the prototype of the header, and the type, size, and complexity of the data. The first time you read the file, the reader reads the header, followed by the data. On subsequent calls, the reader reads the remaining data. Once the end of file is reached, the reader returns zeros of the specified data type, size, and complexity. The reader can read signal data from a binary file that is not created by the dsp.BinaryFileWriter System object.
The object accepts floating-point data or integer data. To read character data and fixed-point data, see the Write and Read Character Data and Write and Read Fixed-Point Data examples. The input data can be real or complex. When the data is complex, the object reads the data as interleaved real and imaginary components. For an example, see Read Complex Data. The reader assumes the default endianness of the host machine. To change the endianness, you can use the swapbytes function. For an example, see Change Endianness of Data.
To read data from a binary file:
- Create the
dsp.BinaryFileReader
object and set its properties. - Call the object with arguments, as if it were a function.
To learn more about how System objects work, see What Are System Objects?
Creation
Syntax
Description
`reader` = dsp.BinaryFileReader
creates a binary file reader object, reader
, using the default properties.
`reader` = dsp.BinaryFileReader(`fname`)
sets the Filename
property to fname
.
reader = dsp.BinaryFileReader(`fname`,`Name=Value`)
with Filename
set to fname
, sets properties using one or more name-value arguments. For example, to set the number of samples per output frame as 1536, setSamplesPerFrame
to 1536.
Properties
Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and therelease function unlocks them.
If a property is tunable, you can change its value at any time.
For more information on changing property values, seeSystem Design in MATLAB Using System Objects.
Name of the file from which the object reads the data, specified as a character vector. If the file is not on the MATLAB® path, then specify the full path for the file.
The Filename
property is tunable in generated code, that is, you can pass the name of the binary file as an input while running the code generated from this object. For an example, see Tunable Binary File Name in Generated Code. (since R2025a)
Number of samples per output frame, specified as a positive integer.SamplesPerFrame
specifies the number of rows of the output matrix that the object returns. The size of the data isSamplesPerFrame
-by-NumChannels
. Once the end of file is reached, the reader returns zeros of the specified data type, size, and complexity.
Number of channels, specified as a positive integer.NumChannels
specifies the number of columns of the output matrix that the object returns. This property defines the number of consecutive interleaved data samples stored in the file for each time instant. The size of the data isSamplesPerFrame
-by-NumChannels
. Once the end of file is reached, if the output matrix is not full, the object fills the matrix with zeros to make it a full-sized matrix.
Type of data in file, specified as a character vector. This property defines the data type of the matrix returned by the object algorithm.
Option to specify data complexity, specified as false
ortrue
. When this property is set to true
, the reader treats the data as complex. The object reads the data as interleaved real and imaginary components. Consider a reader object configured to read the data as a 2-by-2 matrix. The object reads [1 5 2 6 3 7 4 8]
as [1 2; 3 4]+1j*[5 6; 7 8]
. If this property is set to false
, the same object reads the data as [1 5; 2 6]
.
Usage
Syntax
Description
[data](#d126e244439) = reader()
reads data from the binary file in a row-major format. The data type, size, and complexity of the data are determined by the properties of the reader object. Once the end of file is reached, the output contains zeros of the specified data type, size, and complexity.
Output Arguments
Data read by the binary file reader, returned as a vector or a matrix. The size of the data is given bySamplesPerFrame
-by-NumChannels
, whereSamplesPerFrame
and NumChannels
are the properties of the dsp.BinaryFileReader
object.
Object Functions
To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj
, use this syntax:
step | Run System object algorithm |
---|---|
release | Release resources and allow changes to System object property values and input characteristics |
reset | Reset internal states of System object |
Examples
Create a binary file with a custom header using the dsp.BinaryFileWriter
System object. Write data to this file. Read the header and data using the dsp.BinaryFileReader
System object.
Write the Data
Specify the file header as a structure with the following fields:
DataType
set todouble
.Complexity
set tofalse
.FrameSize
(number of rows in the data matrix) set to 150.NumChannels
(number of columns in the data matrix) set to 1.
Create a dsp.BinaryFileWriter
object using this header. The object writes the header first, followed by the data, to ex_file.bin
. The data is a noisy sine wave signal. View the data in a time scope.
L = 150; header = struct(DataType="double",... Complexity=false,... FrameSize=L,... NumChannels=1); writer = dsp.BinaryFileWriter("ex_file.bin",... HeaderStructure=header);
sine = dsp.SineWave(SamplesPerFrame=L); scopewriter = timescope(YLimits=[-1.5 1.5],... SampleRate=sine.SampleRate,... TimeSpanSource="Property",... TimeSpan=1);
for i = 1:1000 data = sine() + 0.01*randn(L,1); writer(data); scopewriter(data) end
Release the writer so that the reader can access the data from this file.
Read the Data
Read the data from the binary file, ex_file.bin
, using the dsp.BinaryFileReader
object. The file contains the header data followed by the actual data. The object reads the binary data until the end of file is reached. Specify the header to the reader using the HeaderStructure
property of the reader object.
If the exact header is not known on the reader side, you must at least specify the prototype of the header. That is, the number of fields, and the data type, size, and complexity of each field in the prototype must match with the header data written to the binary file. When the readHeader
function reads the data from the binary file, the function extracts the header information based on how the fields are specified in the header prototype. For example, a header field set to 'double'
on the writer side can be specified as any string of 6 characters on the reader side. The readHeader
function reads this field as a string of 6 characters from the binary file, which matches with 'double'
.
headerPrototype = struct(DataType="datype",... Complexity=false,... FrameSize=1,... NumChannels=10); reader = dsp.BinaryFileReader(... "ex_file.bin",... HeaderStructure=headerPrototype); headerReader = readHeader(reader)
headerReader =
struct with fields:
DataType: 'double'
Complexity: 0
FrameSize: 150
NumChannels: 1
The header data extracted by the readHeader
function is assigned to the corresponding properties of the reader
object.
reader.IsDataComplex = headerReader.Complexity; reader.DataType = headerReader.DataType; reader.NumChannels = headerReader.NumChannels; reader.SamplesPerFrame = headerReader.FrameSize;
Initialize a scope on the reader side to view the extracted binary file data.
scopereader = timescope(YLimits=[-1.5 1.5],... SampleRate=sine.SampleRate,... TimeSpanSource="Property",... TimeSpan=1);
The data is read into a single channel (column) containing multiple frames, where each frame has 150 samples. View the data in a time scope.
while ~isDone(reader) out = reader(); scopereader(out) end release(reader); release(scopereader);
Set the reader to read data in frames of size 300. Verify that the data read matches the data written to the file.
reader.SamplesPerFrame = 300; while ~isDone(reader) out = reader(); scopereader(out) end release(reader);
Even when the reader reads data with a different frame size, the output in both time scopes matches exactly.
Use a dsp.BinaryFileReader
System object™ to read data from a binary file in a row-major format.
Write the Data
Write the matrix A
to the binary file Matdata.bin
using a dsp.BinaryFileWriter
object. The object writes the specified header followed by the data.
The header has the following format:
DataType
set todouble
.Complexity
set tofalse
.FrameSize
(number of rows in the data matrix) set to 3.NumChannels
(number of columns in the data matrix) set to 4.
A = [1 2 3 8; 4 5 6 10; 7 8 9 11]; header = struct(DataType="double",... Complexity=false,... FrameSize=3,... NumChannels=4); writer = dsp.BinaryFileWriter("Matdata.bin",... HeaderStructure=header); writer(A);
Release the writer so that the reader can access the data.
Read the Data
Specify the header using the HeaderStructure
property of the reader object. If the exact header is not known, you must at least specify the prototype of the header. That is, the number of fields, and the data type, size, and complexity of each field in the prototype must match with the header data written to the binary file. The dsp.BinaryFileReader
object reads the binary file Matdata.bin
until the end of file is reached. Configure the System object to read the data into 4 channels, with each channel containing 5 samples. Each loop of the iteration reads a channel (or frame) of data.
headerPrototype = struct(DataType="double",... Complexity=false,... FrameSize=5,... NumChannels=4); reader = dsp.BinaryFileReader('Matdata.bin',... HeaderStructure=headerPrototype,... NumChannels=4,... SamplesPerFrame=5); while ~isDone(reader) out = reader(); display(out) end
out = 5×4
1 2 3 8
4 5 6 10
7 8 9 11
0 0 0 0
0 0 0 0
Each frame of out
contains frames of the matrix A
, followed by zeros to complete the frame. The original matrix A
contains 4 channels with 3 samples in each channel. The reader is configured to read data into 4 channels, with each channel containing 5 samples. Because there are not enough samples to complete the frame, the reader object appends zeros at the end of each frame.
Read the header data from a binary file using the readHeader
function.
Write a header, followed by the data to a binary file named myfile.dat
. The header is a 1-by-4 matrix of double precision values, followed by a 5-by-1 vector of single-precision values. The data is a sequence of 1000 double-precision values.
fid = fopen("myfile.dat","w"); fwrite(fid,[1 2 3 4],"double"); fwrite(fid,single((1:5).'),"single"); fwrite(fid,(1:1000).',"double"); fclose(fid);
Read the header using a dsp.BinaryFileReader
object. Specify the expected header structure. This structure specifies only the format of the expected binary file header and does not contain the exact values.
reader = dsp.BinaryFileReader("myfile.dat"); s = struct("A",zeros(1,4),"B",ones(5,1,"single")); reader.HeaderStructure = s;
Read the header using the readHeader
function.
H = readHeader(reader); fprintf("H.A: ")
fprintf("\nH.A datatype: %s\n",class(H.A))
fprintf("\nH.B datatype: %s\n",class(H.B))
Read complex data from a binary file using the dsp.BinaryFileReader
object.
Write a sequence of numbers to a binary file named myfile.dat
. There is no header. The data is a 2-by-4 matrix of double-precision values. fwrite
writes the data in a column-major format. That is, the 2-by-4 matrix [1 2 3 4; 9 10 11 12]
is written as [1 9 2 10 3 11 4 12]
in the binary file.
fid = fopen("myfile.dat","w"); fwrite(fid,[1 2 3 4; 9 10 11 12],"double"); fclose(fid);
Specify the data to be complex using the IsDataComplex
property. The object reads the data as interleaved real and imaginary components. The SamplesPerFrame
and NumChannel
properties specify the number of rows and columns of the output data. The header structure is specified as empty.
reader = dsp.BinaryFileReader("myfile.dat",SamplesPerFrame=2,... NumChannels=2,IsDataComplex=true); s = struct([]); reader.HeaderStructure = s; data = reader(); display(data);
data = 2×2 complex
1.0000 + 9.0000i 2.0000 +10.0000i 3.0000 +11.0000i 4.0000 +12.0000i
Alternatively, if you do not specify the data as complex, the reader reads the data as a SamplesPerFrame
-by- NumChannel
matrix of real values.
reader.IsDataComplex = false; data = reader(); display(data);
The dsp.BinaryFileWriter
and dsp.BinaryFileReader
System objects do not support writing and reading fixed-point data. As a workaround, you can write the stored integer portion of the fi
data, read the data, and use this value to reconstruct the fi
data.
Write the Fixed-Point Data
Create an fi
object to represent 100 signed random numbers with a word length of 14 and a fraction length of 12. Write the stored integer portion of the fi
object to the data file myFile.dat
. The built-in data type is int16
, which can be computed using class(storeIntData)
.
data = randn(100,1); fiDataWriter = fi(data,1,14,12); storeIntData = storedInteger(fiDataWriter);
writer = dsp.BinaryFileWriter("myFile.dat"); writer(storeIntData);
Release the writer so that the reader can access the data.
Read the Fixed-Point Data
Specify the reader to read the stored integer data as int16
data with 100 samples per data frame. The real-world value of the fixed-point number can be represented using 2(-fractionLength)(storedInteger). If you know the signedness, word length, and fraction length of the fixed-point data, you can reconstruct the fi
data using fi(realValue,signedness,wordLength,fractionLength). In this example, the data is signed with a word length of 14 and a fraction length of 12.
reader = dsp.BinaryFileReader(Filename="myFile.dat",... SamplesPerFrame=100,... DataType="int16"); data = reader(); fractionLength = 12; wordLength = 14; realValue = 2^(-fractionLength)*double(data);
fiDataReader = fi(realValue,1,... wordLength,fractionLength);
Verify that the writer data is the same as the reader data.
isequal(fiDataWriter,fiDataReader)
The dsp.BinaryFileWriter
and dsp.BinaryFileReader
System objects do not support writing and reading characters. As a workaround, cast character data to one of the built-in data types and write the integer data. After the reader reads the data, convert the data to a character using the char
function.
Write the Character Data
Cast a character into uint8
using the cast
function. Write the cast data to the data file myFile.dat
.
data = 'binary_file'; castData = cast(data,'uint8'); writer = dsp.BinaryFileWriter('myFile.dat'); writer(castData);
Release the writer so that the reader can access the data.
Read the uint8
Data
Configure the reader to read the cast data as uint8
data.
reader = dsp.BinaryFileReader('myFile.dat',... DataType='uint8',... SamplesPerFrame=11); readerData = reader(); charData = char(readerData);
Verify that the writer data is the same as the reader data. By default, the reader returns the data in a column-major format.
By default, the dsp.BinaryFileReader
System object™ uses the endianness of the host machine. To change the endianness, such as when the host machine that writes the data does not have the same endianness as the host machine that reads the data, use the swapbytes
function.
Write a numeric array into myfile.dat
in big endian format. Read the data using the dsp.BinaryFileReader
object. The reader object reads the data in little endian format.
fid = fopen("myfile.dat","w","b"); fwrite(fid,[1 2 3 4 5 6 7 8],"double"); fclose(fid); reader = dsp.BinaryFileReader("myfile.dat",SamplesPerFrame=8); x = reader(); display(x);
x = 8×1 10-318 ×
0.3039
0.0003
0.0104
0.0206
0.0256
0.0307
0.0357
0.0408
x
does not match the original data. Change the endianness of x
using the swapbytes
function.
y = swapbytes(x); display(y);
y
matches the original data.
Since R2025a
The writeBinaryFile
function writes character data to a file, reads data from the same file, and compares the written data with the read data to verify if they are the same. The function accepts the filename as the input.
function writeBinaryFile(filename)
data = 'test_data'; castData = cast(data,'uint8'); writer = dsp.BinaryFileWriter(Filename=filename); writer(castData); release(writer); reader = dsp.BinaryFileReader(Filename=filename,... DataType='uint8',... SamplesPerFrame=9); readerData = reader(); charData = char(readerData); strcmp(data,charData.')
end
For generating code, specify the filename to be a variable-length character vector of a maximum length of 500.
filename = coder.typeof('a',[1 500],[0 1]);
Generate a MEX file using the codegen
function.
codegen writeBinaryFile -args {filename}
Code generation successful.
Run the MEX file by specifying the filename as an input argument. In this example, the file name is 'myfile.dat'
. You can specify a different filename whenever you run the writeBinaryFile_mex
file.
writeBinaryFile_mex('myfile.dat')
Extended Capabilities
Version History
Introduced in R2016b
The Filename
property of the dsp.BinaryFileReader
object is tunable in generated code, that is, you can pass the name of the binary file as an input while running the code generated from this object. For an example, see Tunable Binary File Name in Generated Code.