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

The PLY Format

File Header

Data

Common Elements and Properties

See Also