Luce packages
LuceLuce BaseLuciaOS

dymokomi/luced-3d

Source of release 0.11.6

0.11.6 / src / tool_docs.luc

## docs/TOOLS.md, generated from the tool registry: Geo's tools, then
## CAD's, each by section and family with its node kind, where it runs,
## what it picks, the row a drag sets, its gesture and its rows with their
## starting values. tools/tool_docs.py writes the file; a test fails when it
## is stale.
from tool_record import Tool
from parameter_rows import Parameter
import tool_registry

## The whole page for `tools`.
pub func markdown(tools: list[Tool]) -> str:
    var text = "# Tools\n\nGenerated from the tool registry (`src/tool_registry.luc`) by `tools/tool_docs.py`; do not edit\nby hand. A test fails when this page is stale.\n\n"
    text += "Every tool is declared once. Its node, its Edit step, the tool bar, the Create, Modify and Select\nmenus, the A/S/D marking menus, the right-click menu, Repeat, its prompt, its icon and this page\nall come from that declaration (docs/research/POLY-MODELING.md §3). The mesh tools are\nluce-geocore's verbs; each CAD tool is a `src/tool_<name>.luc` listed in `src/cad_tools.luc`.\n"
    text += part("Geo", "Edit Mesh and the Geo context's nodes.", geo(tools, true))
    text += part("CAD", "Edit CAD's steps and the CAD context's nodes. A node keeps what it picks by name (faces, edges by\nthe faces they lie between, curves), so it holds as the chain upstream changes; a step keeps the\nselection it ran on.", geo(tools, false))
    return text

## One part of the page: its tools by section and family.
func part(title: str, intro: str, tools: list[Tool]) -> str:
    var text = f"\n## {title}\n\n{intro}\n"
    for section in ["Create", "Modify", "Select"]:
        let families = families_in(tools, section)
        if families.length == 0:
            continue
        text += f"\n### {section}\n"
        if section == "Select":
            text += select_intro()
        for family in families:
            text += f"\n#### {family}\n"
            for tool in tools:
                if tool.section == section and tool.family == family:
                    text += entry(tool)
    return text

## The Geo tools of `tools` (`meshes`), or the CAD ones.
func geo(tools: list[Tool], meshes: bool) -> list[Tool]:
    let result: list[Tool] = []
    for tool in tools:
        if ("cad" in tool.contexts or "Edit CAD" in tool.kinds) != meshes:
            result.append(tool)
    return result

## The families of `section`, in the menus' order.
func families_in(tools: list[Tool], section: str) -> list[str]:
    let found: list[str] = []
    for tool in tools:
        if tool.section == section and not (tool.family in found):
            found.append(tool.family)
    let result: list[str] = []
    for rank in 0..<tool_registry.family_order().length + 1:
        for family in found:
            if tool_registry.family_rank(family) == rank:
                result.append(family)
    return result

## One tool: its heading, what it does, where it runs and its rows.
func entry(tool: Tool) -> str:
    var text = f"\n##### {tool.label}\n\n{tool.doc}.\n\n"
    let named = level_words(tool)
    text += "- " + where(tool) + ".\n"
    text += f"- Works on {named}" + (", or everything when nothing is selected" if tool.whole else "") + ".\n"
    for pick in (tool.picks[1..] if tool.picks.length > 1 else []):
        text += f"- Also picks {pick.label.lower()}" + (f": {pick.doc}" if pick.doc != "" else ".") + "\n"
    if tool.first_pick().prompt != "":
        text += f"- With nothing selected: \"{tool.first_pick().prompt}\".\n"
    if tool.function != "":
        text += f"- Group function: `{tool.function}(group{arguments(tool)})`.\n"
    if tool.gesture != "":
        text += f"- Gesture: {gesture_text(tool.gesture)}.\n"
    if let row = tool.row_at(tool.drag):
        text += f"- {drag_text(tool, row.name)}\n"
    if tool.keys.length > 0:
        text += f"- While its drag lasts: {keys_text(tool)}.\n"
    let rows = valued(tool.rows)
    if rows.length == 0:
        return text
    text += "\n| Row | Starts at | On the tool bar | What it does |\n| --- | --- | --- | --- |\n"
    for row in rows:
        text += f"| {row.name} | {starting(row)} | {"yes" if row.in_steps else "no"} | {row.doc} |\n"
    return text

## A tool's drag keys in words: "A drags Width, P drags Shape, M cycles
## Width Type, C flips Clamp overlap".
func keys_text(tool: Tool) -> str:
    let parts: list[str] = []
    for key in tool.keys:
        let row = tool.row_at(key.parm) else continue
        let verb = "drags" if key.action == "drag" else ("cycles" if key.action == "cycle" else "flips")
        parts.append(f"{key.key} {verb} {row.name}")
    return parts.join(", ")

## A group function's arguments after the group: its rows' names, in order.
func arguments(tool: Tool) -> str:
    var text = ""
    for row in valued(tool.rows):
        let name = row.name.lower().replace(" ", "_")
        if row.components == 3:
            text += f", {name}_x, {name}_y, {name}_z"
        else:
            text += ", " + name
    return text

## What every Select tool shares: how it runs, its rows on the tool bar, its
## group function, and the viewport's click gestures.
func select_intro() -> str:
    var text = "\nA Select tool changes the selection only: from D, the right-click Select submenu or Modify ›\nSelection it runs on what is selected (a tool that looks at everything runs on everything when\nnothing is), its rows stay on the tool bar while its selection does, and a change runs it again.\nAs a node it is a Select node whose output selection the viewport adopts. Its group function is\nthe same rule in a node's Group, run on every cook: `sharp(*, 30)`, `loop(p6-7)`.\n\n"
    text += "Click gestures on a mesh's components:\n\n| Gesture | Edge | Face or point |\n| --- | --- | --- |\n"
    text += "| Double-click | Its loop; again on a boundary edge, the whole boundary | Its island |\n"
    text += "| Shift + double-click | Add the loop; on the loop of the edge picked last, only the run between | Add the island; beside the face picked last, the face loop through both |\n"
    text += "| Cmd/Ctrl + double-click | Add its ring | Remove the island |\n"
    text += "| Shift + Cmd/Ctrl + double-click | Remove the loop | Remove the island |\n"
    text += "| Shift + Cmd/Ctrl + click | The shortest path from the element picked last, added | The same |\n\n"
    text += "Hovering an edge shows the loop a double-click would take (its ring with Cmd/Ctrl held).\n"
    return text

func valued(rows: list[Parameter]) -> list[Parameter]:
    let result: list[Parameter] = []
    for row in rows:
        if row.valued() or row.value_ramp():
            result.append(row)
    return result

## Where it is a node and a step ("Node `Fillet` in CAD; a step of Edit
## CAD").
func where(tool: Tool) -> str:
    let parts: list[str] = []
    if tool.contexts.length > 0:
        parts.append(f"Node `{tool.name}` in {contexts(tool).join(" and ")}")
    if tool.kinds.length > 0:
        let verb = f" (`{tool.verb}`)" if tool.verb != tool.name else ""
        parts.append(f"a step of {tool.kinds.join(", ")}{verb}" if parts.length > 0 else f"A step of {tool.kinds.join(", ")}{verb}")
    return parts.join("; ")

## The levels its first pick takes, in words ("edges or faces"): Edit
## CAD's names for a CAD tool.
func level_words(tool: Tool) -> str:
    if "Edit CAD" in tool.kinds or "cad" in tool.contexts:
        return tool.levels_text(["Objects", "CVs", "Edges", "Faces", "Smart", "Patches", "Curves"])
    return tool.levels_text(["Objects", "Points", "Edges", "Faces"])

func contexts(tool: Tool) -> list[str]:
    let result: list[str] = []
    for context in tool.contexts:
        result.append("Geo" if context == "geometry" else ("CAD" if context == "cad" else context))
    return result

func gesture_text(gesture: str) -> str:
    if gesture == "stroke":
        return "a stroke dragged across the model"
    if gesture == "place":
        return "clicks place its corners when nothing is selected; Enter finishes"
    if gesture == "hover":
        return "the edge under the pointer shows what it makes, the wheel sets the count; a click makes it there"
    if gesture == "knife":
        return "clicks place the stroke's points on the surface (points snap, Ctrl edge middles, Shift none; C holds 15° angles, Z cuts through, Backspace takes a point back, the first point again closes); Enter cuts"
    return gesture

## What the viewport's drag does after the tool runs (tool_drag.luc).
func drag_text(tool: Tool, row: str) -> str:
    let how = ["length", "normal", "amount", "angle", "slide"]
    let ways = ["hauled away from the selection's center", "along the selection's average normal", "rightward, its range over 300 points", "turned about the selection's center", "along the rails of the element under the pointer"]
    var way = ""
    for at in 0..<how.length:
        if how[at] == tool.drag_mode:
            way = ways[at]
    var text = f"After it runs, {"moving the pointer" if tool.follows else "a drag in the viewport"} sets {row} ({way})"
    text += "; a click keeps it"
    if let wheel = tool.row_at(tool.wheel):
        text += f", the wheel steps {wheel.name}"
    if let axis = tool.row_at(tool.axis):
        text += f", X, Y or Z locks {axis.name} to that axis"
    return text + "."

## A row's starting value as its pane shows it.
func starting(row: Parameter) -> str:
    if row.value_ramp():
        return "a ramp"
    if row.kind == "toggle":
        return "on" if row.initial != 0.0 else "off"
    if row.kind == "menu":
        let items = row.items.split("|")
        let at = int(row.initial)
        return items[at] if at >= 0 and at < items.length else str(row.initial)
    if row.kind == "vector":
        let parts = [number_text(row, row.initial)]
        for value in row.rest:
            parts.append(number_text(row, value))
        return parts.join(", ")
    return number_text(row, row.initial)

func number_text(row: Parameter, value: float) -> str:
    return str(int(value)) if row.integer else str(value)