NeuralEngine A Game Engine with embeded Machine Learning algorithms based on Gaussian Processes. |

Public Member Functions | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
NeuralEngine::MatlabIO Class Reference

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

`#include <NeMatlabIO.h>`

Collaboration diagram for NeuralEngine::MatlabIO:
[legend]

## 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< MatlabIOContainer > | Read (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 >
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 >
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 | ( |  | ) |
| inline virtual

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

  filename | Filename the full name and filepath of the file.
  mode | Mode 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

  variables | The 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 |  | ) |
| inline private

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.
  data | The 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_type | The type of the data stored in the binary blob.
  nbytes | The number of bytes that constitute the binary blob.
  data | The 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.
  data | The 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_type | The type of the data stored in the binary blob.
  nbytes | The number of bytes that constitute the binary blob.
  data | The 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

  src | The 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 | ) |
| inline private

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

  in | The 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 | ) |
| inline private

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

  vec | The 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
| ) |  |
| inline private

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_type | The 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
| static private

Definition at line 437 of file NeMatlabIO.h.

## ◆ SUBSYS_LENGTH

const int NeuralEngine::MatlabIO::SUBSYS_LENGTH = 8
| static private

Definition at line 438 of file NeMatlabIO.h.

## ◆ ENDIAN_LENGTH

const int NeuralEngine::MatlabIO::ENDIAN_LENGTH = 2
| static private

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:

- NeMatlabIO.h