pointcloudfile

A specialised io module for binary .ply files containing XYZRGB points.

Most uses of this module should go through read() to iterate over points in the file, or write() to save an iterable of points. Neither function accumulates much data in memory.

IncrementalWriter is useful when accumulating data in memory to write many files is impractical. offset_for() and read_header() provide location metadata if possible.

In all cases a “point” is tuple of (x, y, z, r, g, b). XYZ are floats denoting spatial coordinates. RGB is the color, each an unsigned 8-bit integer. While intentionally limited in scope, most data can be converted to this format easily enough.

class src.pointcloudfile.IncrementalWriter(filename: str, header: src.pointcloudfile.PlyHeader, utm: src.pointcloudfile.UTM_Coord = None, buffer=4194304) → None

A streaming file writer for point clouds.

Using the IncrementalWriter with spooled temporary files, which are only flushed to disk if they go above the given size, allows for streaming points to disk even when the header is unknown in advance. This allows some nice tricks, including splitting a point cloud into multiple files in a single pass, without memory issues.

Parameters:

• filename – final place to save the file on disk.
• source_fname – source file for the pointcloud; used to detect file format for metadata etc.
• buffer (int) – The number of bytes to hold in RAM before flushing the temporary file to disk. Default 1MB, which holds ~8300 points - enough for most objects but still practical to hold thousands in memory. Set a smaller buffer for large forests.

class src.pointcloudfile.PlyHeader(vertex_count, names, form_str, comments)

Create new instance of PlyHeader(vertex_count, names, form_str, comments)

comments

Alias for field number 3

form_str

Alias for field number 2

names

Alias for field number 1

vertex_count

Alias for field number 0

class src.pointcloudfile.UTM_Coord(x, y, zone, north)

Create new instance of UTM_Coord(x, y, zone, north)

north

Alias for field number 3

x

Alias for field number 0

y

Alias for field number 1

zone

Alias for field number 2

src.pointcloudfile.offset_for(filename: str) → typing.Tuple[float, float, float]

Return the (x, y, z) UTM offset for a Pix4D or forestutils .ply file.

src.pointcloudfile.parse_ply_header(header_text: bytes) → src.pointcloudfile.PlyHeader

Parse the bytes of a .ply header to useful data about the vertices.

Deliberately discards the non-vertex data - this is a pointcloud module!

src.pointcloudfile.ply_header_text(filename: str) → bytes

Return the exact text of the header of the given .ply file, as bytes.

Using bytes to allow len(header) to give index to start of data; it’s trivial to decode in the parsing function.

src.pointcloudfile.read(fname: str) → typing.Iterator

Passes the file to a read function for that format.

src.pointcloudfile.write(cloud: typing.Iterator, fname: str, header: src.pointcloudfile.PlyHeader, utm: src.pointcloudfile.UTM_Coord) → None

Write the given cloud to disk.