The PLY Format

The version 1.0 PLY format, also known as the Stanford Triangle Format, defines a flexible and systematic scheme for storing 3D data. The ASCII header specifies what data is in the file by defining "elements" each with a set of "properties." Many PLY files only have vertex and face data, however, it is possible to also include other data such as color information, vertex normals, or application-specific properties.

Note

The Computer Vision Toolbox™ point cloud data functions only support the (x,y,z) coordinates, normals, and color properties.

File Header

An example header (italicized text is comment):

ply	file ID
format binary_big_endian 1.0	specify data format and version
element vertex 9200	define "vertex" element
property float x
property float y
property float z
element face 18000	define "face" element
property list uchar int vertex_indices
end_header	data starts after this line

The file begins with "ply," identifying that it is a PLY file. The header must also include a format line with the syntax

format <data format> <PLY version>

Supported data formats are "ascii" for data stored as text and "binary_little_endian" and "binary_big_endian" for binary data (where little/big endian refers to the byte ordering of multi-byte data). Element definitions begin with an "element" line followed by element property definitions

element <element name><number in file>

property <data type><property name 1>

property <data type><property name 2>

property <data type><property name 3>

...

For example, "element vertex 9200" defines an element "vertex" and specifies that 9200 vertices are stored in the file. Each element definition is followed by a list of properties of that element. There are two kinds of properties, scalar and list. A scalar property definition has the syntax

property <data type><property name>

where <data type> is

Name	Type
char	(8-bit) character
uchar	(8-bit) unsigned character
short	(16-bit) short integer
ushort	(16-bit) unsigned short integer
int	(32-bit) integer
uint	(32-bit) unsigned integer
float	(32-bit) single-precision float
double	(64-bit) double-precision float

For compatibility between systems, note that the number of bits in each data type must be consistent. A list type is stored with a count followed by a list of scalars. The definition syntax for a list property is

property list <count data type><data type><property name>

For example,

property list uchar int vertex_index

defines vertex_index properties are stored starting with a byte count followed by integer values. This is useful for storing polygon connectivity as it has the flexibility to specify a variable number of vertex indices in each face.

The header can also include comments. The syntax for a comment is simply a line beginning with "comment" followed by a one-line comment:

comment<comment text>

Comments can provide information about the data like the file's author, data description, data source, and other textual data.

Data

Following the header, the element data is stored as either ASCII or binary data (as specified by the format line in the header). After the header, the data is stored in the order the elements and properties were defined. First, all the data for the first element type is stored. In the example header, the first element type is "vertex" with 9200 vertices in the file, and with float properties "x," "y," and "z."

float vertex[1].x

float vertex[1].y

float vertex[1].z

float vertex[2].x

float vertex[2].y

float vertex[2].z

...

float vertex[9200].x

float vertex[9200].y

float vertex[9200].z

In general, the properties data for each element is stored one element at a time.

<property 1><property 2> ... <property N> element[1]

<property 1><property 2> ... <property N> element[2]

...

The list type properties are stored beginning with a count and followed by a list of scalars. For example, the "face" element type has the list property "vertex_indices" with uchar count and int scalar type.

uchar count

int face[1].vertex_indices[1]

int face[1].vertex_indices[2]

int face[1].vertex_indices[3]

...

int face[1].vertex_indices[count]

uchar count

int face[2].vertex_indices[1]

int face[2].vertex_indices[2]

int face[2].vertex_indices[3]

...

int face[2].vertex_indices[count]

...

Common Elements and Properties

While the PLY format has the flexibility to define many types of elements and properties, a common set of elements are understood between programs to communicate common 3-D data types. Turk suggests elements and property names that programs should try to make standard.

Required Core Property	Element	Property	Data Type	Property Description
✓	vertex	x	float	x,y,z coordinates
✓		y	float
✓		z	float
		nx	float	x,y,z of normal
		ny	float
		nz	float
		red	uchar	vertex color
		green	uchar
		blue	uchar
		alpha	uchar	amount of transparency
		material_index	int	index to list of materials
	face	vertex_indices	list of int	indices to vertices
		back_red	uchar	backside color
		back_green	uchar
		back_blue	uchar
	edge	vertex1	int	index to vertex
		vertex2	int	index to other vertex
		crease_tag	uchar	crease in subdivision surface
	material	red	uchar	material color
		green	uchar
		blue	uchar
		alpha	uchar	amount of transparency
		reflect_coeff	float	amount of light reflected
		refract_coeff	float	amount of light refracted
		refract_index	float	index of refraction
		extinct_coeff	float	extinction coefficient