Luce packages
LuceLuce BaseLuciaOS

dymokomi/luced-3d

Source of release 0.11.2

0.11.2 / src / node_catalog.luc

## Single source of truth for the node menu, defaults and parameter UI. Each
## node's parameters are rows of its parameter pane (`fields`), after
## Houdini's parameter templates: a kind, a label, the slot its value or text
## lives in, ranges, a menu's items, a unit, a tooltip and conditions. The
## numeric slots (`parameters`) come from the same rows, so defaults, clamping
## and the pane never disagree.
##
## Modeling, curve and field nodes are luce-geocore verbs, from one catalog
## over its two registries (VerbCatalog: mesh verbs, then set verbs): their
## parameters come from the verb, in value slots from 0, and grouped ones have
## the standard Group (text slot 0) and Group Type (value slot
## `group_type_slot`) of Houdini.
from luce_geocore.geocore import Verbs, VerbCatalog
from edit_kinds import is_edit, edit_kind_names
import edit_gsplats
from edit_types import soft_radius_slot, falloff_slot, symmetry_slot, keep_slot
from usd_nodes import is_usd_path, Composition, first_variant_slot
from fbx_nodes import is_fbx_path
from shader_nodes import is_shader, shader_kinds, shader_categories, shader_category, math_operations
import shader_nodes
import sketch_node
from parameter_rows import Parameter, number, whole, vector, toggle, menu, entry, heading
from cad_nodes import solid_kinds, cad_only_kinds, is_cad_only, cad_categories, cad_category
import cad_nodes
import code_cook
import script_cook

## Value slots a node has, and the one verb nodes keep their Group Type in.
pub let value_slots: int = 32
pub let group_type_slot: int = 15

pub func is_verb(kind: str) -> bool:
    return VerbCatalog.index_of(kind) >= 0

## Verbs that run on the realized mesh (their groups name mesh components).
pub func is_mesh_verb(kind: str) -> bool:
    return Verbs.index_of(kind) >= 0

## Verbs that run on the whole geometry set (curves, fields, conversions).
pub func is_set_verb(kind: str) -> bool:
    let index = VerbCatalog.index_of(kind)
    return index >= 0 and VerbCatalog.is_set(index)

## Every verb's node kind, in the catalog's order.
pub func verbs() -> list[str]:
    let result: list[str] = []
    for index in 0..<VerbCatalog.count():
        result.append(VerbCatalog.name(index))
    return result

## Verb nodes with no input (primitive curves, SDF shapes).
func generators() -> list[str]:
    let result: list[str] = []
    for index in 0..<VerbCatalog.count():
        if VerbCatalog.inputs(index) == 0:
            result.append(VerbCatalog.name(index))
    return result

## Whether the node's second input must be connected.
pub func requires_second(kind: str) -> bool:
    let index = VerbCatalog.index_of(kind)
    if index >= 0:
        return VerbCatalog.second_required(index)
    return not (kind in ["Switch", "Null", "Extrude", "Revolve", code_cook.kind_name, script_cook.kind_name])

pub func sources() -> list[str]:
    return ["Cube", "Grid", "Sphere", "Cylinder", "Cone", "Torus", "File", "Group", "CAD"] + generators() + solid_kinds()

## Nodes holding nodes: Groups (geometry nodes), CAD nodes (CAD features)
## and Materials (shader nodes).
pub func holds_nodes(kind: str) -> bool:
    return kind in ["Group", "CAD", "Material"]

## Containers whose result is their exposed children placed as one instance,
## by their transform and visibility.
pub func places_children(kind: str) -> bool:
    return kind in ["Group", "CAD"]

## The menu's categories in a network's context: geometry nodes', inside a
## CAD node ("cad") CAD nodes', inside a Material ("shading") shader nodes'.
pub func categories(context: str = "geometry") -> list[str]:
    if context == "shading":
        return shader_categories()
    if context == "cad":
        return cad_categories()
    return ["Primitives", "Modeling", "Deform", "Curves", "Volumes", "GSplats", "Transform / Copy", "Attributes", "Utility", "File I/O", "Materials", "Render", "All"]

## A node's category in the menu of `context`.
pub func category_in(kind: str, context: str) -> str:
    return cad_category(kind) if context == "cad" else category(kind)

pub func category(kind: str) -> str:
    if is_shader(kind):
        return shader_category(kind)
    if is_cad_only(kind):
        return cad_category(kind)
    if kind == edit_gsplats.kind_name:
        return "GSplats"
    let verb = VerbCatalog.index_of(kind)
    if verb >= 0:
        return VerbCatalog.category(verb)
    if kind in ["File", "Cache", "Export"]:
        return "File I/O"
    if kind in scene_kinds():
        return "Render"
    if kind in material_kinds():
        return "Materials"
    if kind in ["Group", "CAD"]:
        return "Utility"
    if kind in sources():
        return "Primitives"
    if kind in ["Transform", "Mirror", "CopyTransform", "CopyToPoints", "MatchSize"]:
        return "Transform / Copy"
    if kind.starts_with("Attribute") or kind in ["Selection Group", "Name", "Normal", "Measure", "UVProject", "Color"]:
        return "Attributes"
    if kind in ["Merge", "Null", "Switch", code_cook.kind_name, script_cook.kind_name]:
        return "Utility"
    return "Modeling"

pub func kinds() -> list[str]:
    return sources() + ["Transform", "Tessellate", "Cache", "Export", "Blast"] + edit_kind_names() + ["Merge", "Null", "Switch", code_cook.kind_name, script_cook.kind_name] + scene_kinds() + material_kinds() + verbs() + ["Mirror", "CopyTransform", "CopyToPoints", "MatchSize", "AttributeCreate", "AttributeRandomize", "AttributeDelete", "AttributeRename", "AttributePromote", "Selection Group", "Name", "Normal", "Measure", "UVProject", "Color"] + [sketch_node.kind_name, "Extrude", "Revolve", "Boolean", "Fillet", "Chamfer", "Mirror Body", "Pattern"] + shader_kinds()

pub func input_count(kind: str) -> int:
    if cad_nodes.two_inputs(kind):
        return 2
    if is_shader(kind):
        return shader_nodes.inputs(kind).length
    let verb = VerbCatalog.index_of(kind)
    if verb >= 0:
        return VerbCatalog.inputs(verb)
    return 0 if kind in sources() else (2 if kind in ["Merge", "Switch", "CopyToPoints", "Assign Material", code_cook.kind_name, script_cook.kind_name] else 1)

## Nodes that put cameras and lights in the geometry, and the Render node.
pub func scene_kinds() -> list[str]:
    return ["Camera", "Light", "Render"]

## Material defines a material; Assign Material binds one to faces.
pub func material_kinds() -> list[str]:
    return ["Material", "Assign Material"]

## Nodes that cook from nothing when their input is unconnected: an Edit
## node creates, a Camera, Light or Material makes just its own, a Sketch
## draws on an origin plane (its input is a body to sketch on a face of).
pub func optional_input(kind: str) -> bool:
    return is_edit(kind) or kind in ["Camera", "Light", "Material", "Volume", sketch_node.kind_name, code_cook.kind_name, script_cook.kind_name]

pub func has_group(kind: str) -> bool:
    let verb = VerbCatalog.index_of(kind)
    if verb >= 0:
        return VerbCatalog.grouped(verb)
    return kind in ["Blast", "Selection Group", "Assign Material", "Name", code_cook.kind_name]

pub func has_attribute_name(kind: str) -> bool:
    return kind in ["AttributeCreate", "AttributeRandomize", "AttributeDelete", "AttributeRename", "AttributePromote", "Selection Group"]

## The value slots of a node: one Parameter a slot, a vector's components
## each their own, for defaults and clamping.
pub func parameters(kind: str, path: str = "") -> list[Parameter]!:
    let result: list[Parameter] = []
    for row in fields(kind, path):
        if not row.valued():
            continue
        if row.components == 1:
            result.append(row)
            continue
        for component in 0..<row.components:
            let value = row.initial if component == 0 else row.rest[component - 1]
            result.append(Parameter(row.name + " " + ["X", "Y", "Z", "W"][component], row.slot + component, value, row.minimum, row.maximum, row.step, row.integer, row.decimals))
    return result

## The rows of node `kind` a tool shows on the viewport's tool bar: its
## values but what it works on (Group Type; the Group and a feature's Edges
## are texts, so left out already).
pub func tool_rows(kind: str) -> list[Parameter]!:
    let result: list[Parameter] = []
    for row in fields(kind):
        if row.valued() and row.slot != group_type_slot:
            result.append(row)
    return result

## Node `kind`'s starting values in its tool rows' slots (a step's numbers).
pub func starting_values(kind: str) -> list[float]!:
    let result: list[float] = []
    for parameter in parameters(kind):
        if parameter.slot == group_type_slot:
            continue
        while result.length <= parameter.slot:
            result.append(0.0)
        result[parameter.slot] = parameter.initial
    return result

## Every row of a node's parameter pane, in order; a USD File node's
## composition rows come from its composed `stage`.
pub func fields(kind: str, path: str = "", stage: Composition? = none) -> list[Parameter]!:
    let rows: list[Parameter] = []
    if kind == "File":
        rows.append(entry("File", 0, "The geometry file: OBJ, FBX, PLY (meshes, point clouds, Gaussian splats), SPZ or .splat (Gaussian splats), STEP or USD (.usd, .usda, .usdc, .usdz).", "path"))
        let reload = heading("Reload", "button")
        reload.doc = "Read the file again from disk."
        rows.append(reload)
        let source = path.trim().lower()
        if source.ends_with(".step") or source.ends_with(".stp"):
            rows.append(number("STEP tolerance", 0, 0.0, 0.0, 1.0, 0.00001, "Model tolerance in file units; 0 uses the file's own.", decimals = 9))
        if is_usd_path(source):
            for row in usd_fields(stage):
                rows.append(row)
        if is_fbx_path(source):
            for row in fbx_fields():
                rows.append(row)
    if kind == "Cache":
        rows.append(entry("File", 0, "The .prism file the cooked geometry is saved to (and loaded from).", "path"))
    if kind == "Export":
        rows.append(entry("File", 0, "Where the input is written, in the format its extension names: .usd, .usda, .usdc, .usdz, .fbx, .obj, .ply, .spz, .splat or .prism.", "path"))
        rows.append(entry("Root prim", 1, "USD: the prim elements without a path attribute go under (empty: geo); it becomes the default prim."))
    if kind in ["Camera", "Light"]:
        rows.append(entry("Path", 0, "The object's path in the scene, like other paths: cameras/hero."))
    if kind == "Light":
        let image = entry("Environment", 1, "A Dome's image: a lat-long OpenEXR in linear Rec.709, its center down the light's -Z and its top up (+Y). Empty shines the color evenly.", "path")
        image.hide_when = "{ type != 4 }"
        rows.append(image)
    if kind == "Material":
        rows.append(entry("Path", 0, "The material's path: what Assign Material binds faces to (materials/red_plastic). Double-click the node to build its shader from nodes."))
    if kind == "Image Texture":
        rows.append(entry("Image", 0, "The image (PNG, JPEG or OpenEXR), mapped by the faces' uv unless Vector is linked.", "path"))
    if kind == "Render":
        let start = heading("Render", "button")
        start.doc = "Render the input in the Render panel, progressively."
        rows.append(start)
        rows.append(entry("Camera", 0, "The path of the camera to render through; empty takes the first camera."))
        rows.append(entry("Output", 1, "Where the image is written (.exr); empty only shows it.", "path"))
    if has_group(kind):
        let group = entry("Group", 0, "Elements to work on, in Houdini's group syntax: empty or * for all, 0 2-5 and 0-99:2 for numbers, names and globs, @P.y>0 or @name tests, ^ to remove, & to intersect, grow(x) and loop(x).")
        if kind == code_cook.kind_name:
            group.hide_when = "{ run_over == 5 }"
        rows.append(group)
    if kind == script_cook.kind_name:
        rows.append(entry("Packages", script_cook.packages_slot, "Luce packages the script imports, apart by spaces: luce-image, owner/name@^1.2, or a folder. luce-geocore and luce-std are always there; the lock that pins registry packages is kept in the project."))
    if kind == code_cook.kind_name:
        let grid = entry("Volume", 0, "Voxels: the grid the code runs over, by name (density); empty takes the first, #2 the third.")
        grid.hide_when = "{ run_over != 5 }"
        rows.append(grid)
    # A verb's own text rows (a Volume's grid name, Volume Visualization's
    # group and fields), where a group would be, in text slots from 0; its
    # ramp rows follow its numbers.
    let verb_index = VerbCatalog.index_of(kind)
    if verb_index >= 0:
        for row in 0..<VerbCatalog.text_row_count(verb_index):
            if not VerbCatalog.text_row_ramp(verb_index, row):
                rows.append(entry(VerbCatalog.text_row_label(verb_index, row), row, VerbCatalog.text_row_doc(verb_index, row)))
    if kind == "Name":
        rows.append(entry("Name", 1, "The name the Group's faces get, in their name attribute (Houdini's Name): pick them later with @name=wheel or a glob, @name=wheel*."))
    if (is_verb(kind) and has_group(kind)) or kind == code_cook.kind_name:
        rows.append(menu("Group Type", group_type_slot, "Guess from group|Points|Edges|Primitives|Vertices", 0.0, "What the group's numbers name; Guess reads the named groups' type, else the operation's own."))
    if kind == "Assign Material":
        rows.append(entry("Material", 1, "The path of the material the group's faces take, from the second input; empty takes its first."))
    if has_attribute_name(kind):
        rows.append(entry("Attribute", 1, "The attribute's name."))
    if kind == "AttributeRename":
        rows.append(entry("New name", 2, "What the attribute is called after."))
    for row in value_fields(kind):
        rows.append(row)
    if verb_index >= 0:
        for row in 0..<VerbCatalog.text_row_count(verb_index):
            if VerbCatalog.text_row_ramp(verb_index, row):
                # As a Code node's color ramp row: positions 0..1.
                let ramp = Parameter(VerbCatalog.text_row_label(verb_index, row), row, 0.0, 0.0, 1.0)
                ramp.kind = "color_ramp"
                ramp.doc = VerbCatalog.text_row_doc(verb_index, row)
                rows.append(ramp)
    return rows

## How many text rows verb node `kind` has (0 for other nodes).
pub func text_row_count(kind: str) -> int:
    let verb = VerbCatalog.index_of(kind)
    return VerbCatalog.text_row_count(verb) if verb >= 0 else 0

## A verb node's ramp row in text slot `slot` as numbers (luce-std ramp's
## form): its text, or the verb's initial ramp while the text is empty.
pub func verb_ramp(kind: str, slot: int, text: str) -> list[float]:
    let verb = VerbCatalog.index_of(kind)
    var source = text.trim()
    if source == "" and verb >= 0 and slot < VerbCatalog.text_row_count(verb):
        source = VerbCatalog.text_row_initial(verb, slot)
    let numbers: list[float] = []
    for piece in source.split(","):
        if piece.trim() != "":
            let value = float(piece.trim()) catch failure:
                recover 0.0
            numbers.append(value)
    return numbers

## A ramp's numbers as a verb node's ramp text: comma apart.
pub func ramp_text(numbers: list[float]) -> str:
    let parts: list[str] = []
    for value in numbers:
        parts.append(f"{value}")
    return parts.join(",")

## A File node's rows for a USD stage (usd_nodes.load_usd reads them), in
## value slots from 1: slot 0 keeps a STEP tolerance across format changes.
## Then its composition: what the stage holds, the variant selections text
## and a menu for each of its first variant sets, and the payload globs.
func usd_fields(stage: Composition?) -> list[Parameter]:
    let rows = load_fields()
    if let composed = stage:
        let summary = heading("Stage", "info")
        summary.text = composed.description()
        rows.append(summary)
    rows.append(entry("Variants", 1, "Variant selections in USD path syntax, blank separated: /Kitchen{look=clean} /Kitchen/Chair{size=big}. The menus below select after them."))
    if let composed = stage:
        let sets = composed.menu_sets()
        for index in 0..<sets.length:
            let shown = sets[index]
            let authored = shown.selection if shown.selection != "" else "none"
            rows.append(menu(f"{shown.prim.split("/")[-1]} {shown.name}", first_variant_slot + index, f"Authored ({authored})|" + shown.options.join("|"), 0.0,
                             f"{shown.prim}: variant set {shown.name}. Authored keeps the stage's own selection."))
    rows.append(entry("Load payloads", 2, "Load only the payloads of prims whose path matches one of these globs (* any run, ? one character), blank separated. Empty loads every payload, - none."))
    return rows

## The load options of a USD File node, value slots 1 to 8.
func load_fields() -> list[Parameter]:
    let set_time = toggle("Set time", 2, 0.0, "Off: the stage's start time, else each attribute's first sample. On: the time below.")
    set_time.key = "settime"
    let at = number("Time", 3, 0.0, -1000000.0, 1000000.0, 1.0, "The time code values are read at.")
    at.disable_when = "{ settime == 0 }"
    return [menu("Import", 1, "Flatten, keep instancing|Flatten everything", 0.0, "Keep point instancers as instances, or bake every instance into the meshes, curves and points."),
            set_time, at,
            toggle("Render purpose", 4, 1.0, "Load prims whose purpose is render."),
            toggle("Proxy purpose", 5, 0.0, "Load prims whose purpose is proxy."),
            toggle("Guide purpose", 6, 0.0, "Load prims whose purpose is guide."),
            toggle("Convert to Y-up meters", 7, 0.0, "Turn a Z-up stage Y-up and scale it to meters; off keeps the stage's own axes and units (in the usd.* detail attributes)."),
            toggle("Subdivide as authored", 8, 1.0, "Show meshes without a subdivisionScheme as Catmull-Clark surfaces, as USD's default says; off shows their polygons.")]

## A File node's rows for an FBX file (fbx_nodes.load_fbx reads them), in
## value slots from 1: slot 0 keeps a STEP tolerance across format changes.
func fbx_fields() -> list[Parameter]:
    let set_frame = toggle("Set frame", 5, 0.0, "Off: the file's pose as saved. On: the first animation stack at the frame below.")
    set_frame.key = "setframe"
    let frame = number("Frame", 6, 0.0, -1000000.0, 1000000.0, 1.0, "The frame the animation is read at, at the file's frame rate.")
    frame.disable_when = "{ setframe == 0 }"
    return [menu("Import", 1, "Merge into one mesh|Keep hierarchy", 0.0, "Merge every model's mesh into one mesh in world space (each face's model path in `path`), or keep each model's mesh in its own space, placed as an instance."),
            toggle("Instancing", 2, 1.0, "Load a mesh several models share once, as instances; off copies it for each model."),
            toggle("Convert to Y-up meters", 3, 0.0, "Turn the file Y-up and scale it to meters; off keeps its own axes and units (in the fbx.* detail attributes)."),
            toggle("Import normals", 4, 1.0, "Read the file's normals as N; off shows face normals."),
            set_frame, frame,
            toggle("Deform", 7, 1.0, "Apply blend shapes and skins; off shows the meshes as modeled.")]

## The format of a File node's path ("usd", "fbx", "step" or ""), whose
## rows it has.
pub func file_format(path: str) -> str:
    let source = path.trim().lower()
    if source.ends_with(".step") or source.ends_with(".stp"):
        return "step"
    if is_fbx_path(source):
        return "fbx"
    return "usd" if is_usd_path(source) else ""

## The numeric rows of each node kind.
func value_fields(kind: str) -> list[Parameter]:
    let verb = VerbCatalog.index_of(kind)
    if verb >= 0:
        return verb_fields(verb)
    if kind == code_cook.kind_name:
        let count = whole("Count", code_cook.count_slot, 10.0, 0.0, 100000000.0, "Numbers: how many times the code runs (n is 0 to Count - 1).", true)
        count.hide_when = "{ run_over != 4 }"
        let run_over = menu("Run Over", code_cook.run_over_slot, code_cook.run_over_names(), 1.0, "What the code is written for: each point (p), vertex (v), primitive (f) or voxel (x), the detail once, or Count numbers (n). It runs for all of them in parallel.")
        run_over.key = "run_over"
        let dense = toggle("Dense", code_cook.dense_slot, 0.0, "Voxels: run over every voxel of the grid's box, activating them all; off, only its active voxels.")
        dense.hide_when = "{ run_over != 5 }"
        return [run_over, count, dense]
    if kind == script_cook.kind_name:
        return [number("Time Limit", script_cook.limit_slot, 30.0, 0.0, 86400.0, 1.0, "Seconds a cook may run before the script is stopped (0: 30 s).", suffix = " s"),
                menu("Time Dependent", script_cook.time_slot, "Auto|On|Off", 0.0, "Whether the node cooks again when the frame changes. Auto: when the code reads k.frame(), k.time() or k.fps().")]
    if kind == "Blast":
        return [toggle("Isolate group", 0, 0.0, "On: keep only the group. Off: delete it.")]
    if kind == "Export":
        return [toggle("Split by path", 0, 1.0, "USD: one prim per path attribute value, as the file was imported; off writes one prim per family."),
                toggle("Precise points", 1, 0.0, "USD: double-precision points, keeping large coordinates exact."),
                menu("Splat precision", 2, "As read|Float|Half", 0.0, "USD: Gaussian splat arrays as floats or halves; As read writes halves when the file the splats came from had them.")]
    if kind == "Cache":
        return [toggle("Load from disk", 0, 0.0, "On: read the file and skip everything upstream. Off: write the input's result to the file when it changes, and pass it on.")]
    if kind == "Tessellate":
        return [whole("Surface divisions", 0, 16.0, 1.0, 64.0, "Subdivisions per CAD surface span.", true),
                number("Target edge", 1, 0.0, 0.0, 100000.0, 0.5, "Longest triangle edge in model units; 0 leaves it to the divisions.", soft = 10.0)]
    if kind == "Cube":
        return [number("Size", 0, 2.0, 0.001, 100.0, 0.1, "Edge length before the size factors.", true, 10.0),
                vector("Position", 1, [0.0, 0.0, 0.0], "Where the cube's center sits."),
                vector("Size factors", 7, [1.0, 1.0, 1.0], "Width, height and depth as factors of Size.", 0.001, 1000.0)]
    if kind in ["Grid", "Sphere", "Cylinder", "Cone", "Torus"]:
        let grid = kind == "Grid"
        let result = [number("Size" if grid else "Radius", 0, 2.0 if grid else 1.0, 0.001, 100.0, 0.1, "Overall size." if grid else "Distance from the center to the surface.", true, 10.0),
                      whole("Divisions", 1, 4.0 if grid else 16.0, 1.0 if grid else 4.0, 2048.0 if grid else 64.0, "Rows and columns (up to 2048: 4.2 million points)." if grid else "Segments around.", true)]
        if kind == "Torus":
            result.append(number("Tube radius", 2, 0.3, 0.001, 100.0, 0.1, "Radius of the ring's cross section.", true, 2.0))
        elif kind in ["Cylinder", "Cone"]:
            result.append(number("Height", 2, 2.0, 0.001, 100.0, 0.1, "Length along Y.", true, 10.0))
        return result
    if kind in ["Transform", "Group", "CAD"]:
        return [vector("Translate", 1, [0.0, 0.0, 0.0], "Moves the geometry, after rotating and scaling."),
                vector("Rotate", 4, [0.0, 0.0, 0.0], "Rotation about X, then Y, then Z, in degrees, about the pivot.", suffix = "°"),
                vector("Scale", 7, [1.0, 1.0, 1.0], "Scale along each axis about the pivot; never zero."),
                vector("Pivot", 10, [0.0, 0.0, 0.0], "The point rotation and scale happen about.")]
    if kind in cad_only_kinds():
        return cad_fields(kind)
    if kind == "Camera":
        return camera_fields()
    if kind == "Light":
        return light_fields()
    if kind == "Render":
        return render_fields()
    if kind == "OpenPBR Surface":
        return material_fields(0, "OpenPBR", true)
    if is_shader(kind):
        return shader_fields(kind)
    if kind == "Mirror":
        return [menu("Axis", 0, "X|Y|Z", 0.0, "The axis the mirror plane faces."),
                toggle("Keep original", 1, 1.0, "Keep the input beside its mirror image.")]
    if kind == "CopyTransform":
        let step = vector("Step", 1, [2.5, 0.0, 0.0], "Offset between one copy and the next.")
        step.disable_when = "{ copies <= 1 }"
        let copies = whole("Copies", 0, 3.0, 1.0, 64.0, "How many, the source included.", true)
        copies.key = "copies"
        return [copies, step]
    if kind == "Switch":
        return [menu("Input", 0, "First|Second", 0.0, "Which input passes through.")]
    if kind == "MatchSize":
        return [number("Longest side", 0, 2.0, 0.001, 1000.0, 0.1, "The size the longest bounding-box side is scaled to.", soft = 10.0)]
    if kind in ["AttributeCreate", "AttributeRandomize", "AttributeDelete", "AttributeRename", "AttributePromote", "Selection Group"]:
        let domains = "Points=0|Vertices=1|Faces=2|Edges=4" if kind == "Selection Group" else "Points|Vertices|Faces|Detail"
        let result = [menu("Domain", 0, domains, 0.0, "Which elements carry the group." if kind == "Selection Group" else "Which elements carry the attribute.")]
        if kind == "AttributePromote":
            result.append(menu("Target domain", 1, domains, 2.0, "The domain the attribute moves to."))
        if kind in ["AttributeCreate", "AttributeRandomize"]:
            let size = whole("Tuple size", 1, 1.0, 1.0, 4.0, "Components per element: 1 for a float, 3 for a vector.")
            size.key = "size"
            result.append(size)
            result.append(toggle("Integer", 2, 0.0, "Store whole numbers."))
            result.append(vector("Maximum" if kind == "AttributeRandomize" else "Value", 3, [1.0, 0.0, 0.0, 0.0], "The value per component; components past the tuple size are unused."))
            if kind == "AttributeRandomize":
                result.append(whole("Seed", 7, 1.0, 0.0, 100000.0, "Another seed gives other random values."))
        return result
    if kind == "Normal":
        return [menu("Domain", 0, "Points=0|Faces=2", 0.0, "Smooth normals on points, or flat normals on faces.")]
    if kind == "UVProject":
        return [number("UV scale", 0, 1.0, 0.001, 1000.0, 0.1, "Texture repeats per model unit.", soft = 10.0)]
    if kind == "Color":
        let color = vector("Color", 0, [0.8, 0.4, 0.1], "Point color Cd, linear RGB, multiplied by the material.", 0.0, 1.0)
        color.kind = "color"
        return [color]
    if kind == edit_gsplats.kind_name:
        return edit_gsplats.fields()
    if is_edit(kind):
        return [number("Soft radius", soft_radius_slot, 0.0, 0.0, 100000.0, 0.1, "Points within this distance of the selection follow its moves, less the farther they are. 0 is off.", soft = 5.0),
                menu("Falloff", falloff_slot, "Linear|Quadratic|Cubic|Smooth", 3.0, "How the soft weight falls off with distance."),
                menu("Symmetry", symmetry_slot, "None|X|Y|Z", 0.0, "Mirror every tool across the plane through the origin normal to this axis."),
                toggle("Keep selection", keep_slot, 0.0, "Keep the selected components through topology tools, instead of selecting what the tool made.")]
    return []

## Where a Camera or Light sits: Translate in slots 1-3 and Rotate in 4-6,
## as on Transform. They look and shine down their local -Z.
func placement_fields(position: list[float], rotation: list[float]) -> list[Parameter]:
    return [vector("Translate", 1, position, "Where the object sits."),
            vector("Rotate", 4, rotation, "Rotation about X, then Y, then Z, in degrees; the object faces down its local -Z.", suffix = "°")]

## A camera as USD describes one (UsdGeomCamera): a lens and film back in
## millimetres, clipping and focus in scene units.
func camera_fields() -> list[Parameter]:
    let projection = menu("Projection", 0, "Perspective|Orthographic", 0.0, "Perspective, or parallel rays across the film back.")
    projection.key = "projection"
    let f_stop = number("F-stop", 12, 0.0, 0.0, 128.0, 0.1, "Lens aperture as an f-number; 0 is a pinhole with everything in focus.", soft = 22.0)
    f_stop.key = "fstop"
    let focus = number("Focus distance", 13, 5.0, 0.001, 100000.0, 0.1, "The distance that is sharp.", soft = 50.0)
    focus.disable_when = "{ fstop == 0 }"
    return [projection] + placement_fields([0.0, 1.0, 6.0], [-8.0, 0.0, 0.0]) + [
            number("Focal length", 7, 50.0, 1.0, 2000.0, 1.0, "Lens focal length in millimetres.", soft = 200.0, suffix = " mm"),
            number("Horizontal aperture", 8, 36.0, 0.1, 500.0, 0.1, "Film back width in millimetres (36 is full frame).", suffix = " mm"),
            number("Vertical aperture", 9, 24.0, 0.1, 500.0, 0.1, "Film back height in millimetres; the render resolution's aspect crops it.", suffix = " mm"),
            number("Near clip", 10, 0.1, 0.0001, 100000.0, 0.01, "Nothing nearer than this is seen."),
            number("Far clip", 11, 10000.0, 0.01, 10000000.0, 10.0, "Nothing farther than this is seen."),
            f_stop, focus]

## A light as UsdLux describes one; Area is USD's RectLight.
func light_fields() -> list[Parameter]:
    let shape = menu("Type", 0, "Area|Disk|Sphere|Distant|Dome", 0.0, "Area: a rectangle. Disk and Sphere: round emitters. Distant: parallel light from far away, like the sun. Dome: light from every direction, an HDR environment image wrapped around the scene.")
    shape.key = "type"
    let color = vector("Color", 7, [1.0, 1.0, 1.0], "Linear RGB, multiplied by the intensity.", 0.0, 1.0)
    color.kind = "color"
    let use_temperature = toggle("Use temperature", 12, 0.0, "Tint the light by a blackbody color temperature.")
    use_temperature.key = "usetemperature"
    let temperature = number("Temperature", 13, 6500.0, 1000.0, 20000.0, 100.0, "Color temperature in Kelvin; 6500 is daylight white.", suffix = " K")
    temperature.disable_when = "{ usetemperature == 0 }"
    let width = number("Width", 14, 1.0, 0.0, 100000.0, 0.1, "The rectangle's size along its local X.", soft = 10.0)
    width.hide_when = "{ type != 0 }"
    let height = number("Height", 15, 1.0, 0.0, 100000.0, 0.1, "The rectangle's size along its local Y.", soft = 10.0)
    height.hide_when = "{ type != 0 }"
    let radius = number("Radius", 16, 0.5, 0.0, 100000.0, 0.05, "The disk's or sphere's radius.", soft = 5.0)
    radius.hide_when = "{ type == 0 } { type >= 3 }"
    let angle = number("Angle", 17, 0.53, 0.0, 180.0, 0.01, "The sun's angular diameter in degrees (0.53 is the real sun); larger softens shadows.", suffix = "°")
    angle.hide_when = "{ type != 3 }"
    return [shape] + placement_fields([0.0, 4.0, 0.0], [-90.0, 0.0, 0.0]) + [
            color,
            number("Intensity", 10, 10.0, 0.0, 1000000.0, 0.1, "Brightness, multiplied by 2 to the exposure.", soft = 100.0),
            number("Exposure", 11, 0.0, -30.0, 30.0, 0.1, "Brightness in stops: each step doubles it.", soft = 10.0),
            use_temperature, temperature, width, height, radius, angle,
            toggle("Normalize", 18, 1.0, "Keep the emitted power as the size changes, so resizing changes only softness."),
            toggle("Visible to camera", 19, 0.0, "Show the emitter itself in the image; its light reaches the scene either way.")]

## What the Render node asks of its engine.
func render_fields() -> list[Parameter]:
    let resolution = Parameter("Resolution", 1, 1920.0, 1.0, 16384.0, 1.0, true)
    resolution.kind = "vector"
    resolution.components = 2
    resolution.rest = [1080.0]
    resolution.doc = "Image width and height in pixels."
    return [menu("Engine", 0, "Luce Path", 0.0, "The renderer. Luce Path is luce-render's spectral GPU path tracer."),
            resolution,
            whole("Samples", 3, 128.0, 1.0, 65536.0, "Paths per pixel at most; adaptive sampling stops earlier where the image is clean."),
            menu("Color", 4, "Spectral|RGB", 0.0, "Spectral traces random wavelengths (dispersion, exact color mixing); RGB traces three channels, a little faster."),
            whole("Max bounces", 5, 12.0, 0.0, 1024.0, "The longest a path may get."),
            whole("Diffuse bounces", 6, 4.0, 0.0, 1024.0, "The most diffuse reflections on a path."),
            whole("Glossy bounces", 7, 8.0, 0.0, 1024.0, "The most glossy reflections on a path."),
            whole("Transmission bounces", 8, 12.0, 0.0, 1024.0, "The most refractions on a path."),
            number("Noise threshold", 9, 0.01, 0.0, 1.0, 0.001, "Adaptive sampling stops a pixel once its noise is below this; 0 gives every pixel every sample.", decimals = 4),
            number("Light paths", 28, 0.5, 0.0, 4.0, 0.1, "Paths from the lights a pixel each sample, joined to the camera's: caustics and light through glass converge without fireflies. 0 traces from the camera alone.", soft = 2.0),
            number("Clamp indirect", 10, 0.0, 0.0, 1000000.0, 1.0, "Clip bright indirect samples. Biased: it removes light (most of a caustic) and the image never converges to the true one; 0 is off.", soft = 100.0),
            toggle("Path guiding", 11, 0.0, "Learn where light comes from and send paths there: for interiors lit by bounced light. About a quarter slower a sample.")] + material_fields(12, "Default material", false)

## A shader node's parameters: its settings, then its inputs' constants
## (shader_nodes; a linked input takes its link instead).
func shader_fields(kind: str) -> list[Parameter]:
    let rows: list[Parameter] = []
    if kind == "Math":
        rows.append(menu("Operation", 0, math_operations().join("|"), 0.0, "What it computes from A and B (A alone for Absolute, Sine, Cosine, Floor and Fraction)."))
    if kind == "Image Texture":
        rows.append(toggle("Non-color data", 0, 0.0, "Read the image as stored (roughness, normal maps) rather than as sRGB color."))
    for socket in shader_nodes.inputs(kind):
        if socket.slot < 0:
            continue
        if socket.width == 3:
            let row = vector(socket.label, socket.slot, socket.initial, "", 0.0, 1.0)
            row.kind = "color"
            rows.append(row)
        else:
            rows.append(number(socket.label, socket.slot, socket.initial[0], -1000.0, 1000.0, 0.05))
    return rows

## OpenPBR parameters in value slots from `first` (scene_nodes.material_values
## names them): a Material node's from 0, `full` with coat, transmission and
## opacity and dispersion (30 slots); the Render node's default material, which faces without
## an assigned material take, from 12 (the first 16).
func material_fields(first: int, title: str, full: bool) -> list[Parameter]:
    let base = vector("Base color", first, [0.8, 0.8, 0.8], "Linear ACEScg: the diffuse color, and a metal's color at normal incidence.", 0.0, 1.0)
    base.kind = "color"
    let specular = vector("Specular color", first + 6, [1.0, 1.0, 1.0], "Tints the specular reflection; a metal's color at grazing angles.", 0.0, 1.0)
    specular.kind = "color"
    let emission = vector("Emission color", first + 13, [1.0, 1.0, 1.0], "The color of the emitted light.", 0.0, 1.0)
    emission.kind = "color"
    return [heading(title), base,
            number("Metalness", first + 3, 0.0, 0.0, 1.0, 0.05, "0 is a dielectric (plastic, paint, wood); 1 a metal.", true),
            number("Diffuse roughness", first + 4, 0.0, 0.0, 1.0, 0.05, "0 is Lambertian; higher flattens the diffuse look, like clay or the moon.", true),
            number("Specular weight", first + 5, 1.0, 0.0, 1.0, 0.05, "How strong the specular reflection is.", true),
            specular,
            number("Specular roughness", first + 9, 0.3, 0.0, 1.0, 0.05, "0 is a mirror; 1 is fully rough.", true),
            number("Specular IOR", first + 10, 1.5, 1.0, 3.0, 0.01, "Index of refraction: 1.5 for plastic and glass, 1.33 water, 2.4 diamond."),
            number("Anisotropy", first + 11, 0.0, 0.0, 1.0, 0.05, "Stretches highlights along the surface's tangent, like brushed metal.", true),
            number("Emission", first + 12, 0.0, 0.0, 100000.0, 1.0, "Emitted luminance in nits.", soft = 100.0),
            emission] + (layer_fields(first) if full else [])

## Coat, transmission and opacity: slots first + 16 to first + 29.
func layer_fields(first: int) -> list[Parameter]:
    let coat_color = vector("Coat color", first + 17, [1.0, 1.0, 1.0], "Tints what is seen through the coat, like a colored lacquer.", 0.0, 1.0)
    coat_color.kind = "color"
    let coat = number("Coat", first + 16, 0.0, 0.0, 1.0, 0.05, "A clear layer over everything: lacquer, varnish, car paint.", true)
    coat.key = "coat"
    let roughness = number("Coat roughness", first + 20, 0.0, 0.0, 1.0, 0.05, "0 is a mirror-like clear coat.", true)
    roughness.disable_when = "{ coat == 0 }"
    let ior = number("Coat IOR", first + 21, 1.6, 1.0, 3.0, 0.01, "The coat's index of refraction.")
    ior.disable_when = "{ coat == 0 }"
    let darkening = number("Coat darkening", first + 22, 1.0, 0.0, 1.0, 0.05, "How much light trapped under the coat darkens and saturates the base.", true)
    darkening.disable_when = "{ coat == 0 }"
    coat_color.disable_when = "{ coat == 0 }"
    let transmission_color = vector("Transmission color", first + 24, [1.0, 1.0, 1.0], "Tints light refracted through the surface.", 0.0, 1.0)
    transmission_color.kind = "color"
    let transmission = number("Transmission", first + 23, 0.0, 0.0, 1.0, 0.05, "How much of the base is clear like glass or water instead of opaque.", true)
    transmission.key = "transmission"
    transmission_color.disable_when = "{ transmission == 0 }"
    let dispersion = number("Dispersion", first + 28, 0.0, 0.0, 1.0, 0.05, "Splits refracted light into colors, as a prism does: rainbow caustics and fringes. 1 takes the Abbe number as it is. Spectral renders only.", true)
    dispersion.key = "dispersion"
    dispersion.disable_when = "{ transmission == 0 }"
    let abbe = number("Abbe number", first + 29, 20.0, 1.0, 100.0, 1.0, "How little the index varies with wavelength: crown glass about 60, flint 30, diamond 55; lower splits more.", soft = 90.0)
    abbe.disable_when = "{ transmission == 0 } { dispersion == 0 }"
    return [heading("Coat"), coat, coat_color, roughness, ior, darkening,
            heading("Transmission"), transmission, transmission_color, dispersion, abbe,
            heading("Geometry"), number("Opacity", first + 27, 1.0, 0.0, 1.0, 0.05, "Below 1 cuts the surface away, like a leaf's outline; it casts a full shadow for now.", true)]

## A verb's parameters as rows, in consecutive value slots from 0.
func verb_fields(verb: int) -> list[Parameter]:
    let result: list[Parameter] = []
    var slot = 0
    for parm in 0..<VerbCatalog.parm_count(verb):
        let label = VerbCatalog.parm_label(verb, parm)
        let kind = VerbCatalog.parm_kind(verb, parm)
        let initial = VerbCatalog.parm_initial(verb, parm)
        let low = VerbCatalog.parm_minimum(verb, parm)
        let high = VerbCatalog.parm_maximum(verb, parm)
        let doc = VerbCatalog.parm_doc(verb, parm)
        var row = number(label, slot, initial, low, high, 0.1, doc, VerbCatalog.parm_soft(verb, parm) > 0.0, VerbCatalog.parm_soft(verb, parm))
        if kind == 1:
            row = whole(label, slot, initial, low, high, doc, true)
        elif kind == 2:
            row = toggle(label, slot, initial, doc)
        elif kind == 3:
            let defaults: list[float] = []
            for component in 0..<VerbCatalog.parm_components(verb, parm):
                defaults.append(initial)
            row = vector(label, slot, defaults, doc, low, high)
        elif kind == 4:
            row = menu(label, slot, VerbCatalog.parm_choices(verb, parm), initial, doc)
        result.append(row)
        slot += row.components
    return result

pub func description(kind: str) -> str:
    let verb = VerbCatalog.index_of(kind)
    if verb >= 0:
        return VerbCatalog.description(verb)
    if kind == "Group":
        return "Nested network / double-click to enter"
    if kind == "CAD":
        return "Solid bodies from sketches and features / double-click to model"
    if kind == sketch_node.kind_name:
        return "CAD sketch / curves on a plane, constrained and dimensioned"
    if is_cad_only(kind):
        return "CAD feature / makes a solid body"
    if is_edit(kind):
        return "Select and edit in the viewport; each edit is a step you can undo"
    if kind == "Material":
        return "An OpenPBR material / double-click to build its shader from nodes"
    if is_shader(kind):
        return "Shader node / feeds the OpenPBR Surface"
    if kind == "Assign Material":
        return "Input 1: geometry / Input 2: materials; binds the group's faces"
    if kind == "Camera":
        return "A camera in the scene / adds to its input when connected"
    if kind == "Light":
        return "A light in the scene / adds to its input when connected"
    if kind == "Render":
        return "Render the input's scene through its camera"
    if kind == "Cache":
        return "Save the cooked input to disk, or load it back and freeze upstream"
    if kind == code_cook.kind_name:
        return "Luce Base code run for each point, primitive or vertex, in parallel (Houdini's Wrangle)"
    if kind == script_cook.kind_name:
        return "Luce Base code run once over the whole geometry, any package imported (Houdini's Python SOP)"
    if kind == "Null":
        return "Passes its input through / a named point to organize the flow"
    if kind == "Export":
        return "Write the input to a USD, FBX, OBJ or prism file and pass it on"
    if kind == "CopyToPoints":
        return "Input 1: source / Input 2: target points"
    if kind in ["AttributeCreate", "AttributeRandomize", "AttributeDelete", "Selection Group"]:
        return "P: points / V: corners / F: faces / D: detail"
    if kind == "Color":
        return "Linear RGB point Cd, multiplied by material"
    if kind == "Name":
        return "Names faces: Group fields elsewhere pick them by @name=…"
    return "Geometry operator"

## A CAD feature's parameters.
func cad_fields(kind: str) -> list[Parameter]:
    if kind == sketch_node.kind_name:
        return [menu("Plane", 0, sketch_node.plane_names(), 1.0, "The plane the sketch is drawn on: XY (front), XZ (the ground), YZ (side), or a flat face of the input body (Pick face)."),
                number("Offset", 1, 0.0, -100000.0, 100000.0, 1.0, "How far the plane is moved along its normal.", soft = 100.0)]
    if kind == "Solid Box":
        return [vector("Size", 0, [20.0, 20.0, 20.0], "Width (X), height (Y) and depth (Z), centered on the origin.", 0.001, 100000.0)]
    if kind in ["Solid Cylinder", "Solid Cone"]:
        let rows = [number("Radius", 0, 10.0, 0.001, 100000.0, 0.5, "The base's radius.", soft = 50.0), number("Height", 1, 20.0, 0.001, 100000.0, 0.5, "Along +Y, centered on the origin.", soft = 100.0)]
        if kind == "Solid Cone":
            rows.append(number("Top radius", 2, 0.0, 0.0, 100000.0, 0.5, "0 is a pointed cone; otherwise a frustum.", soft = 50.0))
        return rows
    if kind == "Solid Sphere":
        return [number("Radius", 0, 10.0, 0.001, 100000.0, 0.5, "Centered on the origin.", soft = 50.0)]
    if kind == "Solid Torus":
        return [number("Radius", 0, 10.0, 0.001, 100000.0, 0.5, "The ring's radius, about +Y.", soft = 50.0), number("Tube", 1, 2.5, 0.001, 100000.0, 0.5, "The tube's radius; less than the ring's.", soft = 20.0)]
    if kind == "Extrude":
        return [number("Distance", 0, 10.0, -100000.0, 100000.0, 0.5, "How far the sketch's profiles sweep along its plane's normal; negative goes the other way.", soft = 100.0),
                menu("Operation", 1, "New body|Join|Cut|Intersect", 0.0, "New body: beside the second input's bodies. Join, Cut, Intersect: combined with them."),
                toggle("Symmetric", 2, 0.0, "Sweep half the distance each way from the sketch's plane.")]
    if kind == "Revolve":
        return [menu("Axis", 0, "Plane U|Plane V", 0.0, "The sketch plane's axis through its origin the profiles turn about (they must lie on one side of it)."),
                menu("Operation", 1, "New body|Join|Cut|Intersect", 0.0, "New body: beside the second input's bodies. Join, Cut, Intersect: combined with them."),
                number("Angle", 2, 360.0, 0.1, 360.0, 5.0, "How far the profiles turn, from the sketch plane toward its normal: 360 all the way round; less, closed by the profile at each end.", suffix = "°")]
    if kind == "Mirror Body":
        return [menu("Plane", 0, "YZ (across X)|ZX (across Y)|XY (across Z)", 0.0, "The plane through the origin the body is mirrored across."),
                toggle("Separate bodies", 1, 0.0, "Keep the mirror image a body of its own instead of joining it.")]
    if kind == "Pattern":
        let count = whole("Count", 1, 3.0, 1.0, 1000.0, "How many bodies, the original among them.")
        return [menu("Type", 0, "Linear|Circular", 0.0, "Linear: copies along an axis, Spacing apart. Circular: copies around an axis through the origin, over Angle."),
                count,
                menu("Axis", 2, "X|Y|Z", 0.0, "The axis the copies go along or around."),
                number("Spacing", 3, 20.0, -100000.0, 100000.0, 1.0, "Linear: the distance between copies.", soft = 100.0),
                number("Angle", 4, 360.0, -360.0, 360.0, 5.0, "Circular: the angle the copies spread over (360: evenly around).", suffix = "°"),
                toggle("Separate bodies", 5, 0.0, "Keep the copies bodies of their own instead of joining them.")]
    if kind in ["Fillet", "Chamfer"]:
        let size = number("Radius" if kind == "Fillet" else "Distance", 0, 1.0, 0.0001, 100000.0, 0.1, "The rolling ball's radius." if kind == "Fillet" else "How far the chamfer reaches along each face.", soft = 10.0)
        let chain = toggle("Tangent chain", 2, 1.0, "Each picked edge brings the edges continuing it smoothly: a rounded slot's rim, the edges around an earlier fillet.")
        if kind == "Fillet":
            return [size, menu("Continuity", 1, "G1|G2|G3", 0.0, "G1: a circular fillet. G2: curvature flows into the faces (no jump in reflections). G3: its change too, smoother still. Where three meet at a corner they stop short of it, and a patch as smooth as they are rounds it."), chain]
        return [size, chain]
    if kind == "Boolean":
        return [menu("Operation", 0, "Union|Subtract|Intersect", 0.0, "Union: both bodies as one. Subtract: the first without the second. Intersect: what both hold.")]
    return []