Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-usd

Source of release 0.9.6

0.9.6 / docs / MAPPING.md

# 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.
- **BrepArray** (UsdSolid's draft schema) prims become CAD models, one per
  B-rep, placed by the prim's world transform: a face's outward side is the
  one its solid region's faceuse looks away from (a face no solid region
  uses is a sheet's); edges are lines when they are one, else B-splines;
  surfaces are planes, cylinders, cones, spheres and tori when their NURBS
  are the rational arcs of a surface of revolution (as this export writes
  them), else B-splines. Face names and paths come from `luce:faceName` and
  `luce:facePath`. A non-manifold B-rep, wire edges, point shells and the
  analytic shape APIs are refused with a warning naming the prim; NurbsPatch
  prims beside BrepArrays (the same faces) pass without one.
- **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 B-reps** (luce-cad models' boundaries) become UsdSolid `BrepArray`
  prims too (the AOUSD proposal's draft schema, `PrelimUsdSolid`; its names
  kept in `convert/solid_schema.lucb`), one per model, `cad/solid_<k>` under
  the root prim, beside the patches below:
  - topology as the Radial Edge model has it: the outside a void region;
    each lump a solid region (its outer shell, then any cavity's); each
    cavity a void region (a closed shell inside an odd number of others'
    boxes); a sheet's faces used on both sides by the outside; two faceuses
    per face, `same` on its surface's du x dv side; loops counterclockwise
    about that normal; an edge's two edgeuses each other's next;
  - shapes as NURBS (BrepPointAPI, BrepCurve3dNurbAPI, BrepSurfaceNurbAPI):
    vertices placed, edge curves from their start vertex to their end one
    (lines of order 2, arcs and ellipse arcs rational quadratics), faces'
    surfaces as the patches below (nets with U the rows); no trim curves
    (optional in the schema);
  - `brep:intersectTol3d` the model's tolerance or its widest tolerant
    edge's or vertex's; face names and paths in custom `luce:faceName` and
    `luce:facePath`.
- **CAD** (luce-cad models) also becomes one NurbsPatch per face, for
  readers without UsdSolid, 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.** A B-rep comes back from its `BrepArray` with its faces, names,
  edges and topology (lumps, cavities, sheets), its planes, cylinders, cones,
  spheres and tori analytic again; tolerant edges come back exact at the
  array's tolerance, face colors and placements' structure are not kept
  (shapes are placed), and standalone patches only as NurbsPatch prims,
  which are not imported (their trims are polylines). Non-manifold arrays
  (an edge with three or more face sides, wire edges, point shells) and the
  analytic shape APIs are refused with a warning naming the prim.