Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-usd

Source of release 0.9.5

0.9.5 / src / convert / particle_fields.lucb

## Gaussian splat prims (UsdVol's ParticleField3DGaussianSplat, OpenUSD 26.03;
## pxr/usd/usdVol/schema.usda) as luce-geocore's splat cloud: `orient`,
## `scale`, `opacity`, linear `Cd` and the `sh` bands (geocore
## splats/conventions.lucb). A generic ParticleField counts when it applies
## the Gaussian ellipsoid kernel.
##
## The schema's values are already what geocore keeps: scales are linear σ
## (the unit Gaussian kernel's), opacities linear 0..1, orientations unit
## quaternions. Each attribute has a half variant (`positionsh`, ...); the
## float one is preferred. An array shorter than the positions is ignored
## (unit scale, opacity 1, no rotation, a DC giving color 0.5) and a longer
## one is cut to them.
##
## Radiance: `radiance:sphericalHarmonicsCoefficients` holds (d + 1)² RGB
## coefficients per particle, DC first, in 3DGS's order and signs: 3DGS's raw
## SH, the DC a PLY's f_dc (color 0.5 + C0 · f_dc) and the rest its f_rest,
## one RGB item per coefficient. The schema's text leaves this open; OpenUSD's
## own reference code settles it (extras/imaging/examples/hdParticleField:
## py3dgsPlyToUsd.py writes f_dc as coefficient 0 and f_rest transposed to
## coefficient-major, gsRenderer.cpp shows C0 · c₀ + 0.5 and fills (0, 0, 0)
## for "DC (0.5, 0.5, 0.5)"; third_party/renderman's
## SphericalHarmonicsToColor.osl agrees), as do Autodesk's arnold-usd and
## LichtFeld Studio. Missing coefficients read as color 0.5. The colors are sRGB-encoded, as
## a trained capture's are, unless the prim says `luce:gsplatColorSpace =
## "linear"` (what this package writes for linear clouds); `Cd` is decoded to
## linear and the bands keep their encoding, as Bake GSplats does. Degrees
## above 3 keep bands 1 to 3, with a warning.
##
## A prim without coefficients (degree 0, as Houdini writes them) takes its
## color from `primvars:displayColor` (vertex or constant, indexed or not),
## which is linear like `Cd`; without either its color is 0.5.
##
## Each prim's splats are placed in world space exactly (covariances and SH
## through geocore's placed_point_store) and all prims join into the set's
## one point cloud, as meshes join into one mesh: each splat keeps its
## prim's path in the point text attribute `path`, and export writes one
## prim per path again. When every prim stored its positions as halves
## (`positionsh`), the detail `usd.halfSplats` says so and export writes
## halves back. The first prim's `sortingModeHint` and
## `projectionModeHint` become the detail texts `gsplat_sorting_mode` and
## `gsplat_projection_mode`, and its custom `luce:gsplatUpAxis` (written for
## a cloud stood up from a Y-down file) the detail `gsplat_up_axis`, so a
## later PLY export turns it back down.

## The splat attributes' names on a stage.
struct FieldNames:
    var positions: u32
    var positionsh: u32
    var orientations: u32
    var orientationsh: u32
    var scales: u32
    var scalesh: u32
    var opacities: u32
    var opacitiesh: u32
    var degree: u32
    var coefficients: u32
    var coefficientsh: u32
    var sorting: u32
    var projection: u32
    var color_space: u32
    var up_axis: u32
    var kernel: u32
    var display_color: u32

    static func of(names: Names*) -> FieldNames!:
        return FieldNames(
            positions = try names.token("positions"), positionsh = try names.token("positionsh"),
            orientations = try names.token("orientations"), orientationsh = try names.token("orientationsh"),
            scales = try names.token("scales"), scalesh = try names.token("scalesh"),
            opacities = try names.token("opacities"), opacitiesh = try names.token("opacitiesh"),
            degree = try names.token("radiance:sphericalHarmonicsDegree"),
            coefficients = try names.token("radiance:sphericalHarmonicsCoefficients"),
            coefficientsh = try names.token("radiance:sphericalHarmonicsCoefficientsh"),
            sorting = try names.token("sortingModeHint"), projection = try names.token("projectionModeHint"),
            color_space = try names.token("luce:gsplatColorSpace"),
            up_axis = try names.token("luce:gsplatUpAxis"),
            kernel = try names.token("ParticleFieldKernelGaussianEllipsoidAPI"),
            display_color = try names.token("primvars:displayColor"))

## The splats of a stage's particle fields, and the hints they carry.
struct SplatImport:
    var cloud: PointCloud*?
    var sorting: u32
    var projection: u32
    var space: ColorSpace
    ## The `luce:gsplatUpAxis` token (0 when unauthored).
    var up_axis: u32
    ## Prims read, and whether every one stored half positions.
    var prims: usize
    var half: bool

    func close():
        if let made = self.cloud: close_point_cloud(made)
        self.cloud = none

func close_point_cloud(cloud: PointCloud*):
    let close = points_component().close
    close((void*)cloud)

## Every particle field prim of `gathered` as one splat cloud (none without
## any).
func import_splats(stage: Stage*, gathered: const Gathered*, warnings: Warnings*) -> SplatImport!:
    var result = SplatImport(cloud = none, sorting = 0, projection = 0, space = ColorSpace.srgb, up_axis = 0, prims = 0, half = true)
    errdefer result.close()
    let fields = try FieldNames.of(stage.names)
    for index in 0..<gathered.gprims.count:
        let gprim = gathered.gprims.items[index]
        if gprim.kind != GprimKind.particle_field: continue
        if not gaussian_field(stage, gprim.path, &fields):
            try warnings.add_path("Skipped a ParticleField without the Gaussian ellipsoid kernel: ", stage.names, gprim.path)
            continue
        let made = (try field_cloud(stage, &gprim, index, gathered.anchor, &fields, &result, warnings)) else continue
        if result.cloud == none:
            result.cloud = made
            continue
        let held = result.cloud else continue
        let join = points_component().joined
        let joined = join((void*)held, (void*)made) catch failure:
            close_point_cloud(made)
            error(failure.code, failure.message)
        close_point_cloud(made)
        close_point_cloud(held)
        result.cloud = (PointCloud*)joined
    return result

## Whether the prim at `path` is a 3DGS splat field: the concrete schema, or
## a ParticleField applying the Gaussian ellipsoid kernel.
func gaussian_field(stage: const Stage*, path: u32, fields: const FieldNames*) -> bool:
    let spec = stage.spec(path) else return false
    if stage.type_of(spec) == stage.tokens.particle_field_splat: return true
    let applied = spec.get(stage.keys.api_schemas) else return false
    let list = applied.list_op() else return false
    for part in [ListPart.explicit, ListPart.prepended, ListPart.added, ListPart.appended]:
        for item in list.items(part):
            if (u32)item.a == fields.kernel: return true
    return false

## The array value of attribute `name` (or, unauthored, `half_name`).
func preferred(stage: Stage*, path: u32, name: u32, half_name: u32) -> Value!:
    var found = try stage.value(path, name)
    if found.array and found.count > 0: return found
    found.release()
    return try stage.value(path, half_name)

## Whether `value` holds at least `count` elements of `width` components.
func covers(value: const Value*, count: usize, width: usize) -> bool:
    return value.array and value.count >= count and components(value.kind) == width

## One prim's splats, placed in world space, each with the prim's path
## (relative to `anchor`); none when it has no positions. `index` is the
## gprim's in its gathering.
func field_cloud(stage: Stage*, gprim: const Gprim*, index: usize, anchor: u32, fields: const FieldNames*, result: SplatImport*, warnings: Warnings*) -> PointCloud*?!:
    let path = gprim.path
    var positions = try preferred(stage, path, fields.positions, fields.positionsh)
    defer positions.release()
    if not positions.array or components(positions.kind) != 3 or positions.count == 0: return none
    let count = positions.count
    result.half = result.half and scalar_of(positions.kind) == ValueKind.half
    var work: SplatRead
    work.count = count
    work.orientations = try preferred(stage, path, fields.orientations, fields.orientationsh)
    defer work.orientations.release()
    work.scales = try preferred(stage, path, fields.scales, fields.scalesh)
    defer work.scales.release()
    work.opacities = try preferred(stage, path, fields.opacities, fields.opacitiesh)
    defer work.opacities.release()
    work.coefficients = try preferred(stage, path, fields.coefficients, fields.coefficientsh)
    defer work.coefficients.release()
    work.has_orientations = covers(&work.orientations, count, 4)
    work.has_scales = covers(&work.scales, count, 3)
    work.has_opacities = covers(&work.opacities, count, 1)
    let degree_value = try stage.number_value(path, fields.degree, 3.0)
    let degree = (usize)math.clamp(math.round(degree_value), 0.0, 16.0)
    work.per_particle = (degree + 1) * (degree + 1)
    work.has_coefficients = covers(&work.coefficients, count * work.per_particle, 3)
    # Without coefficients (Houdini's degree 0): displayColor, linear.
    var display = PrimvarSource(source = index, name = 0, value = Value.marker(ValueKind.empty), indices = Value.marker(ValueKind.empty), domain = Domain.detail,
                                kind = DataType.float64, width = 0, element_size = 1, role = usd_types.Role.generic)
    defer display.release()
    if not work.has_coefficients:
        let slot = PrimSlot(path = path, gprim = index, points = count, faces = 0, corners = 0)
        if let found = try read_primvar(stage, &slot, index, try stage.names.property(path, fields.display_color), false, warnings):
            display = found
            if display.width == 3 and (display.domain == Domain.point or display.domain == Domain.detail): work.display = &display
    if work.has_coefficients and degree > 3: try warnings.add("Spherical harmonics past degree 3 were dropped (bands 1 to 3 kept)")
    let kept = degree if degree < 3 else 3
    work.items = sh_count(kept) if work.has_coefficients else 0
    # The first prim's hints and color space stand for the cloud.
    result.prims += 1
    if result.cloud == none:
        result.sorting = try stage.token_value(path, fields.sorting, 0)
        result.projection = try stage.token_value(path, fields.projection, 0)
        result.up_axis = try stage.token_value(path, fields.up_axis, 0)
        let space = try stage.token_value(path, fields.color_space, 0)
        if space != 0 and stage.names.text_of(space) == "linear": result.space = ColorSpace.linear
    work.space = result.space
    var store = AttributeStore()
    defer store.close()
    try store.put(try float32_points(orient_name, 4, count))
    try store.put(try float64_points(scale_name, 3, count))
    try store.put(try float64_points(opacity_name, 1, count))
    try store.put(try float64_points(color_name, 3, count))
    work.orient = float32_values(store.entry(0))
    work.scale = float64_values(store.entry(1))
    work.opacity = float64_values(store.entry(2))
    work.color = float64_values(store.entry(3))
    if work.items > 0:
        try store.put(try uniform_sh(none, count, work.items))
        work.sh = f32[]((f32*)store.entry(4).data.span().data, count * work.items * 3)
    try parallel.for_each_range(count, grain, (void*)&work, read_splats)
    # Placed in world space: positions over an origin, the rest exactly.
    var world = Matrix4(Vector3(gprim.world.m[0], gprim.world.m[1], gprim.world.m[2]), Vector3(gprim.world.m[4], gprim.world.m[5], gprim.world.m[6]), Vector3(gprim.world.m[8], gprim.world.m[9], gprim.world.m[10]), Vector3(gprim.world.m[12], gprim.world.m[13], gprim.world.m[14]))
    var placed = try placed_point_store(&store, count, world)
    try_path(stage, path, anchor, count, &placed) catch failure:
        placed.close()
        error(failure.code, failure.message)
    var located = place_splat_positions(&positions, &gprim.world) catch failure:
        placed.close()
        error(failure.code, failure.message)
    # cloud_assembled takes the positions and the store, even on failure.
    return try cloud_assembled(located.0, located.1, placed)

## Point text attribute `path`: the prim's path (from `anchor`) on all
## `count` splats, as meshes and Points keep theirs.
func try_path(stage: Stage*, path: u32, anchor: u32, count: usize, store: AttributeStore*) -> !:
    var text = Growing[u8]()
    defer text.close()
    try write_element_path(stage.names, path, anchor, &text)
    var table = TableBuilder()
    defer table.close()
    _ = try table.intern((str)text.view())
    var column = try table.finish()
    defer column.release()
    var rows = try Column[i32].filled(count, 0)
    defer rows.release()
    try store.put(try Attribute.text("path", Domain.point, count, column, rows.span()))

## The positions of `value` placed by `world` over an origin (geocore's rule).
func place_splat_positions(value: const Value*, world: const Matrix4d*) -> (Column[Float3], Vector3)!:
    let count = value.count
    let bytes = value.bytes()
    let scalar = scalar_of(value.kind)
    var low = Vector3(math.infinity, math.infinity, math.infinity)
    var high = Vector3(-math.infinity, -math.infinity, -math.infinity)
    for at in 0..<count:
        let p = world.point(component_at(bytes, scalar, at * 3), component_at(bytes, scalar, at * 3 + 1), component_at(bytes, scalar, at * 3 + 2))
        low = Vector3(math.min(low.x, p.0), math.min(low.y, p.1), math.min(low.z, p.2))
        high = Vector3(math.max(high.x, p.0), math.max(high.y, p.1), math.max(high.z, p.2))
    let origin = origin_for(low, high)
    var column = try Column[Float3].allocate(count)
    var work = PositionWork(bytes = bytes, scalar = scalar, world = world, origin = origin, out = column.span())
    parallel.for_each_range(count, grain, (void*)&work, place_range) catch failure:
        column.release()
        error(failure.code, failure.message)
    return (column, origin)

struct PositionWork:
    var bytes: const u8[]
    var scalar: ValueKind
    var world: const Matrix4d*
    var origin: Vector3
    var out: Float3[]

func place_range(context: void*, first: usize, end: usize, worker: usize):
    _ = worker
    let work = (PositionWork*)context
    for at in first..<end:
        let p = work.world.point(component_at(work.bytes, work.scalar, at * 3), component_at(work.bytes, work.scalar, at * 3 + 1), component_at(work.bytes, work.scalar, at * 3 + 2))
        work.out[at] = Float3((f32)(p.0 - work.origin.x), (f32)(p.1 - work.origin.y), (f32)(p.2 - work.origin.z))

## A prim's splat arrays and the columns they fill.
struct SplatRead:
    var count: usize
    var orientations: Value
    var scales: Value
    var opacities: Value
    var coefficients: Value
    var has_orientations: bool
    var has_scales: bool
    var has_opacities: bool
    var has_coefficients: bool
    ## `primvars:displayColor` (3 wide, vertex or constant), for a prim
    ## without coefficients.
    var display: const PrimvarSource*?
    ## Coefficients per particle in the file, and SH items kept.
    var per_particle: usize
    var items: usize
    var space: ColorSpace
    var orient: f32[]
    var scale: f64[]
    var opacity: f64[]
    var color: f64[]
    var sh: f32[]

func read_splats(context: void*, first: usize, end: usize, worker: usize):
    _ = worker
    let work = (SplatRead*)context
    let orientations = work.orientations.bytes()
    let quaternion = scalar_of(work.orientations.kind)
    let scales = work.scales.bytes()
    let sigma = scalar_of(work.scales.kind)
    let opacities = work.opacities.bytes()
    let alpha = scalar_of(work.opacities.kind)
    let coefficients = work.coefficients.bytes()
    let radiance = scalar_of(work.coefficients.kind)
    for at in first..<end:
        # Gf packs quaternions imaginary first: x, y, z, w, as geocore keeps them.
        for k in 0..<(usize)4:
            work.orient[at * 4 + k] = (f32)component_at(orientations, quaternion, at * 4 + k) if work.has_orientations else (1.0 if k == 3 else 0.0)
        for k in 0..<(usize)3: work.scale[at * 3 + k] = component_at(scales, sigma, at * 3 + k) if work.has_scales else 1.0
        work.opacity[at] = component_at(opacities, alpha, at) if work.has_opacities else 1.0
        let base = at * work.per_particle * 3
        var dc = Vector3()
        if work.has_coefficients: dc = Vector3(component_at(coefficients, radiance, base), component_at(coefficients, radiance, base + 1), component_at(coefficients, radiance, base + 2))
        var linear = color_of_dc(dc, work.space)
        if let shown = work.display: linear = display_color_at(shown, at)
        work.color[at * 3] = linear.x
        work.color[at * 3 + 1] = linear.y
        work.color[at * 3 + 2] = linear.z
        for value in 0..<work.items * 3: work.sh[at * work.items * 3 + value] = (f32)component_at(coefficients, radiance, base + 3 + value)

## Splat `at`'s displayColor: its own (vertex) or the prim's (constant),
## through the indices when there are some.
func display_color_at(display: const PrimvarSource*, at: usize) -> Vector3:
    var element = at if display.domain == Domain.point else 0
    if display.indices.array and display.indices.count > 0: element = (usize)ints_of(&display.indices)[element]
    let bytes = display.value.bytes()
    let scalar = scalar_of(display.value.kind)
    if not display.value.array: element = 0
    return Vector3(component_at(bytes, scalar, element * 3), component_at(bytes, scalar, element * 3 + 1), component_at(bytes, scalar, element * 3 + 2))

## The splat cloud's detail: its color space, the schema's hints, the up
## axis its source file had and whether it stored halves.
func put_splat_details(set: GeometrySet*, stage: const Stage*, splats: const SplatImport*) -> !:
    if splats.half and splats.prims > 0:
        let one: f64[1] = [1.0]
        try set_put_detail(set, try Attribute.from_numbers(half_splats_name, Domain.detail, 1, one[..<1], false))
    if splats.up_axis != 0: try put_detail_token(set, up_axis_name, stage.names.text_of(splats.up_axis))
    try put_detail_token(set, color_space_name, color_space_text(splats.space))
    try put_detail_token(set, "gsplat_sorting_mode", stage.names.text_of(splats.sorting) if splats.sorting != 0 else "zDepth")
    try put_detail_token(set, "gsplat_projection_mode", stage.names.text_of(splats.projection) if splats.projection != 0 else "perspective")

## Detail text attribute `name` = `value`.
func put_detail_token(set: GeometrySet*, name: str, value: str) -> !:
    var table = TableBuilder()
    defer table.close()
    let at: i32[1] = [try table.intern(value)]
    var column = try table.finish()
    defer column.release()
    try set_put_detail(set, try Attribute.text(name, Domain.detail, 1, column, at[..<1]))

## The detail recording that a stage's splats were stored as halves.
let half_splats_name: str = "usd.halfSplats"