Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-ply

Source of release 0.1.0

0.1.0 / README.md

# luce-ply

PLY in Luce Base: reading and writing ASCII, binary little-endian and binary
big-endian files with any elements and properties, as luce-geocore
GeometrySets.

```luce
from luce_ply.ply import Ply

let geometry = Ply.load("scan.ply")
Ply.save(geometry, "copy.ply")             # binary little-endian
Ply.save(geometry, "copy.txt.ply", "ascii")
print(Ply.warnings())
```

## Reading

- The `vertex` element gives the points. `x y z` are the positions; every
  other property becomes a point attribute of its name, except these groups:
  `nx ny nz` become `N`, `red green blue` (or `diffuse_*`) become `Cd` in
  0..1 with `alpha` as `Alpha`, and `u v`, `s t`, `texture_u texture_v` or
  `texture_s texture_t` become `uv`.
- A `face` element with a `vertex_indices` (or `vertex_index`) list makes a
  mesh. Its other properties become face attributes, and a `texcoord` list
  becomes corner `uv`. Without faces the points are a point cloud.
- Lists on vertices and faces become array attributes.
- Every other element's scalar properties become detail arrays named
  `element.property`.
- Integer properties keep their values exactly (`uint` as 64-bit). Double
  positions are stored as f32 offsets from an f64 origin at their center.

## Gaussian splats

A 3DGS file (a vertex element with `f_dc_0..2`, `opacity`, `scale_0..2` and
`rot_0..3`) keeps those raw PLY names as f32 point attributes. Its
channel-major `f_rest_*` become one array attribute, `f_rest`: per point,
coefficient-major RGB items (item i is coefficient i + 1 of red, green and
blue), 0, 3, 8 or 15 items. Its all-zero normals are dropped. luce-geocore's
Bake GSplats turns these names into the splat conventions (`orient`, `scale`,
`opacity`, `Cd`, `sh`).

Binary bodies without lists decode in parallel on luce-std's pool, a block
of rows at a time: a 1M-splat degree-3 file (248 MB) reads in well under a
second.

PlayCanvas compressed PLY (SuperSplat) reads to the same raw names. Writing
it is not supported yet.

## Writing

The mesh, or else the point cloud, is written as the `vertex` element (and
the faces as `face`), mapping attributes back as the reader maps them. A
cloud with the raw 3DGS names is written in the reference layout
(`x y z nx ny nz f_dc_* f_rest_* opacity scale_* rot_*`, all float), so a
3DGS file read and written comes back byte for byte. ASCII floats use the
fewest digits that read back to the same value.

## Tests

`luc test` runs `tests/ply`: ASCII, binary little- and big-endian fixtures
made in the test, a byte-exact 3DGS round trip, the f_rest interleaving
against a hand-built file, compressed PLY, and the read and write times of a
1M-splat file.