PLY (Stanford) File Exporter

This geometry export converter writes out scenes in the Stanford PLY ASCII file format, including mesh attributes such as vertex normals, vertex colors and vertex texture coordinates. An optional material element can also be exported.

Please also refer to the corresponding PLY file importer.

The PLY format describes an object as a collection of vertices, faces and other elements, along with properties such as color and normal direction that can be attached to these elements. A PLY file contains the description of exactly one object. Sources of such objects include: hand-digitized objects, polygon objects from modeling programs, range data, triangles from marching cubes (isosurfaces from volume data), terrain data, radiosity models. Properties that might be stored with the object include: color, surface normals, texture coordinates, transparency, range data confidence, and different properties for the front and back of a polygon.

The PLY format is NOT intended to be a general scene description language, a shading language or a catch-all modeling format. This means that it includes no transformation matrices, object instantiation, modeling hierarchies, or object sub-parts. It does not include parametric patches, quadric surfaces, constructive solid geometry operations, triangle strips, polygons with holes, or texture descriptions.

A typical PLY object definition is simply a list of (x,y,z) triples for vertices and a list of faces that are described by indices into the list of vertices. Most PLY files include this core information. Vertices and faces are two examples of "elements", and the bulk of a PLY file is its list of elements. Each element in a given file has a fixed number of "properties" that are specified for each element. The typical information in a PLY file contains just two elements, the (x,y,z) triples for vertices and the vertex indices for each face. Applications can create new properties that are attached to elements of an object. For example, the properties red, green and blue are commonly associated with vertex elements. New properties are added in such a way that old programs do not break when these new properties are encountered. Properties that are not understood by a program can either be carried along uninterpreted or can be discarded. In addition, one can create a new element type and define the properties associated with this element. Examples of new elements are edges, cells (lists of pointers to faces) and materials (ambient, diffuse and specular colors and coefficients). New elements can also be carried along or discarded by programs that do not understand them.

Limitations of the PLY File Format

• PLY is mean to be a simple, easily parsable file format and hence only conveys basic geometry information.
  
  
• Only one object definition can be specified per PLY file. Hence, an entire 3D scene may require more than one PLY file to be exported.
  
  
• No material definitions are standardized in the PLY format.
  
  
• No lights, cameras, hierarchy, animation are provided by the PLY file format.

Exported PLY Element Types

The following table describes the element types that are exported.

Element Type	Properties

Face		Index list
Vertex		"x", "y" and "z" vertex coordinates
Vertex		"nx", "ny" and "nz" vertex normals
Vertex		"u" and "v" vertex texture coordinates
Vertex		"red", "green" and "blue" vertex colors 
		(0..255 integers or 0..1 normalized)

Custom Material Element

While not common nor standardized in PLY files, this exporter has an option to output a "material" element per PLY file.

The syntax for the "material" element is as follows (this element defines "1" material in the PLY file). The "specular_power" is assumed to lie between 0.0 and 1.0. The opacity is assumed to lie between 0.0 and 1.0. Each color coefficient must lie between 0.0 and 1.0.

element material 1
property uchar ambient_red     
property uchar ambient_green 
property uchar ambient_blue 
property float ambient_coeff
property uchar diffuse_red         
property uchar diffuse_green 
property uchar diffuse_blue 
property float diffuse_coeff 
property uchar specular_red        
property uchar specular_green 
property uchar specular_blue 
property float specular_coeff
property float specular_power   
property float opacity  

For example, the following PLY file defines a cube with vertex colors and one material assignment.

ply
format ascii 1.0
comment made by Greg Turk
comment this file is a cube
element vertex 8      
property float x        
property float y       
property float z       
element face 6          
property list uchar int vertex_indices
element material 1
property uchar ambient_red     
property uchar ambient_green 
property uchar ambient_blue 
property float ambient_coeff
property uchar diffuse_red         
property uchar diffuse_green 
property uchar diffuse_blue 
property float diffuse_coeff 
property uchar specular_red        
property uchar specular_green 
property uchar specular_blue 
property float specular_coeff
property float specular_power   
property float opacity   
end_header             
0 0 0             
0 0 1
0 1 1
0 1 0
1 0 0
1 0 1
1 1 1
1 1 0
4 0 1 2 3          
4 7 6 5 4
4 0 4 5 1
4 1 5 6 2
4 2 6 7 3
4 3 7 4 0
255 255 255 0.3 255 255 255 0.4 255 255 255 0.6 0.4 1.0

Dialog Box Options

Filename naming method

If the "Output entire scene as one single PLY file" option is disabled then these radio buttons determine how each PLY file will be named on disk. The PLY file format only allows a single object to be stored in each PLY file, and hence many PLY files will be written to disk to store all the objects in the scene.

Use name of each object as filename

The filename of each PLY file will be given the corresponding name of the 3D object definition inside the scene. For example, if the scene has 2 objects called "ball" and "bat" then these objects will be saved to disk as 2 PLY files called "ball.ply" and "bat.ply".

Use filename chosen via filename selector

The filename of each PLY file will be given the same name, as you had chosen on the Save-As file selector. For example, if you choose the export filename to be "Building.ply" then each PLY filename written to disk will use the names of "Building.ply", "Building2.ply", "Building3.ply", etc.

Output entire scene as one single PLY file

If this checkbox is checkmarked then the entire scene will be compressed and output to a single PLY file. Normally each and every object has to be exported to its own PLY file, potentially creating many PLY files on disk, so this checkbox is enabled by default so that all objects get output to a single PLY file.

Write PLY files to new sub-directory

If this checkbox is checkmarked then all the new PLY files will be written to a new sub-directory, named after the chosen PLY file. This should be enabled when the "Output entire scene as one single PLY file" option is disabled, since many PLY files will probably be written to disk.

ASCII Line Terminator Type: CR/LF, LF, CR

These radio buttons determine which kind of line terminator will be used. CR/LF is used for PC machines, LF for UNIX and CR for Macintosh.

Confirm file overwrites

If this checkbox is checkmarked then the user will be prompted first prior to existing PLY files on disk being overwritten.

Flip 'Y' up to 'Z' up coordinate system

If this checkbox is checkmarked then the internal 3D scene will be flipped so that "Z" is the up axis. All Okino scenes always use a "Y" up axis, however many PLY files use a "Z" up axis, so this option is enabled by default.

Output mesh data

If this checkbox is checkmarked then mesh geometry will be exported. This should always be enabled.

Output vertex normals

If this checkbox is checkmarked then vertex normals will be exported along with the mesh geometry.

Output u,v texture map coordinates

If this checkbox is checkmarked then (u,v) vertex texture coordinates will be exported along with the mesh geometry.

Output vertex colors

If this checkbox is checkmarked then all the colors assigned to each and every vertex will be exported along with the mesh geometry.

Want convex polygons only

Checkmark this checkbox to cause non-convex polygons to become triangulated

Want quadrilateral polygons only

Checkmark this checkbox to cause 5 or more sided polygons to become triangulated

Want triangles only

Checkmark this checkbox to cause 4 or more sided polygons to become triangulated

Enable polygon reduction

If this checkbox is enabled (check-marked) then the PLY exporter will apply the global polygon reduction algorithm to each mesh object just prior to them being embedded in the PLY file.

The algorithm allows the number of polygons in the scene to be greatly reduced. The parameters used to reduce the polygons can be modified by pressing the "Set Options" button. Press the "Help" button on its corresponding dialog box to learn more about the polygon reduction system.

Output materials ('surface' definitions)

If this checkbox is checkmarked then a "Material" element will be exported at the end of each PLY file. This option only truly makes sense if the "Output entire scene as one single PLY file" option is disabled.