Bonsai: key cut linework on the material of the cut, not the layer set - #9493

Fixes #7830. Does the second half of #7000.

The problem

A material layer's cut linework could never merge with a non-layered element of the same material, whatever JoinCriteria was set to.

The key was built by evaluating every criterion against the element, then — if the cut was a material layer — evaluating every criterion again against the layer and appending those values. A layered cut's key tuple was therefore about twice the length of an unlayered one's, so the two could never hash equal even when every value agreed.

The list was also doing two unrelated jobs at once: deciding which elements merge, and which layers stay apart. It only worked because material.Name and Material.Name happened to cancel at the element level while diverging at the layer level — Material.Name resolves to None on a wall, but to the layer's own IfcMaterial on an IfcMaterialLayer, purely because Material is a real attribute there. That line came from #7700, fixing #7252 and #7369 where every layer hashed alike and collapsed into one polygon.

The change

cut_material — the material of the cut itself: that layer's material for a layered cut, or the element's own material where it has exactly one. The layer pass goes away, so the key is one fixed-length tuple either way and the same material keys identically whether or not it arrived as a layer.

It replaces both material.Name and Material.Name in the defaults. Layers still keep each other apart, so #7252 and #7369 do not regress — each layer keys on its own material, which is exactly what Material.Name was accidentally achieving.

Where nothing identifies a cut's material — no material at all, or several with unlayered geometry — the IFC class is appended instead, so unidentified cuts don't all share one key and merge on contact.

Why not a selector key

cut_material is deliberately join-local vocabulary rather than a new entry in the selector syntax. Which material a cut carries depends on which layer is being drawn — drawing state that no query over the element alone can express; the general syntax can only reach a layer by index (material.item.1.Material.Name), and the index is precisely what the caller knows and the query doesn't. The drawing join code is also the only caller in the tree that ever passed a non-product entity to get_element_value.

Keeping it separate means material.Name still means the layer set name here, exactly as it does in Metadata, IfcCSV and text literals — one query string, one meaning. It also leaves the LayerSetName escape hatch reachable, which hijacking material.* would have closed.

Result

With JoinClasses (#4395) naming the classes and class omitted from JoinCriteria:

JoinClasses  = IfcWall,IfcSlab,IfcFooting
JoinCriteria = cut_material.Name,/Pset_.*Common/.Status,EPset_Status.Status,EPset_Status.UserDefinedStatus

Verified on a real project section. Two footings and the slab's concrete layer merge into a single closed path:

bucket: ['0BvUur15…' (IfcFooting), '2bcEs9SN…' (IfcFooting), '0O$LaON8…' (IfcSlab layer 3405669)]
  3 closed polygons -> 2 unions -> 1 emitted group

while the slab's vapour-barrier layer, each wall's layers, and the unlayered slab outline all stay separate. Confirmed in the output SVG: one <g>, one closed 19-point path, carrying both the IfcFooting and IfcSlab/IfcMaterialLayer classes.

Behaviour change worth flagging

Under the default criteria a layered cut is now keyed on its layer's material alone, where the layer set name previously also participated. Two different layer sets sharing a material will merge where they touch. In the test project that's one case (two wall layer sets both carrying a GENERIC POCHE layer). Arguably the correct drafting convention — same material, no line between them — but it is a change for users who never touch these properties.

Also

JoinCriteria entries are now stripped, as JoinClasses already does. Without it a stray space after a comma stops a query being recognised as a cut_material query and silently disables the layer-aware key.

Related

• Bonsai: stop merged cut linework leaking classes onto disjoint pieces #8807 — the shared class set leaking across disjoint pieces. Independent, but it matters more once more things merge; these two want to land together.
• util.selector: resolve mats.Category via the material set item #9044 — redefines mats.Category via the material set item, for Be able to use 'JoinCriteria' with something like mats.Category. #7000. Worth a look alongside this: cut_material.Category reads the material's own attribute.
• Add cross-coplanar and material/style-change edge classification #9330 — adds merge_duplicate_edges immediately after merge_linework_and_add_metadata. Verified its operator.py hunks still apply cleanly on top of this branch, so the two are independent.

Documentation is deliberately limited to the EPset_Drawing.JoinCriteria pset description, which is what surfaces in the UI. selector_syntax.rst is not updated, since cut_material is not a selector query and doesn't work in IfcCSV or the other tools that page covers. Nothing in the repo documents EPset_Drawing yet; a reference page for it is worth a follow-up, alongside #9358.

🤖 Generated with Claude Code