Racket

PCD: Point Cloud Data Files🔗ℹ

turinglambdaai

package: pcd

This package reads and writes PCD point-cloud files — the native file format of the Point Cloud Library (PCL), version 0.7. All three PCD storage modes are supported: DATA ascii, DATA binary, and DATA binary_compressed. The compressed mode uses the LZF algorithm (as PCL does) and requires the pure-Racket lzf package, a declared runtime dependency.

1 Quick start🔗ℹ

(require pcd)

(define cloud
  (point-cloud
   '("x" "y" "z" "intensity")
   '(4 4 4 4)
   '(#\F #\F #\F #\F)
   '(1 1 1 1)
   3 1
   (vector 0.0 0.0 0.0 1.0 0.0 0.0 0.0)
   (vector (vector 0.5 1.25 -3.75 10.5)
           (vector 1.0 2.0 3.0 -0.5)
           (vector 4.0 5.0 6.0 1.5))))

(pcd-write-file "/tmp/example.pcd" cloud #:data 'binary-compressed)
(define cloud2 (pcd-read-file "/tmp/example.pcd"))
(equal? cloud cloud2)

2 The point-cloud record🔗ℹ

struct
(struct point-cloud ( fields
sizes
types
counts
width
height
viewpoint
points))
  fields : (listof string?)
  sizes : (listof pcd-size/c)
  types : (listof pcd-type/c)
  counts : (listof pcd-count/c)
  width : exact-nonnegative-integer?
  height : exact-nonnegative-integer?
  viewpoint : (vectorof flonum?)
  points : (vectorof (vectorof real?))

A parsed (or to-be-written) PCD file. The constructor validates its arguments and raises exn:fail on malformed clouds, so any point-cloud? value is well-formed. Two clouds with equal field values are equal?, so a round-trip yields an equal? value.

fields — the FIELDS names in file order. A field named "_" is PCL’s padding marker: it occupies space in 'ascii and 'binary data and is skipped in 'binary-compressed chunks (its values read back as 0, exactly like PCL).
sizes — bytes per field element: 1, 2, 4, or 8 (the SIZE line).
types — one of #\F (float), #\U (unsigned integer), or #\I (signed integer) per field (the TYPE line). Float fields require size 4 or 8.
counts — elements per field (the COUNT line). A file that omits the line is read as all-1. A field with count n contributes n consecutive elements to every point’s value vector.
width, height — the WIDTH and HEIGHT lines. Organized clouds (height greater than 1) are supported; points is stored row-major, with width consecutive points per row. For unorganized clouds height is 1. The constraint that (* width height) equals the number of points is enforced.
viewpoint — seven flonums: translation tx ty tz then quaternion qw qx qy qz; defaults to (vector 0.0 0.0 0.0 1.0 0.0 0.0 0.0) when a file omits the VIEWPOINT line.
points — point-major vector; each point is a flat vector of every field element in file order (its length is the sum of counts). Float columns hold flonums; integer columns hold exact integers within the range of their size and signedness.

procedure
(pcd-size/c v) → boolean?
v : any/c

Recognizes legal SIZE values.

procedure
(pcd-type/c v) → boolean?
v : any/c

Recognizes legal TYPE values.

procedure
(pcd-count/c v) → boolean?
v : any/c

Flat contracts for the field tables: size in '(1 2 4 8), type in '(#\F #\U #\I), count a positive exact integer.

3 Reading and writing🔗ℹ

procedure
(pcd-read in) → point-cloud?
in : input-port?

Reads a PCD file from in, consuming the header and the entire data section. Trailing bytes after the data section are ignored (some writers pad files).

procedure
(pcd-read-file path) → point-cloud?
path : path-string?

Opens path and pcd-reads it.

procedure
(pcd-read-bytes bs) → point-cloud?
bs : bytes?

Reads a PCD file from a byte string.

procedure
(pcd-write out cloud [#:data data]) → void?
  out : output-port?
  cloud : point-cloud?
  data : (or/c 'ascii 'binary 'binary-compressed) = 'ascii

Writes cloud to out as a PCD v0.7 file with the given storage mode.

procedure
(pcd-write-file path cloud [#:data data]) → void?
  path : path-string?
  cloud : point-cloud?
  data : (or/c 'ascii 'binary 'binary-compressed) = 'ascii

Writes cloud to path (truncating any existing file).

4 Data formats🔗ℹ

4.1 ascii🔗ℹ

One point per line; values separated by spaces or tabs. Float values are printed so that they read back bit-exactly for float32-representable values; nan, inf, and -inf follow PCL’s conventions and round-trip.

4.2 binary🔗ℹ

A little-endian array of structures: for each point, every field element in file order at its sizes width. Reading requires POINTS × step bytes and rejects truncated data.

4.3 binary_compressed🔗ℹ

Matches PCL’s on-disk layout: the data is reordered field-major (all values of the first field, then the second, ...), each field’s chunk is LZF compressed, and for each field — in field order, skipping "_" padding fields — the file stores a little-endian unsigned 32-bit compressed size, then an unsigned 32-bit uncompressed size, then the compressed chunk. The reader validates each field’s uncompressed size against SIZE × COUNT × POINTS, de-interleaves the planes back to point-major order, and decodes values as in the binary format. Truncated or corrupt LZF chunks raise exn:fail naming the field.

5 Errors🔗ℹ

All format errors raise exn:fail. Messages name the offending header line number, field, or point index, e.g. header line 3: unknown TYPE 'Q' for field 'z', truncated DATA section: needed 12 byte(s) of binary point data, got only 4, or header line 8: POINTS 5 does not match WIDTH * HEIGHT = 1.

6 Scope🔗ℹ

This package is a file-format codec for PCD v0.7. It does not re-create PCL’s pcl::PointCloud C++ type system, Kd-trees, filters, or readers for other formats (PLY, STL, OBJ, ...).

1	Quick start
2	The point-cloud record
3	Reading and writing
4	Data formats
5	Errors
6	Scope