Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-geocore

Source of release 0.7.8

0.7.8 / src / core / attributes.lucb

## Typed attributes over shared columns. An attribute is a name, a domain, a
## scalar type and a tuple width, and one column of bytes: `width` values per
## element (array storage) or one tuple for the whole domain (single storage,
## O(1) to add). Snapshots share every column; changing one attribute writes
## that column alone.
##
## A group is a boolean attribute flagged as a group (Houdini's element
## groups): its bits are the members. Text attributes store an i32 index per
## element into a string table (strings.lucb) shared like any column. A role
## says how geometric operations treat the values (Houdini's type info):
## transforms move positions and vectors, turn normals and rotations, and
## leave the rest.
from luce_std import math
import memory
import errors
from core.shared import Column
from core.growing import Growing
from core.strings import table_text
from core.limits import max_corners

## Element domains. The numbers are the ones callers pass as integers.
pub enum Domain as u8:
    point = 0
    corner = 1
    face = 2
    detail = 3
    edge = 4

## How many domains there are.
pub let domain_count: usize = 5

## Scalar component types. Booleans are packed bits, 64 per u64 word.
pub enum DataType as u8:
    boolean = 0
    int8 = 1
    int32 = 2
    int64 = 3
    float32 = 4
    float64 = 5
    ## An i32 index into the attribute's string table.
    text = 6

## How geometric operations treat an attribute's values.
pub enum Role as u8:
    generic = 0
    ## A point in space: transformed with the geometry.
    position = 1
    ## A direction with length: rotated and scaled.
    vector = 2
    ## A unit direction: inverse-transposed and renormalized.
    normal = 3
    color = 4
    uv = 5
    ## An element or class id: copied, never interpolated.
    index = 6
    ## A unit quaternion x, y, z, w (Houdini's `orient`): turned by the
    ## rotation of a transform's polar decomposition.
    rotation = 7

## Attribute flags.
pub let group_flag: u8 = 1

## The role an attribute gets by its name when none is given.
pub func role_of(name: str) -> Role:
    if name == "N": return Role.normal
    if name == "Cd": return Role.color
    if name == "uv": return Role.uv
    if name == "v" or name == "up": return Role.vector
    if name == "id" or name == "class": return Role.index
    if name == "orient": return Role.rotation
    return Role.generic

## An element per tuple (array), one tuple for the whole domain (single), or a list of
## tuples per element (ragged: Houdini's array attributes, f[]@ i[]@ v[]@), its items
## packed in `data` and each element's range in `offsets`.
pub enum Storage as u8:
    array = 0
    single = 1
    ragged = 2

## Bytes of one scalar of `kind`; 0 for packed booleans.
pub func scalar_bytes(kind: DataType) -> usize:
    match kind:
        .int8: return 1
        .int32, .float32, .text: return 4
        .int64, .float64: return 8
        _: return 0

## Whether `kind` holds whole numbers (booleans included).
pub func is_integer(kind: DataType) -> bool:
    return kind == DataType.boolean or kind == DataType.int8 or kind == DataType.int32 or kind == DataType.int64

## Names are 1..64 bytes; "P" belongs to the positions.
pub func check_name(name: str) -> !:
    if name.length == 0 or name.length > 64 or name == "P":
        error(errors.invalid, "attribute needs a nonreserved name of 1..64 bytes")

## One named attribute on a domain: tuples of 1..4 scalars in a shared
## column (bits for booleans), or one tuple with single storage.
pub struct Attribute:
    var label: u8[64]
    var label_length: usize
    ## The domain its elements belong to.
    pub var domain: Domain
    ## The scalar type.
    pub var kind: DataType
    ## Scalars per tuple, 1..4.
    pub var width: usize
    ## A tuple per element, or one for all.
    pub var storage: Storage
    ## Elements covered: the domain's size (1 for single storage).
    pub var elements: usize
    ## The tuples, packed.
    pub var data: Column[u8]
    ## `group_flag` marks a group (a boolean attribute).
    pub var flags: u8 = 0
    ## How operations transform its values.
    pub var role: Role = Role.generic
    ## The string table of a text attribute; empty otherwise.
    pub var table: Column[u8]
    ## A ragged attribute's item ranges: element i's items are offsets[i]..<offsets[i + 1]
    ## (u32 each, elements + 1 of them); empty otherwise.
    pub var offsets: Column[u8]

    ## An attribute whose column the caller fills: `elements` tuples, or one
    ## tuple for single storage. Booleans need width 1.
    pub static func create(name: str, domain: Domain, kind: DataType, width: usize, elements: usize, storage: Storage = Storage.array) -> Attribute!:
        try check_name(name)
        if width < 1 or width > 4 or ((kind == DataType.boolean or kind == DataType.text) and width != 1):
            error(errors.invalid, "attribute tuples have 1..4 components; booleans and text have one")
        if storage == Storage.ragged:
            error(errors.invalid, "an array attribute is made by Attribute.ragged")
        let stored = 1 if storage == Storage.single else elements
        let bytes = (stored + 63) // 64 * 8 if kind == DataType.boolean else stored * width * scalar_bytes(kind)
        var label: u8[64]
        memory.copy(label[..<name.length], name.bytes, name.length)
        var empty: Column[u8]
        return Attribute(label, name.length, domain, kind, width, storage, elements, try Column[u8].allocate(bytes), 0, role_of(name), empty)

    ## A group of `elements` on `domain`, with no members yet (every bit zero).
    pub static func group(name: str, domain: Domain, elements: usize) -> Attribute!:
        var attribute = try Attribute.create(name, domain, DataType.boolean, 1, elements)
        let bytes = attribute.data.span()
        if bytes.length > 0: memory.set(bytes, 0)
        attribute.flags = group_flag
        return attribute

    ## A group whose members are the bits of `words` (`elements` of them).
    pub static func group_of(name: str, domain: Domain, elements: usize, words: const u64[]) -> Attribute!:
        var attribute = try Attribute.group(name, domain, elements)
        let bytes = attribute.data.span()
        memory.copy(bytes, u8[]((u8*)words.data, words.length * 8), bytes.length)
        return attribute

    ## A text attribute: element i is string `values[i]` of `table` (which it
    ## shares), or one value for the domain with single storage.
    pub static func text(name: str, domain: Domain, elements: usize, table: Column[u8], values: const i32[], storage: Storage = Storage.array) -> Attribute!:
        var attribute = try Attribute.create(name, domain, DataType.text, 1, elements, storage)
        let out = typed_mut_i32(attribute.data.span())
        memory.copy(out, values, out.length)
        attribute.table = table.share()
        return attribute

    ## From f64 tuples: integers become int32 (int64 when out of range), and
    ## other numbers float64, so every value reads back exactly.
    ## `float32` stores non-integer values as f32 (half the bytes; about 7
    ## significant digits), as display and analysis attributes want.
    pub static func from_numbers(name: str, domain: Domain, width: usize, values: const f64[], integer: bool, storage: Storage = Storage.array, float32: bool = false) -> Attribute!:
        if width < 1 or width > 4 or values.length % width != 0:
            error(errors.invalid, "attribute needs a tuple size of 1..4 dividing its values")
        if values.length // width > max_corners:
            error(errors.limit, "an attribute is limited to 32M tuples, the largest domain")
        var wide = false
        if integer:
            for value in values:
                if not (math.abs(value) <= 9007199254740991.0) or math.floor(value) != value:
                    error(errors.invalid, "attribute values must be finite and integer values exactly representable")
                wide = wide or value < -2147483648.0 or value > 2147483647.0
        else:
            for value in values:
                if not math.is_finite(value) or (float32 and math.abs(value) > 3.4e38):
                    error(errors.invalid, "attribute values must be finite and integer values exactly representable")
        let kind = (DataType.int64 if wide else DataType.int32) if integer else (DataType.float32 if float32 else DataType.float64)
        let tuples = values.length // width
        var attribute = try Attribute.create(name, domain, kind, width, tuples if storage == Storage.array else 0, storage)
        let stored = attribute.data.span()
        let count = width if storage == Storage.single else values.length
        match kind:
            .int32:
                let output = i32[]((i32*)stored.data, count)
                for at in 0..<count: output[at] = (i32)values[at]
            .int64:
                let output = i64[]((i64*)stored.data, count)
                for at in 0..<count: output[at] = (i64)values[at]
            .float32:
                let output = f32[]((f32*)stored.data, count)
                for at in 0..<count: output[at] = (f32)values[at]
            _: memory.copy(f64[]((f64*)stored.data, count), values[..<count], count)
        return attribute

    ## A ragged (array) attribute over `elements` = offsets.count / 4 - 1 elements: f32 or
    ## i32 items (`kind` float32 or int32), each of `width` 1 or 3 components (3: vectors),
    ## `values` holding every element's items in order. Takes both columns' shares.
    pub static func ragged(name: str, domain: Domain, kind: DataType, width: usize, offsets: Column[u8], values: Column[u8]) -> Attribute!:
        try check_name(name)
        if (kind != DataType.float32 and kind != DataType.int32) or (width != 1 and width != 3):
            error(errors.invalid, "array attributes hold f32 or i32 items of 1 or 3 components")
        let bounds = offsets.view()
        if bounds.length < 4 or bounds.length % 4 != 0:
            error(errors.invalid, "array attribute offsets need one more entry than elements")
        let elements = bounds.length // 4 - 1
        let last = (usize)memory.read[u32]((void*)&bounds[elements * 4])
        if last * width * 4 != values.view().length:
            error(errors.invalid, "array attribute values do not match their offsets")
        var label: u8[64]
        memory.copy(label[..<name.length], name.bytes, name.length)
        var empty: Column[u8]
        var attribute = Attribute(label, name.length, domain, kind, width, Storage.ragged, elements, values, 0, Role.generic, empty)
        attribute.offsets = offsets
        return attribute

    ## Whether it is an array attribute (ragged storage).
    pub func is_ragged() -> bool:
        return self.storage == Storage.ragged

    ## How many items element `element` of an array attribute has (0 otherwise).
    pub func item_count(element: usize) -> usize:
        if self.storage != Storage.ragged: return 0
        let bounds = self.offsets.view()
        return (usize)(memory.read[u32]((void*)&bounds[(element + 1) * 4]) - memory.read[u32]((void*)&bounds[element * 4]))

    ## The first item of element `element` of an array attribute.
    pub func first_item(element: usize) -> usize:
        return (usize)memory.read[u32]((void*)&self.offsets.view()[element * 4])

    ## Component `component` of item `index` of element `element` of an array attribute.
    pub func item(element: usize, index: usize, component: usize) -> f64:
        let at = (self.first_item(element) + index) * self.width + component
        let bytes = self.data.view()
        if self.kind == DataType.int32: return (f64)memory.read[i32]((void*)&bytes[at * 4])
        return (f64)memory.read[f32]((void*)&bytes[at * 4])

    ## The attribute's name.
    pub func name() -> str:
        return (str)self.label[..<self.label_length]

    ## Whether it is a group (a flagged boolean attribute).
    pub func is_group() -> bool:
        return self.flags & group_flag != 0

    ## The text of element `element` of a text attribute ("" otherwise).
    pub func text_at(element: usize) -> str:
        if self.kind != DataType.text: return ""
        let index = memory.read[i32]((void*)&self.data.view()[(0 if self.storage == Storage.single else element) * 4])
        return table_text(self.table.view(), (usize)index) if index >= 0 else ""

    ## Whether its scalars are whole numbers.
    pub func integer() -> bool:
        return is_integer(self.kind)

    ## Component `component` of element `element`, as f64. Single storage
    ## answers its one tuple for every element.
    pub func number(element: usize, component: usize) -> f64:
        # An array attribute answers its first item (0 for an empty array).
        if self.storage == Storage.ragged:
            return self.item(element, 0, component) if self.item_count(element) > 0 else 0.0
        let index = (0 if self.storage == Storage.single else element) * self.width + component
        let bytes = self.data.view()
        match self.kind:
            .boolean: return 1.0 if (bytes[index // 8] >> (u8)(index % 8)) & 1 != 0 else 0.0
            .int8: return (f64)(i8)bytes[index]
            .int32, .text: return (f64)memory.read[i32]((void*)&bytes[index * 4])
            .int64: return (f64)memory.read[i64]((void*)&bytes[index * 8])
            .float32: return (f64)memory.read[f32]((void*)&bytes[index * 4])
            _: return memory.read[f64]((void*)&bytes[index * 8])

    ## Bytes of one tuple; 0 for bits.
    pub func tuple_bytes() -> usize:
        return self.width * scalar_bytes(self.kind)

    ## Another owner of the same attribute: shares its column.
    pub func share() -> Attribute:
        var copy = self
        copy.data = self.data.share()
        copy.table = self.table.share()
        copy.offsets = self.offsets.share()
        return copy

    ## The same attribute under another name.
    pub func renamed(name: str) -> Attribute!:
        try check_name(name)
        var copy = self.share()
        memory.copy(copy.label[..<name.length], name.bytes, name.length)
        copy.label_length = name.length
        return copy

    ## Release this owner's share of the columns.
    pub func release():
        self.data.release()
        self.table.release()
        self.offsets.release()

## i32 values of a column's bytes; columns are 64-byte aligned.
func typed_mut_i32(bytes: u8[]) -> i32[]:
    return i32[]((i32*)bytes.data, bytes.length // 4)

## The attributes of one mesh. (name, domain) pairs are unique; Cd, uv and N
## are found once per change, not per element.
pub struct AttributeStore:
    var entries: Growing[Attribute]
    ## Index of Cd per domain, or -1.
    pub var colors: i64[5]
    ## Index of uv per domain, or -1.
    pub var uvs: i64[5]
    ## Index of N per domain, or -1.
    pub var normals: i64[5]

    ## An empty store.
    pub func init():
        self.entries = Growing[Attribute]()
        self.colors = [-1, -1, -1, -1, -1]
        self.uvs = [-1, -1, -1, -1, -1]
        self.normals = [-1, -1, -1, -1, -1]

    ## How many attributes there are.
    pub func count() -> usize:
        return self.entries.count

    ## Attribute `index`, valid until the store changes.
    pub func entry(index: usize) -> const Attribute*:
        return &self.entries.items[index]

    ## The index of attribute `name` on `domain`, or -1.
    pub func find(name: str, domain: Domain) -> i64:
        for index in 0..<self.entries.count:
            let entry = &self.entries.items[index]
            if entry.domain == domain and entry.name() == name:
                return (i64)index
        return -1

    ## Add `attribute` (taking its share), replacing one of the same name and
    ## domain. On failure the store is unchanged and the share released.
    pub func put(attribute: Attribute) -> !:
        var owned = attribute
        let found = self.find(owned.name(), owned.domain)
        if found >= 0:
            self.entries.items[(usize)found].release()
            self.entries.items[(usize)found] = owned
        else:
            self.entries.push(owned) catch failure:
                owned.release()
                error(failure.code, failure.message)
        self.reindex()

    ## The column of attribute `index`, written copy-on-write: other owners of
    ## it keep their contents.
    pub func writable(index: usize) -> u8[]!:
        return try self.entries.items[index].data.writable()

    ## After `writable`: only tuples first..<end of attribute `index` differ
    ## from the column it was written from.
    pub func set_changed(index: usize, first: usize, end: usize):
        let entry = &self.entries.items[index]
        if entry.storage == Storage.ragged:
            # Item ranges do not follow element numbers: the whole column changed.
            entry.data.set_changed(0, entry.data.bytes())
            return
        let tuple = entry.tuple_bytes()
        entry.data.set_changed(first * tuple, end * tuple)

    ## Remove attribute `index`, releasing its share.
    pub func remove(index: usize):
        self.entries.items[index].release()
        for at in index + 1..<self.entries.count:
            self.entries.items[at - 1] = self.entries.items[at]
        self.entries.count -= 1
        self.reindex()

    ## A store sharing every column: O(attributes), no element copies.
    pub func shared() -> AttributeStore!:
        var copy = AttributeStore()
        try copy.entries.reserve(self.entries.count)
        for entry in self.entries.view():
            copy.entries.items[copy.entries.count] = entry.share()
            copy.entries.count += 1
        copy.colors = self.colors
        copy.uvs = self.uvs
        copy.normals = self.normals
        return copy

    func reindex():
        self.colors = [-1, -1, -1, -1, -1]
        self.uvs = [-1, -1, -1, -1, -1]
        self.normals = [-1, -1, -1, -1, -1]
        for index in 0..<self.entries.count:
            let entry = &self.entries.items[index]
            let domain = (usize)(u8)entry.domain
            # Display reads these as one tuple per element: arrays never qualify.
            if entry.storage == Storage.ragged: continue
            if entry.name() == "Cd": self.colors[domain] = (i64)index
            elif entry.name() == "uv": self.uvs[domain] = (i64)index
            elif entry.name() == "N": self.normals[domain] = (i64)index

    ## Bytes of every column, counting shared ones as if owned.
    pub func bytes() -> usize:
        var total: usize = 0
        for entry in self.entries.view(): total += entry.data.bytes() + entry.table.bytes() + entry.offsets.bytes()
        return total

    ## Release every attribute.
    pub func close():
        for index in 0..<self.entries.count: self.entries.items[index].release()
        self.entries.close()