Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-geocore

Source of release 0.7.4

0.7.4 / src / geometries / polygon / access.lucb

## Element access, per-corner vertices, lazy topology caches and
## spatial queries.

## Domains in the order a corner's color, uv and N are looked up, later
## ones winning: detail, face, point, corner (Houdini's precedence).
let lookup_order: usize[4] = [3, 2, 0, 1]

extend Mesh:
    ## A cube of edge `size` centered on the origin.
    pub static func cube(size: f64 = 2.0) -> interop.Reference[Mesh]!:
        if not (size > 0.0 and size <= 100000.0):
            error(errors.invalid, "cube size must be in (0,100000]")
        let h = size * 0.5
        let points: Vector3[8] = [Vector3(-h, 0.0, -h), Vector3(h, 0.0, -h), Vector3(h, size, -h), Vector3(-h, size, -h),
                                  Vector3(-h, 0.0, h), Vector3(h, 0.0, h), Vector3(h, size, h), Vector3(-h, size, h)]
        let sizes: i64[6] = [4, 4, 4, 4, 4, 4]
        let corners: i64[24] = [1, 2, 6, 5, 4, 7, 3, 0, 3, 7, 6, 2, 0, 1, 5, 4, 5, 6, 7, 4, 0, 3, 2, 1]
        return try make_mesh(points, sizes, corners)

    ## A mesh with no points or faces.
    pub static func empty() -> interop.Reference[Mesh]!:
        var points: Vector3[]
        var sizes: i64[]
        var corners: i64[]
        return try make_mesh(points, sizes, corners)

    ## How many points the mesh has.
    pub func point_count() -> i64:
        return (i64)self.positions.count()

    ## The change id of the positions column: equal ids mean the same
    ## positions. A mesh sharing a cloud's points (SplatEdits.pick_mesh) has
    ## the cloud's id, which tells which drawn cloud it picks on.
    pub func positions_id() -> i64:
        return (i64)(self.positions.id() >> 1)

    ## How many faces the mesh has.
    pub func face_count() -> i64:
        return (i64)self.offsets.count() - 1

    ## How many corners (the renderer's vertices) the mesh has.
    pub func vertex_count() -> i64:
        return (i64)self.corners.count()

    ## How many display triangle indices the mesh has.
    pub func index_count() -> i64:
        return (i64)self.triangles.count()

    ## Edges are derived on first use, which can fail for memory.
    pub func edge_count() -> i64!:
        return (i64)(try self.edge_arrays()).0.length // 2

    ## The axis-aligned box of the points, in world space.
    pub func bounds() -> Bounds:
        return self.extent

    ## Nonzero 64-bit connectivity hash (bit pattern as a signed integer).
    pub func topology_hash() -> i64:
        return (i64)self.topology.connectivity_hash(self.offsets.view(), self.corners.view(), self.positions.count())

    ## The elements of domain `domain` (0 points, 1 corners, 2 faces, 3
    ## detail, 4 edges).
    pub func domain_count(domain: i64) -> i64!:
        if domain < 0 or domain > 4:
            error(errors.invalid, "unknown attribute domain")
        return (i64)(try self.domain_size(Domain((u8)domain)))

    ## `domain_count` for Base callers.
    pub func domain_size(domain: Domain) -> usize!:
        match domain:
            .point: return self.positions.count()
            .corner: return self.corners.count()
            .face: return self.offsets.count() - 1
            .edge: return (usize)(try self.edge_count())
            _: return 1

    ## The face of each corner, built on first use.
    func corner_faces() -> const i32[]!:
        return try self.topology.faces(self.offsets.view(), self.corners.count())

    ## Edge endpoints (two per edge) and each corner's edge, built on first use.
    func edge_arrays() -> (const i32[], const i32[])!:
        return try self.topology.edges(self.offsets.view(), self.corners.view(), self.positions.count())

    ## Faces around each point, built on first use.
    func incidence() -> (const i32[], const i32[])!:
        return try self.topology.incidence(self.offsets.view(), self.corners.view(), self.positions.count())

    ## The point of corner `corner`.
    pub func corner_point(corner: i64) -> i64!:
        try checked(corner, self.corners.count())
        return (i64)self.corners.view()[(usize)corner]

    ## The face corner `corner` belongs to.
    pub func corner_face(corner: i64) -> i64!:
        try checked(corner, self.corners.count())
        return (i64)(try self.corner_faces())[(usize)corner]

    ## The edge leaving corner `corner` toward the next corner of its face.
    pub func corner_edge(corner: i64) -> i64!:
        try checked(corner, self.corners.count())
        return (i64)(try self.edge_arrays()).1[(usize)corner]

    ## The first corner of face `face`.
    pub func face_offset(face: i64) -> i64!:
        try checked(face, self.offsets.count() - 1)
        return (i64)self.offsets.view()[(usize)face]

    ## The face display triangle `triangle` belongs to.
    pub func triangle_face(triangle: i64) -> i64!:
        try checked(triangle, self.triangles.count() // 3)
        return (i64)(try self.corner_faces())[(usize)self.triangles.view()[(usize)triangle * 3]]

    ## Point `index` in world space.
    pub func point(index: i64) -> Vector3!:
        try checked(index, self.positions.count())
        return self.point_at((usize)index)

    ## Whether this mesh keeps f64 points (see Mesh).
    pub func is_precise() -> bool:
        return not self.precise.is_empty()

    ## A point in f64: the precise point, or the f32 position plus the origin.
    func point_at(index: usize) -> Vector3:
        if not self.precise.is_empty(): return self.precise.view()[index]
        return self.positions.view()[index].vector().add(self.origin)

    ## How many corners face `face` has.
    pub func face_size(face: i64) -> i64!:
        try checked(face, self.offsets.count() - 1)
        let offsets = self.offsets.view()
        return (i64)(offsets[(usize)face + 1] - offsets[(usize)face])

    ## The point of corner `corner` (0..size) of face `face`.
    pub func face_point(face: i64, corner: i64) -> i64!:
        let size = try self.face_size(face)
        try checked(corner, (usize)size)
        return (i64)self.corners.view()[(usize)self.offsets.view()[(usize)face] + (usize)corner]

    ## Shared undirected edge ID for a polygon's outgoing corner edge.
    pub func face_edge(face: i64, corner: i64) -> i64!:
        let size = try self.face_size(face)
        try checked(corner, (usize)size)
        return (i64)(try self.edge_arrays()).1[(usize)self.offsets.view()[(usize)face] + (usize)corner]

    ## Face `face`'s unit normal (zero for a face without an area).
    pub func face_normal(face: i64) -> Vector3!:
        try checked(face, self.offsets.count() - 1)
        return self.normals.view()[(usize)face].vector()

    ## The mean of face `face`'s points.
    pub func face_center(face: i64) -> Vector3!:
        let size = try self.face_size(face)
        let corners = self.corners.view()
        let start = (usize)self.offsets.view()[(usize)face]
        var sum = Vector3()
        for at in start..<start + (usize)size:
            sum = sum.add(self.point_at((usize)corners[at]))
        return sum.multiply_scalar(1.0 / (f64)size)

    ## Point `end` (0 or 1) of edge `edge`.
    pub func edge_point(edge: i64, end: i64) -> i64!:
        let edges = (try self.edge_arrays()).0
        try checked(edge, edges.length // 2)
        if end != 0 and end != 1:
            error(errors.invalid, "edge endpoint must be 0 or 1")
        return (i64)edges[(usize)edge * 2 + (usize)end]

    ## Corner `index` as the renderer draws it: position, shading normal, uv
    ## and color, each looked up corner > point > face > detail.
    pub func vertex(index: i64) -> interop.Outcome[Vertex]:
        if index < 0 or (usize)index >= self.corners.count():
            return errors.failure[Vertex](errors.invalid, "polygon vertex out of range")
        let faces = self.corner_faces() catch failure:
            return errors.failure[Vertex](failure.code, failure.message)
        let face = (usize)faces[(usize)index]
        let at = (usize)index - (usize)self.offsets.view()[face]
        let point = (usize)self.corners.view()[(usize)index]
        var color = Vector3(1.0, 1.0, 1.0)
        let normal = self.shading_normal((usize)index, face) catch failure:
            return errors.failure[Vertex](failure.code, failure.message)
        var u = 1.0 if at == 1 or at == 2 else 0.0
        var v = 1.0 if at >= 2 else 0.0
        for domain in lookup_order:
            let element = self.element_of(domain, (usize)index, face)
            let cd = self.attributes.colors[domain]
            if cd >= 0 and self.attributes.entry((usize)cd).width >= 3:
                let entry = self.attributes.entry((usize)cd)
                color = Vector3(math.max(0.0, math.min(1.0, entry.number(element, 0))), math.max(0.0, math.min(1.0, entry.number(element, 1))), math.max(0.0, math.min(1.0, entry.number(element, 2))))
            let uv = self.attributes.uvs[domain]
            if uv >= 0 and self.attributes.entry((usize)uv).width >= 2:
                let entry = self.attributes.entry((usize)uv)
                u = entry.number(element, 0)
                v = entry.number(element, 1)
        return errors.success[Vertex](Vertex(self.point_at(point), normal, u, v, color))

    ## A corner's shading normal alone, without building a whole Vertex; bulk
    ## overlay extraction calls it for every corner.
    pub func corner_normal(corner: i64) -> Vector3!:
        try checked(corner, self.corners.count())
        return try self.shading_normal((usize)corner, (usize)(try self.corner_faces())[(usize)corner])

    ## The N attribute by corner > point > primitive > detail precedence,
    ## else the smooth normal (see ShadingCache).
    func shading_normal(corner: usize, face: usize) -> Vector3!:
        var normal = Vector3()
        if not self.has_normals():
            let smooth = try self.smooth_normals()
            return smooth[corner if self.shading.corner_domain() else (usize)self.corners.view()[corner]].vector()
        for domain in lookup_order:
            let ni = self.attributes.normals[domain]
            if ni < 0 or self.attributes.entry((usize)ni).width != 3:
                continue
            let element = self.element_of(domain, corner, face)
            let entry = self.attributes.entry((usize)ni)
            let provided = Vector3(entry.number(element, 0), entry.number(element, 1), entry.number(element, 2))
            if provided.length() > 0.000000001:
                normal = provided.multiply_scalar(1.0 / provided.length())
        return normal if normal.length() > 0.0 else self.normals.view()[face].vector()

    ## The element of `domain` that corner `corner` of `face` reads: the
    ## detail's one, the face, the corner's point or the corner itself.
    func element_of(domain: usize, corner: usize, face: usize) -> usize:
        if domain == 3: return 0
        if domain == 2: return face
        if domain == 0: return (usize)self.corners.view()[corner]
        return corner

    ## Whether an authored N (three components) exists on any domain.
    func has_normals() -> bool:
        for domain in 0..<(usize)4:
            let index = self.attributes.normals[domain]
            if index >= 0 and self.attributes.entry((usize)index).width == 3: return true
        return false

    ## k1 and k2 of every point (discrete; see curvature.lucb), computed on
    ## first use.
    func curvatures() -> const f32[]!:
        if self.shading.has_curvatures(): return self.shading.built_curvatures()
        # Points on an edge used once are boundary points.
        let points = self.positions.count()
        let edges = try self.edge_arrays()
        let uses = try new u32[edges.0.length // 2] --- in memory.heap
        defer free(uses) in memory.heap
        memory.set(u8[]((u8*)uses.data, uses.length * 4), 0)
        for edge in edges.1: uses[(usize)edge] += 1
        let boundary = try new bool[points] --- in memory.heap
        defer free(boundary) in memory.heap
        memory.set(u8[]((u8*)boundary.data, points), 0)
        for edge in 0..<uses.length:
            if uses[edge] == 1:
                boundary[(usize)edges.0[edge * 2]] = true
                boundary[(usize)edges.0[edge * 2 + 1]] = true
        let incidence = try self.incidence()
        let shape = CurvatureShape(self.positions.view(), self.offsets.view(), self.corners.view(), self.triangles.view(), self.normals.view(), incidence.0, incidence.1, boundary)
        return try self.shading.curvatures(&shape)

    ## The discrete principal curvatures (k1, k2, 0) at `point`: positive
    ## where the surface bends away from its normals; zero on a boundary.
    pub func point_curvature(point: i64) -> Vector3!:
        try checked(point, self.positions.count())
        let values = try self.curvatures()
        return Vector3((f64)values[(usize)point * 2], (f64)values[(usize)point * 2 + 1], 0.0)

    ## The smooth normals (per point, or per corner where a cusp splits a
    ## point), computed on first use.
    func smooth_normals() -> const Float3[]!:
        let incidence = try self.incidence()
        let shape = Surface(self.positions.view(), self.offsets.view(), self.corners.view(), self.normals.view(), incidence.0, incidence.1)
        return try self.shading.get(&shape)

    ## Display triangle index `offset`: a corner.
    pub func index(offset: i64) -> interop.Outcome[i64]:
        if offset < 0 or (usize)offset >= self.triangles.count():
            return errors.failure[i64](errors.invalid, "polygon triangle index out of range")
        return errors.success[i64]((i64)self.triangles.view()[(usize)offset])

    ## Nearest Euclidean distance to the mesh surface; -1 for an empty mesh.
    pub func surface_distance(point: Vector3) -> f64!:
        if not point.is_finite(): error(errors.invalid, "distance query requires a finite point")
        return (try self.query_index()).distance(point.subtract(self.origin))

    ## Primitive containing the closest surface point, or -1 for empty geometry.
    pub func closest_face(point: Vector3) -> i64!:
        if not point.is_finite(): error(errors.invalid, "distance query requires a finite point")
        return (try self.query_index()).nearest(point.subtract(self.origin)).face

    ## Build the shared query index now, for example before worker-to-UI transfer.
    ## Otherwise the first ray/distance query builds it. Failure is retryable.
    pub func prepare_queries() -> !:
        _ = try self.query_index()

    ## Nearest two-sided face intersection. -1 means no hit; direction must be
    ## normalized for the returned distance to be world-space distance.
    pub func ray_face(origin: Vector3, direction: Vector3) -> i64!:
        return (try self.query_index()).ray(origin.subtract(self.origin), direction).face

    ## How far along the ray the nearest face is (see ray_face).
    pub func ray_distance(origin: Vector3, direction: Vector3) -> f64!:
        return (try self.query_index()).ray(origin.subtract(self.origin), direction).distance

    ## Change ids of the arrays (equal ids: equal contents, on any thread);
    ## caches such as GPU buffers key on them.
    pub func points_id() -> u64:
        return self.positions.id()

    ## The corners' change id.
    pub func corners_id() -> u64:
        return self.corners.id()

    ## The face offsets' change id.
    pub func offsets_id() -> u64:
        return self.offsets.id()

    ## The display triangles' change id.
    pub func triangles_id() -> u64:
        return self.triangles.id()

    ## The face normals' change id.
    pub func normals_id() -> u64:
        return self.normals.id()

    ## Edges are derived from the corners, so their id is the corners' id.
    pub func edges_id() -> u64:
        return self.corners.id()

    ## The faces' spatial index, built on first use and shared (for Base kernels that
    ## query it many times: positions there are relative to position_origin()).
    pub func query_index() -> const TriangleIndex*!:
        let faces = try self.corner_faces()
        return try self.queries.get(self.positions.view(), self.corners.view(), self.triangles.view(), faces)

    ## Whole arrays for Base kernels, valid while the mesh is (Luce sees none
    ## of them). Positions are relative to position_origin().
    pub func point_span() -> const Float3[]:
        return self.positions.view()

    ## The origin positions are measured from.
    pub func position_origin() -> Vector3:
        return self.origin

    ## Face offsets: face f's corners are offsets[f]..<offsets[f + 1].
    pub func offset_span() -> const i32[]:
        return self.offsets.view()

    ## The point of every corner.
    pub func corner_span() -> const i32[]:
        return self.corners.view()

    ## The face of every corner.
    pub func corner_face_span() -> const i32[]!:
        return try self.corner_faces()

    ## Every face's unit normal.
    pub func face_normal_span() -> const Float3[]:
        return self.normals.view()

    ## Display triangles: three corners each, grouped by face.
    pub func triangle_span() -> const i32[]:
        return self.triangles.view()

    ## The two points of every edge.
    pub func edge_span() -> const i32[]!:
        return (try self.edge_arrays()).0

    ## The edge leaving every corner.
    pub func corner_edge_span() -> const i32[]!:
        return (try self.edge_arrays()).1

    ## The face nearest `point` if it is closer than `bound`, else
    ## -1 (the spatial index is built on first use).
    pub func nearest_face_within(point: Vector3, bound: f64) -> i64!:
        return (try self.query_index()).nearest_within(point.subtract(self.origin), bound).face

    ## Attribute `index`, for Base readers.
    pub func attribute_entry(index: i64) -> const Attribute*!:
        try checked(index, self.attributes.count())
        return self.attributes.entry((usize)index)

    ## The arrays a position edit derived positions and face normals from, or 0.
    pub func points_parent() -> u64:
        return self.positions.parent()

    ## The face normals' parent column id, or 0.
    pub func normals_parent() -> u64:
        return self.normals.parent()

    ## Smooth normals (the shading of a mesh without N), per point or per corner
    ## (`smooth_normals_corner_domain`), computed on first use; and the id of
    ## their column and the one it was updated from.
    pub func smooth_normal_span() -> const Float3[]!:
        return try self.smooth_normals()

    ## Whether the smooth normals are per corner (a cusp splits a point).
    pub func smooth_normals_corner_domain() -> bool!:
        _ = try self.smooth_normals()
        return self.shading.corner_domain()

    ## The smooth normals' column id and the id it was updated from.
    pub func smooth_normals_ids() -> (u64, u64)!:
        _ = try self.smooth_normals()
        return (self.shading.id(), self.shading.parent())

    ## k1 and k2 of every point (discrete principal curvatures), computed on first
    ## use; and the id of their column.
    pub func curvature_span() -> const f32[]!:
        return try self.curvatures()

    ## The curvatures' column id.
    pub func curvature_id() -> u64!:
        _ = try self.curvatures()
        return self.shading.curvature_id()

    ## The positions' and smooth normals' changed elements (see Column.changed).
    pub func points_changed() -> (usize, usize):
        return self.positions.changed()

    ## The smooth normals' changed elements (see Column.changed).
    pub func smooth_changed() -> (usize, usize)!:
        _ = try self.smooth_normals()
        return self.shading.changed()

    ## Faces around each point (one per corner there), as offsets into a list.
    pub func point_face_span() -> (const i32[], const i32[])!:
        return try self.incidence()

    ## What another module derives from the connectivity, shared by every
    ## mesh with it (see TopologyCache.extension_of).
    pub func topology_extension(dispose: func(void*) -> unit, make: func() -> void*!) -> void*!:
        return try self.topology.extension_of(dispose, make)

    ## Each edge's corners (those whose outgoing edge it is).
    pub func edge_corner_span() -> (const i32[], const i32[])!:
        let edges = try self.edge_arrays()
        return try self.topology.edge_corners(edges.1, edges.0.length // 2)

    ## Each point's edges.
    pub func point_edge_span() -> (const i32[], const i32[])!:
        let edges = try self.edge_arrays()
        return try self.topology.point_edges(edges.0, self.positions.count())