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

NameType
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 PropertyElementPropertyData TypeProperty Description
vertexxfloatx,y,z coordinates
 yfloat 
 zfloat 
  nxfloatx,y,z of normal
  nyfloat 
  nzfloat 
  reducharvertex color
  greenuchar 
  blueuchar 
  alphaucharamount of transparency
  material_indexintindex to list of materials
facevertex_indiceslist of intindices to vertices
  back_red ucharbackside color
  back_greenuchar 
  back_blueuchar 
 edgevertex1intindex to vertex
  vertex2intindex to other vertex
  crease_tagucharcrease in subdivision surface
 materialreducharmaterial color
  greenuchar 
  blueuchar 
  alphaucharamount of transparency
  reflect_coefffloatamount of light reflected
  refract_coefffloatamount of light refracted
  refract_indexfloatindex of refraction
  extinct_coefffloatextinction coefficent

See Also

|