Example: a node variant

Sometimes you want to offer a different implementation of an existing node — a domain-specific version of a generic one. overrides="pkg.node" registers your step as a variant of that node identity; override_mode decides whether it replaces the original or coexists with it.

The code#

# tool.py
from lsdtools import Tool, Source, Table

tool = Tool("mim_openpit", label="Open Pit")


@tool.load(overrides="mim.solid", override_mode="coexist", source_kinds=("file",))
def pit_shell(src: Source, bench_height: float = 15.0) -> Table:
    """Build a pit-shell solid from survey points — a variant of the base `mim.solid` node."""
    t = src.read()
    bench = t["z"] / bench_height # a whole-column expression
    return t.with_column("bench", bench)

What each line does#

• Node identity is always f"{tool_name}.{fn_name}". The base node here is mim.solid — the solid step of a tool named mim (the lsd-mim package).
• overrides="mim.solid" — registers pit_shell as a variant of that identity. It does not need to import lsd-mim; it just names the identity.
• override_mode="coexist" — both stay addable. The base mim.solid and your pit_shell each appear in the palette, and the node's variants dropdown lets the user pick which one a given node uses. override_mode="replace" (the default) instead makes your provider win the identity, so existing mim.solid nodes silently use pit_shell.
• pit_shell's body — a normal load: read the picked file, then add a bench column derived from z. t["z"] / bench_height is a single-kernel Column expression.

Run it in Python#

Because it coexists, pit_shell is a fully-functional load on its own:

from lsdtools import Engine, Source, Table

Table({"x": [0.0], "y": [0.0], "z": [30.0]}).write_csv("survey.csv")

Engine().run(pit_shell(Source.file("survey.csv"), bench_height=15.0)).output.print()
# → x y z bench
# 0 0 30 2

To make your variant the active provider for a whole project — the programmatic equivalent of the variants dropdown — call Engine.set_variant:

eng = Engine("pit.lsd")
eng.set_variant("mim.solid", mode="replace", provider="mim_openpit")
# → every live `mim.solid` node now runs pit_shell; returns the number of steps swapped

Where the user picks it#

In the desktop Package Manager, the Variants section lists every identity that has more than one provider. Choosing one there is persisted in the .lsd project (package_state.variants) and swaps live nodes instantly.

Try changing it#

• Switch to override_mode="replace" and reopen the project — existing mim.solid nodes adopt your step with no re-wiring.
• Override a shape instead: @tool.shape(overrides="mim.wireframe", override_mode="coexist").
• Add a bench_height validation rule via a dialog= so the value can't be zero.

Related#

Learn — Node variants · The Package Manager · Load steps

API — Engine · Tool · PackageManager

Examples — A complete package · File loader