Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

dsp.BinaryFileWriter System object

Write data to binary files

Description

The dsp.BinaryFileWriter System object™ writes multichannel signal data to a binary file. If the header is not empty, then the header precedes the signal data. The object specifies the file name and the structure of the header. The first time you write to the file, the object writes the header, followed by the data. On subsequent calls, the object writes the remaining data. If the header is empty, then no header is written.

The object can write floating-point data and integer data. To write character data and fixed-point data, see Write and Read Character Data and Write and Read Fixed-Point Data. The input data can be real or complex. When the data is complex, the object writes the data as interleaved real and imaginary components. For an example, see Write and Read Fixed-Point Data. The writer assumes the default endianness of the host machine. To change the endianness, you can use the swapbytes function. For an example, see Change the Endianness of the Data Before Writing the Data .

The object writes the data in row-major format. For example if the input array is [1 2 4 5; 8 7 9 2], the object writes the data as [1 2 4 5 8 7 9 2].

The object supports C and C++ code generation.

To write data to a binary file:

  1. Create a dsp.BinaryFileWriter object and set the properties of the object.

  2. Call step to write to the binary file. In the first call to step, the object writes the header before the data. In subsequent calls, the object writes the data to the end of the file.

Note

Alternatively, instead of using the step method to perform the operation defined by the System object, you can call the object with arguments, as if it were a function. For example, y = step(obj) and y = obj() perform equivalent operations.

Construction

writer = dsp.BinaryFileWriter creates a binary file writer object, writer, using the default properties.

writer = dsp.BinaryFileWriter(fname) sets the Filename property to fname.

writer = dsp.BinaryFileWriter(fname,Name,Value, ...) with Filename set to fname, and each property Name set to the specified Value. Unspecified properties have default values.

Example:

writer = dsp.BinaryFileWriter('myFilename.bin','HeaderStructure',...
struct('field1',1:10,'field2',single(1)));

Properties

expand all

Name of the file to which the object writes the data, specified as a character vector. You must specify the full path for the file.

Header to write at the beginning of the file, specified as a structure. The structure can have an arbitrary number of fields. Each field of the structure must be a real matrix of a built-in type. For example, if HeaderStructure is set to struct('field1',1:10,'field2',single(1)), the object writes a header formed by 10 double-precision values, (1:10), followed by one single precision value, single(1). If you do not specify a header, the object sets this property to an empty structure, struct([]).

Methods

resetReset internal states of System object
stepWrite data to the binary file
Common to All System Objects
clone

Create System object with same property values

getNumInputs

Expected number of inputs to a System object

getNumOutputs

Expected number of outputs of a System object

isLocked

Check locked states of a System object (logical)

release

Allow System object property value changes

Examples

expand all

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.

This example shows how the dsp.BinaryFileWriter object writes complex data.

Create a dsp.BinaryFileWriter object which writes to a file named 'myfile.dat'. There is no header. The data is complex.

writer = dsp.BinaryFileWriter('myfile.dat');
data = [1 2 3 4]+1i*[5 6 7 8];
writer(data);
release(writer);

Read the data using the dsp.BinaryFileReader System object™. To view data in the format it is written to the file, set the IsDataComplex property to false. The reader object reads the data as a sequence of numbers in a row major format. Set SamplesPerFrame to 1 and NumChannels to 8.

reader = dsp.BinaryFileReader('myfile.dat','SamplesPerFrame',1,...
    'NumChannels',8);
s = struct([]);
reader.HeaderStructure = s;
dataRead = reader();

You can see that the real and imaginary components of the original data are sample interleaved.

display(dataRead);
dataRead = 

     1     5     2     6     3     7     4     8

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.BinaryFileWriter System object™ uses the endianness of the host machine. To change the endianness, use the swapbytes function.

Write a numeric array into myfile.dat using the dsp.BinaryFileWriter object. Before writing the data, change the endianness of the data using the swapbytes function.

data = [1 2 3 4 2 2];
swapData = swapbytes(data);
writer = dsp.BinaryFileWriter('myfile.dat');
writer(swapData);

Extended Capabilities

Introduced in R2016b

Was this topic helpful?