SurgSim::DataStructures::PlyReader Class Reference

Wrapper for the C .ply file parser This class wraps the main functionality for the original C .ply file parser at http://paulbourke.net/dataformats/ply/ it enables customization of the parsing process either through a delegate class or through executing the requestElement and requestProperty functions. More...

`#include <SurgSim/DataStructures/PlyReader.h>`

## Classes

struct | Data
struct | ElementInfo
| Information about the element in the .ply file. More...
struct | PropertyInfo
| Information about the property on the .ply file. More...

## Public Types

enum | Type { TYPE_INVALID = 0, TYPE_CHAR, TYPE_SHORT, TYPE_INT, TYPE_UNSIGNED_CHAR, TYPE_UNSIGNED_SHORT, TYPE_UNSIGNED_INT, TYPE_FLOAT, TYPE_DOUBLE, TYPE_COUNT }
| Values that represent the data type/size of requested data. More...
typedef std::function< void *(const std::string &, size_t)> | StartElementCallbackType
| The callback that is being used to indicate the start of an element, the parameters that are passed into the callback are the name of the element that is being processed and the number of elements that will be processed. More...
typedef std::function< void(const std::string &)> | StandardCallbackType
| The callback that is used for the processing and the end of processing, the parameter passed is the name of the element that is being processed. More...

## Public Member Functions

| PlyReader (const std::string &filename)
| Constructor. More...
virtual | ~PlyReader ()
| Destructor. More...
bool | isValid () const
| Query if this object is valid. More...
bool | requestElement (const std::string &elementName, std::function< void *(const std::string &, size_t)> startElementCallback, std::function< void(const std::string &)> processElementCallback, std::function< void(const std::string &)> endElementCallback)
| Request element to be processed during parsing. More...
bool | requestScalarProperty (const std::string &elementName, const std::string &propertyName, int dataType, int dataOffset)
| Request a scalar property for parsing. More...
bool | requestListProperty (const std::string &elementName, const std::string &propertyName, int dataType, int dataOffset, int countType, int countOffset)
| Request a list property for parsing. More...
bool | hasElement (const std::string &elementName) const
| Query if this elementName is in the .ply file. More...
bool | hasProperty (const std::string &elementName, const std::string &propertyName) const
| Query if 'elementName' has the given property. More...
bool | isScalar (const std::string &elementName, const std::string &propertyName) const
| Query if the property of the give element is scalar. More...
bool | parseWithDelegate (std::shared_ptr< PlyReaderDelegate > delegate)
| Sets a delegate for parsing and then parse the file. More...
void | setStartParseFileCallback (std::function< void(void)> startParseFileCallback)
| Register callback to be called at the begining of parseFile. More...
void | setEndParseFileCallback (std::function< void(void)> endParseFileCallback)
| Register callback to be called at the end of parseFile. More...
bool | setDelegate (std::shared_ptr< PlyReaderDelegate > delegate)
| Sets a delegate for parsing. More...
void | parseFile ()
| Parse the file. More...

## Private Member Functions

bool | requestProperty (const std::string &elementName, const std::string &propertyName, int dataType, int dataOffset, int countType, int countOffset)
| Generic Internal function to handle list and scalar properties, see requestScalarProperty() and requestListProperty() for full documentation. More...

## Private Attributes

std::string | m_filename
| The name of the .ply file. More...
std::unordered_map< std::string, ElementInfo > | m_requestedElements
std::shared_ptr< PlyReaderDelegate > | m_delegate
| The delegate. More...
std::function< void(void)> | m_startParseFileCallback
| Callback to be executed at the start of 'parseFile'. More...
std::function< void(void)> | m_endParseFileCallback
| Callback to be executed at the end of 'parseFile'. More...
std::unique_ptr< Data > | m_data

## Friends

class | PlyReaderTests

## Detailed Description

Wrapper for the C .ply file parser This class wraps the main functionality for the original C .ply file parser at http://paulbourke.net/dataformats/ply/ it enables customization of the parsing process either through a delegate class or through executing the requestElement and requestProperty functions.

The file needs to be a valid .ply file, either ascii or binary, for the reader to be a valid reader.

## General Information

A ply file consists of a header description followed by the data, a header might look like this ply format ascii 1.0 { ascii/binary, format version number } comment made by Greg Turk { comments keyword specified, like all lines } comment this file is a cube element vertex 8 { define "vertex" element, 8 of them in file } property float x { vertex contains float "x" coordinate } property float y { y coordinate is also a vertex property } property float z { z coordinate, too } element face 6 { there are 6 "face" elements in the file } property list uchar int vertex_indices { "vertex_indices" is a list of ints } end_header { delimits the end of the header }

As you can see there are elements with properties, there can be multiple elements and multiple properties per element. An element can have scalar and/or list properties. To work correctly users will have to preallocate the memory that will be used by the parser to deposit the information from the file, and set offsets to the correct value to match the expected locations in the preallocated receiving memory.

## Initialisation

The constructor for the PlyReader accepts the file name of the file, it will make sure the the file exists and is actually a .ply file, after the constructor has executed isValid() should be true. At this time all the information in the header is available and users of the reader can tell the reader which elements and which properties are of interest using the requestElement() and requestProperty() functions.

## The three types of callback functions

Parsing is accomplished via a set of callback functions. There are three kinds of callback function each with a different responsibility.

- The BeginElement callback is called whenever the section for an element is encountered in the file, it will pass the name of the element and the number of elements that will be read it should return a pointer to the preallocated memory that will be used for reading.
- The ProcessElement callback is called whenever a new element has been read from the file, the read values can be copied from the preallocated memory that was sent to the parser in the previous callback. If list data was requested, the memory for the list data needs to be freed at this time.
- The EndElement callback is called whenever processing of the element is concluded, this gives users a chance to finalize processing on their side.

## The delegate

The PlyReaderDelegate interface should be used to create classes that encapsulate the needed callbacks and their processing.

## Member Typedef Documentation

## StandardCallbackType

typedef std::function<void (const std::string&)> SurgSim::DataStructures::PlyReader::StandardCallbackType

The callback that is used for the processing and the end of processing, the parameter passed is the name of the element that is being processed.

## StartElementCallbackType

typedef std::function<void* (const std::string&, size_t)> SurgSim::DataStructures::PlyReader::StartElementCallbackType

The callback that is being used to indicate the start of an element, the parameters that are passed into the callback are the name of the element that is being processed and the number of elements that will be processed.

The callback needs to return allocated memory that is used by the reader to deposit the read information

## Member Enumeration Documentation

## Type

enum SurgSim::DataStructures::PlyReader::Type

Values that represent the data type/size of requested data.

Enumerator
TYPE_INVALID |
TYPE_CHAR |
TYPE_SHORT |
TYPE_INT |
TYPE_UNSIGNED_CHAR |
TYPE_UNSIGNED_SHORT |
TYPE_UNSIGNED_INT |
TYPE_FLOAT |
TYPE_DOUBLE |
TYPE_COUNT |

## Constructor & Destructor Documentation

## PlyReader()

SurgSim::DataStructures::PlyReader::PlyReader | ( | const std::string & | filename | ) |

explicit

Constructor.

Parameters

  filename | Filename of the .ply file.

## ~PlyReader()

SurgSim::DataStructures::PlyReader::~PlyReader | ( |  | ) |

virtual

Destructor.

## Member Function Documentation

## hasElement()

bool SurgSim::DataStructures::PlyReader::hasElement | ( | const std::string & | elementName | ) | const

Query if this elementName is in the .ply file.

Parameters

  elementName | Name of the element.

Returns
  true if yes, false otherwise.

## hasProperty()

bool SurgSim::DataStructures::PlyReader::hasProperty | ( | const std::string & | elementName,
|  | const std::string & | propertyName
| ) |  | const

Query if 'elementName' has the given property.

Parameters

  elementName | Name of the element.
  propertyName | Name of the property.

Returns
  true if the element exists and has the property, false otherwise.

## isScalar()

bool SurgSim::DataStructures::PlyReader::isScalar | ( | const std::string & | elementName,
|  | const std::string & | propertyName
| ) |  | const

Query if the property of the give element is scalar.

Parameters

  elementName | Name of the element.
  propertyName | Name of the property.

Returns
  true if the element exists and has the property and it is a scalar value.

## isValid()

bool SurgSim::DataStructures::PlyReader::isValid | ( |  | ) | const

Query if this object is valid.

Returns
  true if the file was successfully opened, false if not.

## parseFile()

void SurgSim::DataStructures::PlyReader::parseFile | ( |  | ) |

Parse the file.

## parseWithDelegate()

bool SurgSim::DataStructures::PlyReader::parseWithDelegate | ( | std::shared_ptr< PlyReaderDelegate > | delegate | ) |

Sets a delegate for parsing and then parse the file.

Parameters

  delegate | The delegate.

Returns
  true if set and parse are successful; otherwise false.

## requestElement()

bool SurgSim::DataStructures::PlyReader::requestElement | ( | const std::string & | elementName,
|  | std::function< void *(const std::string &, size_t)> | startElementCallback,
|  | std::function< void(const std::string &)> | processElementCallback,
|  | std::function< void(const std::string &)> | endElementCallback
| ) |  |

Request element to be processed during parsing.

Parameters

  elementName | Name of the element that is needed.
  startElementCallback | The callback to be used when the element is first encountered.
  processElementCallback | The callback to be used when one element of this type is read.
  endElementCallback | The callback to be used when all of the elements of this type have been read.

Returns
  true if there is a element elementName in the .ply file and it has not been requested yet.

## requestListProperty()

bool SurgSim::DataStructures::PlyReader::requestListProperty | ( | const std::string & | elementName,
|  | const std::string & | propertyName,
|  | int | dataType,
|  | int | dataOffset,
|  | int | countType,
|  | int | countOffset
| ) |  |

Request a list property for parsing.

Use this for when you want the information from a list property from the .ply file. The item in your data structure should be a pointer of the type of data that you want, the reader will allocate the needed space and deposit all the items in the list in this space.

Warning
  If the offset is wrong or the data type provided and the actual data type in your structure does not match there could be a buffer overrun, use this with caution.

Parameters

  elementName | Name of the element that contains this property.
  propertyName | Name of the property that you want stored.
  dataType | The type of the data that should be stored.
  dataOffset | The offset of the data in your data structure where the data should be stored.
  countType | The type of the number of element that should be stored.
  countOffset | The offset for storing the count.

Returns
  true if it succeeds, false if it fails.

## requestProperty()

bool SurgSim::DataStructures::PlyReader::requestProperty | ( | const std::string & | elementName,
|  | const std::string & | propertyName,
|  | int | dataType,
|  | int | dataOffset,
|  | int | countType,
|  | int | countOffset
| ) |  |

private

Generic Internal function to handle list and scalar properties, see requestScalarProperty() and requestListProperty() for full documentation.

Parameters

  elementName | Name of the element that contains this property.
  propertyName | Name of the property that you want stored.
  dataType | The type of the data that should be stored.
  dataOffset | The offset of the data in your data structure where the data should be stored.
  countType | The type of the number of element that should be stored.
  countOffset | The offset for storing the count.

Returns
  true if it succeeds, false if it fails.

## requestScalarProperty()

bool SurgSim::DataStructures::PlyReader::requestScalarProperty | ( | const std::string & | elementName,
|  | const std::string & | propertyName,
|  | int | dataType,
|  | int | dataOffset
| ) |  |

Request a scalar property for parsing.

Use this for when you want the information from a scalar property from the .ply file. With this call you register the type that you want for storing the data and the offset in the data structure where the information should be stored. The data actually comes from the startElementCallback that was supplied in the previous call

Warning
  If the offset is wrong or the data type provided and the actual data type in your structure does not match there could be a buffer overrun, use this with caution

Parameters

  elementName | Name of the element that contains this property.
  propertyName | Name of the property that you want stored.
  dataType | The type of the data that should be stored.
  dataOffset | The offset of the data in your data structure where the data should be stored.

Returns
  true if the property exists and has not been registered yet and is a scalar property, otherwise false.

## setDelegate()

bool SurgSim::DataStructures::PlyReader::setDelegate | ( | std::shared_ptr< PlyReaderDelegate > | delegate | ) |

Sets a delegate for parsing.

Parameters

  delegate | The delegate.

Returns
  true if it succeeds and the properties in the ply file satisfy the delegates fileIsAcceptable().

## setEndParseFileCallback()

void SurgSim::DataStructures::PlyReader::setEndParseFileCallback | ( | std::function< void(void)> | endParseFileCallback | ) |

Register callback to be called at the end of parseFile.

## setStartParseFileCallback()

void SurgSim::DataStructures::PlyReader::setStartParseFileCallback | ( | std::function< void(void)> | startParseFileCallback | ) |

Register callback to be called at the begining of parseFile.

## Friends And Related Function Documentation

## PlyReaderTests

friend class PlyReaderTests

friend

## Member Data Documentation

## m_data

std::unique_ptr<Data> SurgSim::DataStructures::PlyReader::m_data

private

## m_delegate

std::shared_ptr<PlyReaderDelegate> SurgSim::DataStructures::PlyReader::m_delegate

private

The delegate.

## m_endParseFileCallback

std::function<void(void)> SurgSim::DataStructures::PlyReader::m_endParseFileCallback

private

Callback to be executed at the end of 'parseFile'.

## m_filename

std::string SurgSim::DataStructures::PlyReader::m_filename

private

The name of the .ply file.

## m_requestedElements

std::unordered_map<std::string, ElementInfo> SurgSim::DataStructures::PlyReader::m_requestedElements

private

## m_startParseFileCallback

std::function<void(void)> SurgSim::DataStructures::PlyReader::m_startParseFileCallback

private

Callback to be executed at the start of 'parseFile'.

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

- SurgSim/DataStructures/PlyReader.h
- SurgSim/DataStructures/PlyReader.cpp