Without 'Material.Name' layers merge. - #7700

This is through hard won trial and error. Not entirely sure why Material.Name is necessary to not merge the layers--seems counterintuitive for the JoinCriteria parameter.

from AI...

JoinCriteria functions as an equality predicate — two elements merge if and only if they produce identical values for every query in the list. The problem is that this same predicate is evaluated against both the element and its IfcMaterialLayer in a single concatenated key, meaning the list is simultaneously controlling two distinct merging decisions with different semantics and different target entities.

Material.Name works as a layer discriminator not because it expresses that intent, but because getattr(IfcMaterialLayer, "Material") happens to be a valid direct attribute in the schema, returning a distinct IfcMaterial per layer, while the same query returns None on a wall — so it silently has no effect at the element level but a significant effect at the layer level.

The practical problem is that this is a hidden coupling: a developer reading JoinCriteria has no way to know it's also controlling layer behaviour, a developer tuning layer rendering has no way to know they're editing element merge criteria, and the default list as shipped only works correctly because Material.Name and material.Name happen to cancel each other out at the element level while diverging at the layer level — which is a fragile invariant that could easily break if someone reasonably decides to clean up what looks like a duplicate entry.

also from AI....

Now we can see exactly what happens. Looking at _get_element_value:

material.Name (lowercase)

python

elif key in ("material", "mat"):
    value = ifcopenshell.util.element.get_material(value, should_skip_usage=True)

It hits this explicit special-case branch, which traverses HasAssociations relationships, handles IfcMaterialLayerSetUsage → ForLayerSet, inherits from the type element, etc. Then on the next iteration, .Name is resolved as a direct attribute on the returned material entity — with the extra quirk that IfcMaterialLayerSet.Name is silently remapped to LayerSetName:

python

if key == "Name" and value.is_a("IfcMaterialLayerSet"):
    key = "LayerSetName"

Material.Name (uppercase)

It doesn't match any special keyword. It falls through to the isinstance(value, ifcopenshell.entity_instance) branch and does:

python

attribute = getattr(value, key, None)  # key = "Material"

So it's looking for a direct Material attribute on the element itself. A small number of IFC entities actually do have a direct Material attribute — notably IfcMaterialLayer and IfcMaterialProfile. So Material.Name would only return something meaningful if the element being evaluated is one of those entities, not a regular building element like IfcWall.

This confirms the earlier suspicion, but more precisely: Material.Name isn't completely useless — it's just only meaningful in a context where the current value in the traversal chain is already a material layer or profile, not a top-level building element. In the join_criteria context where it's applied directly to an IfcWall or IfcSlab, it would return None for almost all elements.

when a wall, for example, with an IfcMaterialLayerSet, when Material.Name is used, the layer print out separately, but when you don't, the layers merge in the svg. Can you help me understand why?

This is a subtle but elegant interaction between two parts of the code. The key is that join_criteria is evaluated against both the element and the layer:

python

keys = []
for query in join_criteria:
    key = ifcopenshell.util.selector.get_element_value(element, query)
    keys.append(key)

if layer:
    for query in join_criteria:
        key = ifcopenshell.util.selector.get_element_value(layer, query)
        keys.append(key)

hash_keys = hash(tuple(keys))

The layer here is an IfcMaterialLayer entity, retrieved via the layer-id attribute stamped onto the SVG group by generate_material_layers.

Now the difference becomes clear:

• material.Name on an IfcMaterialLayer — hits the special keyword branch, calls get_material() on the layer, which traverses relationships. IfcMaterialLayer doesn't have material associations in that sense, so this likely returns None for all layers — making them indistinguishable.
• Material.Name on an IfcMaterialLayer — falls through to getattr(layer, "Material", None), and IfcMaterialLayer does have a direct Material attribute in the IFC schema. So this returns the actual IfcMaterial entity, and then .Name gives the material name — which is different for each layer.

So with Material.Name in the criteria, each layer gets a unique value contributing to its hash key, meaning they never merge. Without it, layers of the same wall class end up with the same hash and get unioned together into a single polygon.

In other words, Material.Name isn't redundant with material.Name at all — they operate on different entities and serve completely different purposes in this context.