ifcopenshell.api.style.add_surface_style

Module Contents

ifcopenshell.api.style.add_surface_style.add_surface_style(file: ifcopenshell.file, style: ifcopenshell.entity_instance, ifc_class: SURFACE_STYLE_TYPES = 'IfcSurfaceStyleShading', attributes: dict[str, Any] | None = None) → None

Adds a new presentation item to a surface style

A surface style can have multiple different types of presentation items assigned to it:

  • Shading, this is the simplest item, which defines a single basic colour and transparency that can be used to display the object on a screen. It is an indicative colour of what the object would be in real life. It is commonly incorrectly abused to colour code systems for MEP equipment or object types for structural steel. If you just want to give something a colour, this is what you need.

  • Rendering, this is an advanced extension of shading, which includes the definition of a shader for a rendering engine. You may select the reflectance / lighting model such as PHYSICAL, for PBR style rendering, or FLAT, for flat shading, or PHONG for older biased rendering workflows. Based on the chosen lighting model, you may then specify the appropriate colour maps, such as diffuse colours, specularity, emissive component, etc. These lighting models are fully compatible with glTF and X3D. This should be used if your model is prepared to be rendered by a rendering engine which is compatible with glTF / X3D shader descriptions. If you are doing archviz or 3D rendering, this is what you need.

  • Textures, this is a special type of Rendering presentation item that uses image textures instead of single colours. Textures may be either mapped using a bounding box stretch mapping, or with UV coordinates for mesh-like geometry.

  • Lighting, this is used to define photometrically accurate colour parameters used in lighting simulation. If you are a simulationist, this is what you need.

  • Reflectance, this is a special type of Lighting presentation item which includes some lesser used photometric properties, typically required for advanced materials like glazing.

  • External, this is for any other surface style defined using an external URI. This is relevant if you are using a third-party non-glTF compatible shader definition such as for Cycles, Renderman, V-Ray, etc, or a complex lighting simulation definition, such as for Radiance.

Shading is sufficient for the majority of basic models.

The attributes you specify will depend on the type of presentation item you are adding. An example is shown below, but for full details please refer to the IFC documentation.

Parameters:

  • style (ifcopenshell.entity_instance) – The IfcSurfaceStyle you want to add to presentation item to. See ifcopenshell.api.style.add_style.

  • ifc_class (str) – Choose from IfcSurfaceStyleShading, IfcSurfaceStyleRendering, IfcSurfaceStyleWithTextures, IfcSurfaceStyleLighting, IfcSurfaceStyleReflectance, or IfcExternallyDefinedSurfaceStyle.

  • attributes (dict, optional) – a dictionary of attribute names and values.

Returns:

The newly created presentation item based on the provided ifc_class.

Return type:

ifcopenshell.entity_instance

Example:

# Create a new surface style
style = ifcopenshell.api.style.add_style(model)

# Create a simple shading colour and transparency.
ifcopenshell.api.style.add_surface_style(model,
    style=style, ifc_class="IfcSurfaceStyleShading", attributes={
        "SurfaceColour": { "Name": None, "Red": 1.0, "Green": 0.8, "Blue": 0.8 },
        "Transparency": 0., # 0 is opaque, 1 is transparent
    })

# Alternatively, create a rendering style.
ifcopenshell.api.style.add_surface_style(model,
    style=style, ifc_class="IfcSurfaceStyleRendering", attributes={
        # A surface colour and transparency is still supplied for
        # viewport display only. This will supersede the shading
        # presentation item.
        "SurfaceColour": { "Name": None, "Red": 1.0, "Green": 0.8, "Blue": 0.8 },
        "Transparency": 0., # 0 is opaque, 1 is transparent

        # NOTDEFINED is assumed to be a PHYSICAL (PBR) lighting
        # model. In IFC4X3, you may choose PHYSICAL directly.
        "ReflectanceMethod": "NOTDEFINED",

        # For PBR shading, you may specify these parameters:
        "DiffuseColour": { "Name": None, "Red": 0.9, "Green": 0.8, "Blue": 0.8 },
        "SpecularColour": 0.1, # Metallic factor
        "SpecularHighlight": {"SpecularRoughness": 0.5}, # Roughness factor
    })
ifcopenshell.api.style.add_surface_style.SURFACE_STYLE_TYPES