API Reference

NumPy-based PLY format input and output for Python.

class plyfile.PlyData

PLY file header and data.

A PlyData instance is created in one of two ways: by the static method PlyData.read (to read a PLY file), or directly from __init__ given a sequence of elements (which can then be written to a PLY file).

Attributes:

elementslist of PlyElement
commentslist of str
obj_infolist of str
textbool
byte_order{‘<’, ‘>’, ‘=’}
headerstr: PLY-formatted metadata for the instance.

Methods

`read`(stream[, mmap, known_list_len])	Read PLY data from a readable file-like object or filename.
`write`(stream)	Write PLY data to a writeable file-like object or filename.

__init__(elements=[], text=False, byte_order='=', comments=[], obj_info=[])

Parameters:

elementsiterable of PlyElement
textbool, optional: Whether the resulting PLY file will be text (True) or binary (False).
byte_order{‘<’, ‘>’, ‘=’}, optional: '<' for little-endian, '>' for big-endian, or '=' for native. This is only relevant if text is False.
commentsiterable of str, optional: Comment lines between “ply” and “format” lines.
obj_infoiterable of str, optional: like comments, but will be placed in the header with “obj_info …” instead of “comment …”.

static read(stream, mmap=True, known_list_len={})

Read PLY data from a readable file-like object or filename.

Parameters:

streamstr or readable open file
mmapbool, optional (default=True): Whether to allow element data to be memory-mapped when possible. The default is True, which allows memory mapping. Using False will prevent memory mapping.
known_list_lendict, optional: Mapping from element names to mappings from list property names to their fixed lengths. This optional argument is necessary to enable memory mapping of elements that contain list properties. (Note that elements with variable-length list properties cannot be memory-mapped.)

Raises:

PlyParseError: If the file cannot be parsed for any reason.
ValueError: If stream is open in text mode but the PLY header indicates binary encoding.

write(stream)

Write PLY data to a writeable file-like object or filename.

Parameters:

streamstr or writeable open file

Raises:

ValueError: If stream is open in text mode and the file to be written is binary-format.

property header: PLY-formatted metadata for the instance.

__len__(): Return the number of elements.

__contains__(name): Check if an element with the given name exists.

__getitem__(name)

Retrieve an element by name.

Parameters:

namestr

Returns:

PlyElement

Raises:

KeyError: If the element can’t be found.

class plyfile.PlyElement

PLY file element.

Creating a PlyElement instance is generally done in one of two ways: as a byproduct of PlyData.read (when reading a PLY file) and by PlyElement.describe (before writing a PLY file).

Attributes:

namestr
countint
datanumpy.ndarray
propertieslist of PlyProperty
commentslist of str
headerstr: PLY header block for this element.

Methods

`describe`(data, name[, len_types, val_types, ...])	Construct a `PlyElement` instance from an array's metadata.
`dtype`([byte_order])	Return the `numpy.dtype` description of the in-memory representation of the data.
`ply_property`(name)	Look up property by name.

__init__(name, properties, count, comments=[])

This is not part of the public interface. The preferred methods of obtaining PlyElement instances are PlyData.read (to read from a file) and PlyElement.describe (to construct from a numpy array).

Parameters:

namestr
propertieslist of PlyProperty
countstr
commentslist of str

ply_property(name)

Look up property by name.

Parameters:

namestr

Returns:

PlyProperty

Raises:

KeyError: If the property can’t be found.

dtype(byte_order='=')

Return the numpy.dtype description of the in-memory representation of the data. (If there are no list properties, and the PLY format is binary, then this also accurately describes the on-disk representation of the element.)

Parameters:

byte_order{‘<’, ‘>’, ‘=’}

Returns:

numpy.dtype

static describe(data, name, len_types={}, val_types={}, comments=[])

Construct a PlyElement instance from an array’s metadata.

Parameters:

datanumpy.ndarray: Structured numpy array.
len_typesdict, optional: Mapping from list property names to type strings (numpy-style like 'u1', 'f4', etc., or PLY-style like 'int8', 'float32', etc.), which will be used to encode the length of the list in binary-format PLY files. Defaults to 'u1' (8-bit integer) for all list properties.
val_typesdict, optional: Mapping from list property names to type strings as for len_types, but is used to encode the list elements in binary-format PLY files. Defaults to 'i4' (32-bit integer) for all list properties.
commentslist of str: Comments between the “element” line and first property definition in the header.

Returns:

PlyElement

Raises:

TypeError, ValueError

__len__(): Return the number of rows in the element.

__contains__(name): Determine if a property with the given name exists.

__getitem__(key): Proxy to self.data.__getitem__ for convenience.

__setitem__(key, value): Proxy to self.data.__setitem__ for convenience.

class plyfile.PlyProperty

PLY property description.

This class is pure metadata. The data itself is contained in PlyElement instances.

Attributes:

namestr
val_dtypestr: numpy.dtype description for the property’s data.

Methods

dtype([byte_order])

Return the numpy.dtype description for this property.

__init__(name, val_dtype)

Parameters:

namestr
val_dtypestr

dtype(byte_order='=')

Return the numpy.dtype description for this property.

Parameters:

byte_order{‘<’, ‘>’, ‘=’}, default=’=’

Returns:

tuple of str

class plyfile.PlyListProperty

PLY list property description.

Attributes:

name
val_dtype
len_dtypestr: numpy.dtype description for the property’s length field.

Methods

`dtype`([byte_order])	`numpy.dtype` name for the property's field in the element.
`list_dtype`([byte_order])	Return the pair `(len_dtype, val_dtype)` (both numpy-friendly strings).

__init__(name, len_dtype, val_dtype)

Parameters:

namestr
len_dtypestr
val_dtypestr

dtype(byte_order='=')

numpy.dtype name for the property’s field in the element.

List properties always have a numpy dtype of “object”.

Parameters:

byte_order{‘<’, ‘>’, ‘=’}

Returns:

dtypestr: Always '|O'.

list_dtype(byte_order='=')

Return the pair (len_dtype, val_dtype) (both numpy-friendly strings).

Parameters:

byte_order{‘<’, ‘>’, ‘=’}

Returns:

len_dtypestr
val_dtypestr

exception plyfile.PlyParseError: Base class for PLY parsing errors.

exception plyfile.PlyElementParseError

Raised when a PLY element cannot be parsed.

Attributes:

messagestr
elementPlyElement
rowint
propPlyProperty

__init__(message, element=None, row=None, prop=None)

exception plyfile.PlyHeaderParseError

Raised when a PLY header cannot be parsed.

Attributes:

linestr: Which header line the error occurred on.

__init__(message, line=None)