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 <PlyReader.h>

Classes
struct	Data

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.

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.

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.

void	setEndParseFileCallback (std::function< void(void)> endParseFileCallback)
	Register callback to be called at the end of parseFile.

bool	setDelegate (std::shared_ptr< PlyReaderDelegate > delegate)
	Sets a delegate for parsing. More...

void	parseFile ()
	Parse the file.

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

Constructor & Destructor Documentation

§ PlyReader()

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

explicit

Constructor.

Parameters

filename Filename of the .ply file.

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.

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

§ 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().

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

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

Classes

Public Types

Public Member Functions

Friends

Detailed Description

General Information

Initialisation

The three types of callback functions

The delegate

Member Typedef Documentation

§ StandardCallbackType

§ StartElementCallbackType

Constructor & Destructor Documentation

§ PlyReader()

Member Function Documentation

§ hasElement()

§ hasProperty()

§ isScalar()

§ isValid()

§ parseWithDelegate()

§ requestElement()

§ requestListProperty()

§ requestScalarProperty()

§ setDelegate()