Module polygon

The module polygon can read and write PLY polygon files (*.ply).

Examples

Note: Click triangle to view content.

another-cube.greg-turk.ascii.ply:

ply
format ascii 1.0
comment author: Greg Turk
comment object: another cube
element vertex 8
property float x
property float y
property float z
property uchar red
property uchar green
property uchar blue
element face 7
property list uchar int vertex_index
element edge 5
property int vertex1
property int vertex2
property uchar red
property uchar green
property uchar blue
end_header
0 0 0 255 0 0
0 0 1 255 0 0
0 1 1 255 0 0
0 1 0 255 0 0
1 0 0 0 0 255
1 0 1 0 0 255
1 1 1 0 0 255
1 1 0 0 0 255
3 0 1 2
3 0 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
0 1 255 255 255
1 2 255 255 255
2 3 255 255 255
3 0 255 255 255
2 0 0 0 0

single-triangle.ascii.ply:

ply
format ascii 1.0
element vertex 3
property float x
property float y
end_header
0.0 1.0
0.0 0
.0 -1.0

single-triangle.binary-le.ply:

ply
format binary_little_endian 1.0
element vertex 3
property float x
property float y
end_header
\x00\x00\x00\x00\x00\x00\x80\x3f
\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x80\xbf

Supplements for “The PLY Polygon File Format by Greg Turk”

File Structure

This is the structure of a supplemented PLY file:

1. Header layout:

• Each part of the “header” is a “newline-terminated ASCII string (LF or CRLF)” that begins with a “keyword”. The preferred newline terminator is LF.
• Following the header is one “list of elements for each element type”, presented “in the order and quantity described in the header”.

2. Keyword ply:

• The characters “ply” must be the first “three” characters of the file.

3. Keyword format:

• Following the start of the header is the keyword “format” and a specification of either ASCII or binary format, followed by a “version identifier”.
• The header of a binary version of the same object would differ only in substituting the word “binary_little_endian” or “binary_big_endian” for the word “ascii”.
• In “ascii” format, each element is a “newline-terminated ASCII string” composed of “space-separated” data values.
• In “binary_little_endian” and “binary_big_endian” formats, the data is stored in corresponding byte order, with “neither whitespace nor newline” between the data values.

4. Keyword element and property:

• Next is the description of each of the elements in the polygon file, and within each element description is the specification of the properties. The generic “element” descriptions may be like:

  element <element-name-1> <number-in-file>
  property <data-type> <property-name-1>
  property <data-type> <property-name-2>
  property <data-type> <property-name-3>
  ...
  element <element-name-2> <number-in-file>
  property <data-type> <property-name-1>
  property <data-type> <property-name-2>
  ...

5. Data types of property:

• The “properties” listed after an “element” line define both the “data type” of the property and also the “order” in which the property appears for each element. There are two kinds of data types a property may have: scalar and list.

  Here is a list of the “common scalar data types” a “property” may have:

  name	description	number of bytes
  int8 | char	character	1
  uint8 | uchar	unsigned character	1
  int16 | short	short integer	2
  uint16 | ushort	unsigned short integer	2
  int32 | int	integer	4
  uint32 | uint	unsigned integer	4
  float32 | float	single-precision float	4
  float64 | double	double-precision float	8

  Here is a list of the “special scalar data types” a “property” may have:

  name	description	number of bytes
  byte	byte	1
  ubyte	unsigned byte	1
  half	half-precision float	2
  long	unsigned long integer	8
  ulong	long integer	8
  float16	half-precision float	2
  int64	long integer	8
  uint64	unsigned long integer	8

• There is a special form of “property” definitions that uses the “list data type”:

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

  The count and value data types are specified separately and must be scalar, not list types.

  Here is an example:

  property list ushort int vertex_index

  This means that the property “vertex_index” starts with an unsigned short specifying the count of indices, followed by a list containing that many integers. Each integer in this “variable-length list” is an index to a vertex.

6. Keyword comment and obj_info:

• Comments in files are ordinary keyword-identified lines that begin with the word “comment” and “obj_info”.

7. Keyword end_header:

• “end_header” and a line terminator (CRLF or LF) delimits the end of the header.

The Syntax for Polygon File Format

Authored by Asher Chen, Nov 2024.

Backus-Naur Form

Click to expand

<newline> ::= "\r"? "\n"
<number>  ::= [0-9]
<space>   ::= " "
<word>    ::=
    [A-Z] | [a-z] | <number> | "_" |
    "." | "," | ":" | ";" | "'" | "\"" |
    "!" | "?" | "-" | "+" | "*" | "/" |
    "@" | "#" | "$" | "%" | "^" | "(" |
    ")" | "[" | "]" | "{" | "}" | "|" |
    "\\" | "~" | "`" | "<" | ">" | "=" |
    "&"

<polygon_header> ::=
    <header_start>
    (<header_block> <newline>)*
    <header_end>

    <header_start> ::=
        "ply" <newline>
        "format" <space>+ <format> <space>+ <version> <newline>

        <format> ::=
            "ascii" | "binary_big_endian" | "binary_little_endian"
        <version> ::= <word>+

    <header_block> ::=
        "comment" <space>+ <comment> |
        "element" <space>+ <element_name> <space>+ <element_size> |
        "property" <space>+ <property_kind> <space>+ <property_name> |
        "obj_info" <space>+ <comment>

        <comment> ::=
            (<word> | <space>)*
        <element_name> ::=
            <word>+
        <element_size> ::=
            <number>+
        <property_kind> ::=
            "list" <space>+ <scalar_property_kind> <space>+ <scalar_property_kind> |
            <scalar_property_kind>
        <property_name> ::=
            <word>+
        <property_size> ::=
            <number>+
        <scalar_property_kind> ::=
            "u"? "char" |
            "u"? "short" |
            "u"? "int" ("8" | "16" | "32")? |
            "float" ("32" | "64")? |
            "double" |
            <special_scalar_property_kind>
        <special_scalar_property_kind> ::=
            "half" | "float16" |
            "u"? ("long" | "int64")

    <header_end> ::=
        "end_header" <newline>

License

The PLY Polygon File Format by Greg Turk

Retrieved from: https://web.archive.org/web/20161204152348/http://www.dcs.ed.ac.uk/teaching/cs4/www/graphics/Web/ply.html

Copyright (c) 1994 The Board of Trustees of The Leland Stanford Junior University. All rights reserved. Permission to use, copy, modify and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice and this permission notice appear in all copies of this software and that you do not sell the software.

THE SOFTWARE IS PROVIDED “AS IS” AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE

Re-exports

• pub use crate::error::Error;
• pub use crate::function::Decoder;
• pub use crate::function::DecoderWith;
• pub use crate::function::Encoder;
• pub use header::Format;
• pub use header::Header;
• pub use object::Object;
• pub use payload::Payload;

Modules

• header
  Polygon header module.
• object
  Polygon object module.
• payload
  Polygon payload module.