NeuralEngine
A Game Engine with embeded Machine Learning algorithms based on Gaussian Processes.
NeuralEngine::MatlabIO Class Reference

Matlab Mat file parser for C++ OpenCV. More...

#include <NeMatlabIO.h>

Collaboration diagram for NeuralEngine::MatlabIO:

Public Member Functions

 MatlabIO ()
 Default constructor. More...
 
virtual ~MatlabIO ()
 Destructor. More...
 
std::string Filename (void)
 Gets the filename. More...
 
bool Open (std::string filename, std::string mode)
 Open a filestream for reading or writing. More...
 
bool Close (void)
 Close the filestream and release all resources. More...
 
std::vector< MatlabIOContainerRead (void)
 Read all variables from a file. More...
 
void Whos (std::vector< MatlabIOContainer > variables) const
 Print a formatted list of the contents of a file. More...
 
template<class T >
Find (std::vector< MatlabIOContainer > &variables, std::string name) const
 
MatlabIOContainer Find (std::vector< MatlabIOContainer > &variables, std::string name) const
 
template<class T >
bool TypeEquals (std::vector< MatlabIOContainer > &variables, std::string name) const
 
template<typename T >
bool IsPrimitiveType (void) const
 

Private Member Functions

void GetHeader (void)
 Gets the .Mat file header information. More...
 
bool HasVariable (void)
 
MatlabIOContainer ConstructString (std::vector< char > &name, std::vector< uint32_t > &dims, std::vector< char > &real)
 Constructs a string from an extracted set of fields. More...
 
MatlabIOContainer ConstructSparse (std::vector< char > &name, std::vector< uint32_t > &dims, std::vector< char > &real, std::vector< char > &imag)
 Construct a sparse matrix. More...
 
MatlabIOContainer ConstructCell (std::vector< char > &name, std::vector< uint32_t > &dims, std::vector< char > &real)
 Constructs a cell array. More...
 
MatlabIOContainer ConstructStruct (std::vector< char > &name, std::vector< uint32_t > &dims, std::vector< char > &real)
 Constructs a structure. More...
 
const char * ReadVariableTag (uint32_t &data_type, uint32_t &dbytes, uint32_t &wbytes, const char *data)
 Interpret the variable header information. More...
 
MatlabIOContainer CollateMatrixFields (uint32_t data_type, uint32_t nbytes, std::vector< char > data)
 Interpret all fields of a matrix. More...
 
std::vector< char > UncompressVariable (uint32_t &data_type, uint32_t &dbytes, uint32_t &wbytes, const std::vector< char > &data)
 Uncompress a variable. More...
 
MatlabIOContainer ReadVariable (uint32_t data_type, uint32_t nbytes, const std::vector< char > &data)
 Interpret a variable from a binary block of data. More...
 
MatlabIOContainer ReadBlock (void)
 Reads a block of data from the file being parsed. More...
 
void TransposeMat (const cv::Mat &src, cv::Mat &dst)
 Transpose a multi-channel matrix. More...
 
template<class T1 , class T2 >
std::vector< T2 > ConvertPrimitiveType (const std::vector< char > &in)
 Convert the type of a variable. More...
 
template<typename T >
Product (const std::vector< T > &vec)
 Product of the elements of a vector. More...
 
template<class T >
MatlabIOContainer ConstructMatrix (std::vector< char > &name, std::vector< uint32_t > &dims, std::vector< char > &real, std::vector< char > &imag, uint32_t stor_type)
 Construct a matrix from an extracted set of fields. More...
 

Private Attributes

char header_ [HEADER_LENGTH+1]
 
char subsys_ [SUBSYS_LENGTH+1]
 
char endian_ [ENDIAN_LENGTH+1]
 
int16_t version_
 
bool byte_swap_
 
int bytes_read_
 
std::string filename_
 
EFStream fid_
 

Static Private Attributes

static const int HEADER_LENGTH = 116
 
static const int SUBSYS_LENGTH = 8
 
static const int ENDIAN_LENGTH = 2
 

Detailed Description

Matlab Mat file parser for C++ OpenCV.


This class provides the capacity to read and write Mat files produced by Matlab. The OpenCV cv::Mat class is used for the
internal storage of matrices. The class also provides methods
to inspect the contents of a Mat-file, read all variables, or
read a single variable by name.

HmetalT, 02/08/2019.

Definition at line 45 of file NeMatlabIO.h.

Constructor & Destructor Documentation

◆ MatlabIO()

NeuralEngine::MatlabIO::MatlabIO ( )
inline

Default constructor.

Hmetal T, 03/08/2019.

Definition at line 55 of file NeMatlabIO.h.

◆ ~MatlabIO()

virtual NeuralEngine::MatlabIO::~MatlabIO ( )
inlinevirtual

Destructor.

Hmetal T, 03/08/2019.

Definition at line 62 of file NeMatlabIO.h.

Member Function Documentation

◆ Filename()

std::string NeuralEngine::MatlabIO::Filename ( void  )
inline

Gets the filename.

Hmetal T, 03/08/2019.

Returns
A std::string.

Definition at line 71 of file NeMatlabIO.h.

◆ Open()

bool NeuralEngine::MatlabIO::Open ( std::string  filename,
std::string  mode 
)

Open a filestream for reading or writing.

Hmetal T, 03/08/2019.

Parameters
filenameFilename the full name and filepath of the file.
modeMode either "r" for reading or "w" for writing.
Returns
true if the file open succeeded, false otherwise.

◆ Close()

bool NeuralEngine::MatlabIO::Close ( void  )

Close the filestream and release all resources.

Hmetal T, 03/08/2019.

Returns
true if the filestream was successfully closed, false otherwise.Even in the case of failure, the filestream will no longer point to a valid object.

◆ Read()

std::vector< MatlabIOContainer > NeuralEngine::MatlabIO::Read ( void  )

Read all variables from a file.


Reads every variable encountered when parsing a valid Matlab .Mat file. If any of the variables is a function pointer, or other Matlab specific object, it will be passed. Most integral types will be parsed successfully. Matlab matrices will be converted to OpenCV matrices of the same type. Note: Matlab stores images in RGB format whereas OpenCV stores images in BGR format, so if displaying a parsed image using cv::imshow(), the colours will be inverted.

Hmetal T, 03/08/2019.

Returns
A std::vector<MatlabIOContainer>

◆ Whos()

void NeuralEngine::MatlabIO::Whos ( std::vector< MatlabIOContainer variables) const

Print a formatted list of the contents of a file.


Similar to the 'whos' function in matlab, this function prints to stdout a list of variables and their C++ datatypes stored in the associated .Mat file

Hmetal T, 03/08/2019.

Parameters
variablesThe variables read from the .Mat file using the read() function.

◆ Find() [1/2]

template<class T >
T NeuralEngine::MatlabIO::Find ( std::vector< MatlabIOContainer > &  variables,
std::string  name 
) const
inline

Definition at line 132 of file NeMatlabIO.h.

◆ Find() [2/2]

MatlabIOContainer NeuralEngine::MatlabIO::Find ( std::vector< MatlabIOContainer > &  variables,
std::string  name 
) const
inline

Definition at line 147 of file NeMatlabIO.h.

◆ TypeEquals()

template<class T >
bool NeuralEngine::MatlabIO::TypeEquals ( std::vector< MatlabIOContainer > &  variables,
std::string  name 
) const
inline

Definition at line 156 of file NeMatlabIO.h.

◆ IsPrimitiveType()

template<typename T >
bool NeuralEngine::MatlabIO::IsPrimitiveType ( void  ) const
inline

Definition at line 165 of file NeMatlabIO.h.

◆ GetHeader()

void NeuralEngine::MatlabIO::GetHeader ( void  )
private

Gets the .Mat file header information.


The fields read are: header_ the matlab header as a human readable string,
subsys_ subsystem specific information,
version_ the .Mat file version (5 or 73),
endian_ the bye ordering of the .Mat file. If the byte ordering
needs reversal, this is automatically handled by esfstream.

Hmetal T, 03/08/2019.

◆ HasVariable()

bool NeuralEngine::MatlabIO::HasVariable ( void  )
inlineprivate

Definition at line 198 of file NeMatlabIO.h.

◆ ConstructString()

MatlabIOContainer NeuralEngine::MatlabIO::ConstructString ( std::vector< char > &  name,
std::vector< uint32_t > &  dims,
std::vector< char > &  real 
)
private

Constructs a string from an extracted set of fields.


If the data is of type char, the data is stored as a string rather than a matrix. The dimensionality is ignored (the data is linearized)

Hmetal T, 03/08/2019.

Parameters
name[in,out] The variable name.
dims[in,out] The variable dimensionality (ignored).
real[in,out] The string data.
Returns
The wrapped string.

◆ ConstructSparse()

MatlabIOContainer NeuralEngine::MatlabIO::ConstructSparse ( std::vector< char > &  name,
std::vector< uint32_t > &  dims,
std::vector< char > &  real,
std::vector< char > &  imag 
)
private

Construct a sparse matrix.

Hmetal T, 03/08/2019.

Parameters
name[in,out] The name.
dims[in,out] The dims.
real[in,out] The real.
imag[in,out] The imag.
Returns
A MatlabIOContainer.

◆ ConstructCell()

MatlabIOContainer NeuralEngine::MatlabIO::ConstructCell ( std::vector< char > &  name,
std::vector< uint32_t > &  dims,
std::vector< char > &  real 
)
private

Constructs a cell array.


If the variable is of type MAT_CELL, construct a cell array. This is done by iteratively calling collateMatrixFields() on each element of the cell, and
storing the result in a vector<MatlabIOContainer>.
Cell fields may not have a name, but are still required to have a name tag. In
this case, placeholder names are substituted. The dimensionality of the cell
array is ignored, and the size is linearized in column major format.

Hmetal T, 03/08/2019.

Parameters
name[in,out] The variable name.
dims[in,out] The dimesionality of the cell array (ignored).
real[in,out] The real part.
Returns
The wrapped cell array.

◆ ConstructStruct()

MatlabIOContainer NeuralEngine::MatlabIO::ConstructStruct ( std::vector< char > &  name,
std::vector< uint32_t > &  dims,
std::vector< char > &  real 
)
private

Constructs a structure.

Hmetal T, 03/08/2019.

Parameters
name[in,out] The name.
dims[in,out] The dims.
real[in,out] The real.
Returns
A MatlabIOContainer.

◆ ReadVariableTag()

const char * NeuralEngine::MatlabIO::ReadVariableTag ( uint32_t &  data_type,
uint32_t &  dbytes,
uint32_t &  wbytes,
const char *  data 
)
private

Interpret the variable header information.


Given a binary data blob, determine the data type and number of bytes that constitute the data blob. This internally handles whether the
header is in long or short format.

Hmetal T, 03/08/2019.

Parameters
data_type[in,out] The returned data type.
dbytes[in,out] The returned number of bytes that constitute the data blob.
wbytes[in,out] The whole number of bytes that include the header size, the size of the data and any padding to 64 - bit boundaries.This is equivalent to the entire number of bytes effectively used by a variable.
dataThe input binary blob.
Returns
A pointer to the beginning of the data segment of the binary blob.

◆ CollateMatrixFields()

MatlabIOContainer NeuralEngine::MatlabIO::CollateMatrixFields ( uint32_t  data_type,
uint32_t  nbytes,
std::vector< char >  data 
)
private

Interpret all fields of a matrix.


collateMatrixFields takes a binary blob of data and strips out the matrix fields. These fields necessarily include: the variable dimensionality, the variable name
and the real part of the variable data. It optionally includes the imaginary part
of the variable data if that exists too. The extracted fields are used to either
construct a matrix, cell array or struct, or a scalar in the case where the variable
dimensionality is (1,1)

Hmetal T, 03/08/2019.

Parameters
data_typeThe type of the data stored in the binary blob.
nbytesThe number of bytes that constitute the binary blob.
dataThe binary blob.
Returns
The variable (matrix, struct, cell, scalar) wrapped in a container.

◆ UncompressVariable()

std::vector< char > NeuralEngine::MatlabIO::UncompressVariable ( uint32_t &  data_type,
uint32_t &  dbytes,
uint32_t &  wbytes,
const std::vector< char > &  data 
)
private

Uncompress a variable.


If the data type of a variable is MAT_COMPRESSED, then the binary data blob has been compressed using zlib compression. This function uncompresses the blob,
then calls readVariable() to interpret the actual data

Hmetal T, 03/08/2019.

Parameters
data_type[in,out] The type of the data stored in the binary blob.
dbytes[in,out] The number of bytes that constitue the binary blob.
wbytes[in,out] The whole number of bytes that consistute the header, the binary blob, and any padding to 64 - bit boundaries.
dataThe binary blob.
Returns
The binary blob, uncompressed

◆ ReadVariable()

MatlabIOContainer NeuralEngine::MatlabIO::ReadVariable ( uint32_t  data_type,
uint32_t  nbytes,
const std::vector< char > &  data 
)
private

Interpret a variable from a binary block of data.


This function may be called recursively when either uncompressing data or interpreting fields of a struct or cell array

Hmetal T, 03/08/2019.

Parameters
data_typeThe type of the data stored in the binary blob.
nbytesThe number of bytes that constitute the binary blob.
dataThe binary blob.
Returns
An interpreted variable.

◆ ReadBlock()

MatlabIOContainer NeuralEngine::MatlabIO::ReadBlock ( void  )
private

Reads a block of data from the file being parsed.


This function attempts to read an entire variable from the file being parsed. The data block is then encapsulated in a vector and passed onto readVariable()
for interpretation. This design means that the file is touched a minimal number
of times, and later manipulation of the data can make use of automatic memory
management, reference counting, etc.

Hmetal T, 03/08/2019.

Returns
The block of data interpreted as a variable and stored in a generic container.

◆ TransposeMat()

void NeuralEngine::MatlabIO::TransposeMat ( const cv::Mat &  src,
cv::Mat &  dst 
)
private

Transpose a multi-channel matrix.


The OpenCV builtin transpose method cannot tranpose multi-dimensional matrices. This function provides that capability by splitting the matrix
into a vector of its channels, tranposing each channel, then merging
the result back into a single multi-channel matrix

Hmetal T, 03/08/2019.

Parameters
srcThe input matrix.
dst[in,out] The output matrix, where dst(i,j,k) == src(j,i,k).
Here is the caller graph for this function:

◆ ConvertPrimitiveType()

template<class T1 , class T2 >
std::vector< T2 > NeuralEngine::MatlabIO::ConvertPrimitiveType ( const std::vector< char > &  in)
inlineprivate

Convert the type of a variable.


Given a vector of type char, interpret the data as an vector of type T1, and convert it to a vector of type
T2.

HmetalT, 03/08/2019.

Parameters
inThe input char vector.
Returns
The same data, reinterpreted as type T2 through storage type T1.

Definition at line 451 of file NeMatlabIO.h.

◆ Product()

template<typename T >
T NeuralEngine::MatlabIO::Product ( const std::vector< T > &  vec)
inlineprivate

Product of the elements of a vector.


The function is useful for calculating the total number of elements in an array given a vector of dims.

Hmetal T, 03/08/2019.

Parameters
vecThe input vector.
Returns
The product of elements in the input.

Definition at line 472 of file NeMatlabIO.h.

◆ ConstructMatrix()

template<class T >
MatlabIOContainer NeuralEngine::MatlabIO::ConstructMatrix ( std::vector< char > &  name,
std::vector< uint32_t > &  dims,
std::vector< char > &  real,
std::vector< char > &  imag,
uint32_t  stor_type 
)
inlineprivate

Construct a matrix from an extracted set of fields.


Given the variable size, name, data and data type, construct a matrix. Note that Matlab may store variables in a different data type to the actual variable data type (T) to save space. For example matrix a = [1 2 3 4 5]; in Matlab will intrinsically be of type double (everything is unless otherwise explicitly stated) but could be stored as a uint8_t to save space. The type of the variable returned should necessarily be double, since it's impossible to know at compile time which data types Matlab has decided to store a set of variables in.

Hmetal T, 03/08/2019.

Parameters
name[in,out] The variable name.
dims[in,out] The variable dimensionality (i, j, k, ...).
real[in,out] The real part.
imag[in,out] The imaginary part (imag.size() == 0 if the data is real).
stor_typeThe storage type of the value.
Returns
The wrapped matrix.

Definition at line 480 of file NeMatlabIO.h.

Here is the call graph for this function:

Member Data Documentation

◆ HEADER_LENGTH

const int NeuralEngine::MatlabIO::HEADER_LENGTH = 116
staticprivate

Definition at line 437 of file NeMatlabIO.h.

◆ SUBSYS_LENGTH

const int NeuralEngine::MatlabIO::SUBSYS_LENGTH = 8
staticprivate

Definition at line 438 of file NeMatlabIO.h.

◆ ENDIAN_LENGTH

const int NeuralEngine::MatlabIO::ENDIAN_LENGTH = 2
staticprivate

Definition at line 439 of file NeMatlabIO.h.

◆ header_

char NeuralEngine::MatlabIO::header_[HEADER_LENGTH+1]
private

Definition at line 440 of file NeMatlabIO.h.

◆ subsys_

char NeuralEngine::MatlabIO::subsys_[SUBSYS_LENGTH+1]
private

Definition at line 441 of file NeMatlabIO.h.

◆ endian_

char NeuralEngine::MatlabIO::endian_[ENDIAN_LENGTH+1]
private

Definition at line 442 of file NeMatlabIO.h.

◆ version_

int16_t NeuralEngine::MatlabIO::version_
private

Definition at line 443 of file NeMatlabIO.h.

◆ byte_swap_

bool NeuralEngine::MatlabIO::byte_swap_
private

Definition at line 444 of file NeMatlabIO.h.

◆ bytes_read_

int NeuralEngine::MatlabIO::bytes_read_
private

Definition at line 445 of file NeMatlabIO.h.

◆ filename_

std::string NeuralEngine::MatlabIO::filename_
private

Definition at line 446 of file NeMatlabIO.h.

◆ fid_

EFStream NeuralEngine::MatlabIO::fid_
private

Definition at line 447 of file NeMatlabIO.h.


The documentation for this class was generated from the following file: