dymokomi/luce-usd
Source of release 0.9.3
# USD and GeometrySet
How `Usd.load` turns a stage into a luce-geocore `GeometrySet`, and how
`Usd.save` writes one back. The code is in `src/convert/`.
## Loading
A GeometrySet holds one component per family, so loading merges prims, as
Houdini's USD Import does:
- every mesh becomes part of one mesh;
- every Points prim becomes part of one point cloud, unless the stage has
Gaussian splats (below), which take the cloud instead (Points are then
left out with a warning);
- every curves prim becomes part of one curves component;
- every PointInstancer, and every scene-graph instance (a prim marked
`instanceable` in a composed stage), becomes rows of one instances
component.
Each face, curve and point keeps its prim's path in the text attribute
`path`, so Blast and the path filters see the hierarchy. Points are placed
by their prims' world transforms, in f64, over the set's origin.
Which prims load:
- defined, active prims only: not `over`s or `class`es;
- not invisible ones;
- purposes `default` and `render`, plus `proxy` and `guide` on request;
- not the prototypes of a point instancer, which are placed by it.
Values are read at the `time` argument. Without one, the layer's
`startTimeCode` is used, else each attribute's first sample (a spline's
first knot). Samples in between are interpolated linearly; an attribute
spline is evaluated as Ts evaluates it (held, linear, Bezier or Hermite
segments, extrapolation and loops).
`Usd.warnings()` lists what a load left out.
### Meshes
- **Winding.** `leftHanded` meshes, and meshes under a mirroring transform,
have their faces reversed, keeping the first corner.
- **Faces** keep their corners: n-gons stay n-gons. Faces with fewer than
3 corners are dropped. A face without an area (its points coincide or lie
on a line) is kept with a zero normal, and counted in a warning; a
self-intersecting face displays as a fan. Faces may have any number of
corners.
- **Primvars** become attributes by interpolation:
| USD interpolation | Attribute domain |
|---|---|
| vertex, varying | point |
| faceVarying | corner |
| uniform | face |
| constant | detail |
Indexed primvars are expanded, and `elementSize` multiplies the tuple
width (at most 4).
- **Names.** `displayColor` becomes `Cd`, `displayOpacity` becomes `Alpha`,
`st` (or the first texCoord2f primvar) becomes `uv`, and `normals` becomes
`N`. Other primvars drop the `primvars:` prefix.
- **Constant primvars** are inherited from ancestor prims. When several
prims merge, one that differs between prims is stored per face.
- **Types.** Floating point becomes f32, and double becomes f64. Integers
become i32 or i64, and strings and tokens become text.
- **GeomSubsets** become face, point and edge groups named after the
subset. Subsets with the same name on different prims are merged.
- **Materials.** Each face's bound material path (direct bindings,
including subsets') goes in the face text attribute `material`.
- **Subdivision.**
- `subdivisionScheme` becomes `subd.scheme`, shown at level 1.
Unauthored means Catmull-Clark (USD's default) unless
`subdivide = false`.
- `interpolateBoundary` becomes `subd.boundary`.
- Creases become the edge attribute `crease`, corners become the point
attribute `corner_sharpness`, and holes become the face group `hole`.
- The merged mesh holds one scheme: the one most faces ask for.
- **Intrinsic shapes.** Cube, Sphere, Cylinder, Cone, Capsule and Plane
are tessellated: 24 segments around and 12 along.
### Curves, points and instances
- **BasisCurves.** Linear curves become poly curves.
- **Bezier.** Cubic Bezier curves become Bezier curves with `handle_l` and
`handle_r`.
- **Bspline.** Cubic B-splines become uniform order-4 NURBS.
- **Catmull-Rom** curves become Catmull-Rom curves. A nonperiodic one drops
its phantom first and last points.
- **NurbsCurves** keep their order, their knots (narrowed to f32) and their
weights, as `w`.
- **Periodic curves** become cyclic.
- **Points.** `widths` becomes `width`, and `ids` becomes `id`.
- **Gaussian splats** (UsdVol's `ParticleField3DGaussianSplat`, OpenUSD
26.03, or a `ParticleField` applying `ParticleFieldKernelGaussianEllipsoidAPI`)
become luce-geocore's splat cloud (`orient`, `scale`, `opacity`, linear
`Cd`, `sh`), placed in world space exactly (covariances and SH), all prims
joined. Each splat keeps its prim's path in the point text `path`, as
meshes and Points do.
- A prim without SH coefficients (degree 0, as Houdini writes them) takes
its color from `primvars:displayColor` (vertex or constant, linear).
- When every prim stored half positions, the detail `usd.halfSplats` says
so.
- Scales are linear σ and opacities linear, as in the schema; the half
variants are read when the float ones are missing; short arrays are
ignored (unit scale, opacity 1, no rotation) and long ones cut.
- `radiance:sphericalHarmonicsCoefficients` are read as 3DGS's raw SH:
the first per splat is a PLY's `f_dc` (color 0.5 + C0 · f_dc), the rest
its `f_rest`. The schema names the original 3DGS technique but does not
spell this out, so it is an assumption. Colors are sRGB-encoded (`Cd` is
decoded to linear) unless the prim's custom `luce:gsplatColorSpace` says
`linear`. Bands past degree 3 are dropped with a warning.
- `sortingModeHint` and `projectionModeHint` become the detail texts
`gsplat_sorting_mode` and `gsplat_projection_mode`.
- Export writes a splat cloud as `ParticleField3DGaussianSplat` prims,
one per `path` (`splats` under the root without one), with float
arrays, or half ones (`positionsh`, ...) when the cloud came from halves
or `splat_precision` asks for them, the SH in the world frame
(a `restorient` baked in), the hints (zDepth and perspective by default)
and, for a linear cloud, `luce:gsplatColorSpace`. Other point attributes
are left out with a warning.
- **PointInstancer.**
- Each prototype is loaded once as its own set. Its paths are relative
to the prototype's parent.
- Each instance is a row: its position, orientation and scale, then the
instancer's transform. A sheared row takes the nearest rotation and
scale, with a warning. A `primvars:path` of one string per instance
becomes the rows' `path` attribute.
- With `flatten = true`, instances are baked into the other components
instead.
- **Scene-graph instances.** A composed stage is flattened as UsdStage
flattens it: instances sharing composition share one prototype.
- Each prototype is loaded once; its paths are relative to the prototype.
- Each instance is a row placed by its world transform; its prim's path
is the row attribute `path`.
- Constant primvars inherited from an instance's ancestors do not reach
its prototype's prims (they would differ per instance).
- With `flatten = true`, each instance holds its own copy of its
prototype's prims, as instance proxies show them.
### Stage metadata
The set's detail attributes record:
- `usd.upAxis`;
- `usd.metersPerUnit`;
- `usd.time`.
`convert_units = true` rotates a Z-up stage to Y-up and scales it to
meters.
## Saving
Elements are grouped by their `path` text into prims at those paths, with
Xform ancestors. Elements without a path go under `/<root>/mesh`,
`/<root>/points`, `/<root>/curves` or `/<root>/instances`. When the whole
mesh is one prim, it keeps its point numbering, and its columns are written
without a copy.
Attributes are written back as primvars:
| Attribute domain | USD interpolation |
|---|---|
| point | vertex |
| corner | faceVarying |
| face | uniform |
| detail | constant |
Other details:
- **Names and types.** `Cd`, `Alpha`, `uv` and `N` get their USD names
back. Value types come from the scalar type, the width and the role (a
3-wide float color is `color3f[]`).
- **Unwritten values.** A prim whose share of an attribute is all zero does
not get that primvar: merging filled zeros there.
- **Groups** become GeomSubsets. `hole` becomes `holeIndices`.
- **Subdivision.** `subdivisionScheme` is always written: absent `subd.*`
means `none`. Creases are written as two-point chains.
- **Materials.**
- One material per prim becomes a `material:binding` on the prim.
- Several materials become `materialBind` subsets, one per material,
declared `nonOverlapping`.
- Materials themselves are not written.
- **Curves** go to one prim per kind, open or closed:
- poly as linear;
- Bezier as cubic bezier, with the handles between the points;
- uniform order-4 NURBS as bspline;
- other NURBS as NurbsCurves, with explicit knots;
- Catmull-Rom as pinned catmullRom.
- **Instances** become a PointInstancer whose prototypes sit under its
`Prototypes` scope; the rows' `path` attribute becomes `primvars:path`
(vertex interpolation), so a trip keeps each instance's path.
- **CAD** (luce-cad models) becomes one NurbsPatch per face, under the prim
the face's path names (else `cad` under the root prim):
- the support converted exactly: a plane as a bilinear patch over its trim
box; cylinders, cones, spheres and tori as rational quadratic surfaces of
revolution (arcs of at most 90 degrees); B-spline supports keep their
net and knots;
- trims as closed order-2 `trimCurve` loops in the patch's parameters,
sampled at the display tessellation's edge stations (outer loop
counterclockwise, holes clockwise); a pointed cone closes through its
apex, a hemisphere through its pole;
- `orientation` is `leftHanded` where the face's normal opposes the
surface's.
- **Stage metadata.** `upAxis` and `metersPerUnit` come from the set's
`usd.*` detail, defaulting to Y and 1. The first root prim becomes the
`defaultPrim`.
## What does not survive a round trip
- **Local transforms.** Points are baked to world space, so the Xforms are
written as identity.
- **Time samples.** One time is loaded.
- **Attributes on prims that lacked them.** Values filled in by merging
(zeros) are left out on save, so these stay absent. A constant that
differed between prims comes back uniform.
- **Subdivision schemes that differ between prims.** The merged mesh holds
one scheme.
- **Unconverted prims.** Materials, shaders, cameras, lights, skeletons and
composition arcs are not converted. `Usd.convert` keeps them, since it
works on layers.
- **Components with no USD form.** Volumes and SDFs are left out.
- **CAD.** Faces are written as independent NurbsPatch prims: shared edges
and the B-rep's topology are not, trims are polylines (exact trim curves
come later), and NurbsPatch prims are not imported yet.