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 and create a dsp.BinaryFileWriter object. The object writes the header first, followed by the data, to the ex_file.bin file. The data is a noisy sine wave signal. View the data in a time scope.

header = struct('A',[1 2 3 4],'B','x7');
writer = dsp.BinaryFileWriter('ex_file.bin','HeaderStructure',header);
L = 150;
sine = dsp.SineWave('SamplesPerFrame',L);
scopewriter = dsp.TimeScope(1,'YLimits',[-1.5 1.5],'SampleRate',...
    L,'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.

release(writer);

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, its size and data type. The dsp.BinaryFileReader object reads the binary data from ex_file.bin until the end of file is reached. The data is read into a single channel (column) containing multiple frames, where each frame has 300 samples. View the data in a time scope.

headerPrototype = struct('A',[0 0 0 0],'B','-0');

reader = dsp.BinaryFileReader(...
    'ex_file.bin',...
    'HeaderStructure',headerPrototype,...
    'NumChannels',1,'SamplesPerFrame',300);
scopereader = dsp.TimeScope(1,'YLimits',[-1.5 1.5],'SampleRate',...
    L,'TimeSpan',1);
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.

A = [1 2 3 8; 4 5 6 10; 7 8 9 11];
header = struct('A',[1 2],'B','x7');
writer = dsp.BinaryFileWriter('Matdata.bin','HeaderStructure',header);
writer(A);

Release the writer so that the reader can access the data.

release(writer);

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, its size and data type. The dsp.BinaryFileReader object reads the binary file Matdata.bin until the end of file is reached. Specify 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('A',[0 0],'B','-0');
reader = dsp.BinaryFileReader('Matdata.bin','HeaderStructure',header,...
    'NumChannels',4,'SamplesPerFrame',5);
while ~isDone(reader)
    out = reader();
    display(out)
end

out =

     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 specified 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 method.

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 method of the dsp.BinaryFileReader object.

H = readHeader(reader);
fprintf('H.A: ')
fprintf('%d ',H.A);
fprintf('\nH.A datatype: %s\n',class(H.A))
fprintf('H.B: ')
fprintf('%d ',H.B);
fprintf('\nH.B datatype: %s\n',class(H.B))

H.A: 1 2 3 4 
H.A datatype: double
H.B: 1 2 3 4 5 
H.B datatype: single

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);
release(reader);

data =

   1.0000 + 9.0000i   2.0000 +10.0000i
   3.0000 +11.0000i   4.0000 +12.0000i

Alternatively, if you do not specify the data to be complex, the reader reads the data as a SamplesPerFrame-by- NumChannel matrix of real values.

reader.IsDataComplex = false;
data = reader();
display(data);
release(reader);

data =

     1     9
     2    10

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 a 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.

release(writer);

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 . If you know the signedness, word length, and fraction length of the fixed-point data, you can reconstruct the fi data using . 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)

ans =

  logical

   1

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.

release(writer);

Read the uint8 Data

Specify 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.

strcmp(data,charData.')

ans =

  logical

   1

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 =

  1.0e-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 =

     1
     2
     3
     4
     5
     6
     7
     8

y matches the original data.