`ifcopenshell.api.style`¶

Manage visual styles of geometry (colours, transparency, rendering, etc)

Geometry may have visual styles associated with it, including surface styles, 2D curve styles, text styles, and more. Surface styles are most commonly used for simple colouring.

Submodules¶

Package Contents¶

ifcopenshell.api.style.add_style(file: ifcopenshell.file, name: str | None = None, ifc_class='IfcSurfaceStyle') → ifcopenshell.entity_instance¶

Add a new presentation style

A presentation style is a container of visual settings (called presentation items) that affect the appearance of objects. There are four types of style:

Surface styles, which give 3D objects (which have surfaces / faces) their colours and textures. This is the most common type of style.
Curve styles, which give 2D and 3D curves, lines, polylines, their stroke thickness and colour.
Fill area styles, which gives 2D polygons and flat 3D planes their colours, hatch patterns, tiled patterns, and pattern scales.
Text styles, which gives text their font family, weight, variant, size, indentation, alignment, decoration, spacing, and transformation.

Once you have created a presentation style object, you can further define the properties of your style using other API functions by adding presentation items, such as ifcopenshell.api.style.add_surface_style.

Parameters:

name (str,optional) – The name of the style. Used to easily identify it using a style library.
ifc_class (str) – Choose from IfcSurfaceStyle, IfcCurveStyle, IfcFillAreaStyle, or IfcTextStyle.

Returns:

The newly created style element, based on the provided ifc_class.

Return type:

ifcopenshell.entity_instance

Example:

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

ifcopenshell.api.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_textures(file: ifcopenshell.file, material: bpy.types.Material | None = None, textures: list[dict] | None = None, uv_maps: list[ifcopenshell.entity_instance] | None = None) → list[ifcopenshell.entity_instance]¶

Add surface texture based on a Blender material definition or texture data.

Either material or textures should be provided.

Parameters:

material (bpy.types.Material, optional) – The Blender material definition with a node tree that is compatible with glTF. See one of the valid combinations here: https://docs.blender.org/manual/en/dev/addons/import_export/scene_gltf2.html
uv_maps (list[ifcopenshell.entity_instance]) – A list of IfcIndexedTextureMap for any IfcTessellatedFaceSets that the representation has, obtained from the HasTextures attribute.
textures (list[dict], optional) –
A list of dictionaries containing:
1. Attributes to create IfcImageTexture.
2. One additional parameter uv_mode to map IfcImageTexture to correct IfcTextureCoordinate type.
Possible uv_mode values:
- UV - use IfcTextureCoordinate from uv_maps parameter;
- Generated - IfcTextureCoordinateGenerator with mode COORD (autogenerated UV based on geometry);
- Camera - IfcTextureCoordinateGenerator with mode COORD_EYE (autogenerated UV based on camera position)

Returns:

A list of IfcImageTexture

Return type:

list[ifcopenshell.entity_instance]

ifcopenshell.api.style.assign_material_style(file: ifcopenshell.file, material: ifcopenshell.entity_instance, style: ifcopenshell.entity_instance, context: ifcopenshell.entity_instance, should_use_presentation_style_assignment: bool = False) → None¶

Assigns a style to a material

A style may either be assigned directly to an object’s representation, or to a material which is then associated with the object. If both exist, then the style assigned directly to the object’s representation takes precedence. It is recommended to use materials and assign styles to materials. This API function provides that capability.

Parameters:

material (ifcopenshell.entity_instance) – The IfcMaterial which you want to assign the style to.
style (ifcopenshell.entity_instance) – The IfcPresentationStyle (typically IfcSurfaceStyle) that you want to assign to the material. This will then be applied to all objects that have that material.
context (ifcopenshell.entity_instance) – The IfcGeometricRepresentationSubContext at which this style should be used. Typically this is the Model BODY context.
should_use_presentation_style_assignment (bool) – This is a technical detail to accomodate a bug in Revit. This should always be left as the default of False, unless you are finding that colours aren’t showing up in Revit. In that case, set it to True, but keep in mind that this is no longer a valid IFC. Blame Autodesk.

Returns:

None

Return type:

None

Example:

# A model context is needed to store 3D geometry
model3d = ifcopenshell.api.context.add_context(model, context_type="Model")

# Specifically, we want to store body geometry
body = ifcopenshell.api.context.add_context(model,
    context_type="Model", context_identifier="Body", target_view="MODEL_VIEW", parent=model3d)

# Let's create a new wall. The wall does not have any geometry yet.
wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# Let's use the "3D Body" representation we created earlier to add a
# new wall-like body geometry, 5 meters long, 3 meters high, and
# 200mm thick
representation = ifcopenshell.api.geometry.add_wall_representation(model,
    context=body, length=5, height=3, thickness=0.2)

# Assign our new body geometry back to our wall
ifcopenshell.api.geometry.assign_representation(model,
    product=wall, representation=representation)

# Place our wall at the origin
ifcopenshell.api.geometry.edit_object_placement(model, product=wall)

# Let's prepare a concrete material. Note that our concrete material
# does not have any colours (styles) at this point.
concrete = ifcopenshell.api.material.add_material(model, name="CON01", category="concrete")

# Assign our concrete material to our wall
ifcopenshell.api.material.assign_material(model,
    products=[wall], type="IfcMaterial", material=concrete)

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

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

# Now any element (like our wall) with a concrete material will have
# a grey colour applied.
ifcopenshell.api.style.assign_material_style(model, material=concrete, style=style, context=body)

ifcopenshell.api.style.assign_representation_styles(file: ifcopenshell.file, shape_representation: ifcopenshell.entity_instance, styles: list[ifcopenshell.entity_instance], replace_previous_same_type_style: bool = True, should_use_presentation_style_assignment: bool = False) → list[ifcopenshell.entity_instance]¶

Assigns a style directly to an object representation

If you want to assign styles to a material instead (recommended), then please see ifcopenshell.api.style.assign_material_style.

Parameters:

shape_representation (ifcopenshell.entity_instance) – The IfcShapeRepresentation of the object that you want to assign styles to. This implicitly defines the context at which the styles should be used.
styles (list[ifcopenshell.entity_instance]) – A list of presentation styles, typically IfcSurfaceStyle. The number of items in the list should correlate with the number of items in the shape_representation’s Items attribute. If you have more items than styles, the last style is used.
replace_previous_same_type_style (bool) – Remove previously assigned styles of the same type as currently assign style`. Defaults to True.
should_use_presentation_style_assignment (bool) – This is a technical detail to accomodate a bug in Revit. This should always be left as the default of False, unless you are finding that colours aren’t showing up in Revit. In that case, set it to True, but keep in mind that this is no longer a valid IFC. Blame Autodesk.

Returns:

List of created IfcStyledItems

Return type:

list[ifcopenshell.entity_instance]

Example:

# A model context is needed to store 3D geometry
model3d = ifcopenshell.api.context.add_context(model, context_type="Model")

# Specifically, we want to store body geometry
body = ifcopenshell.api.context.add_context(model,
    context_type="Model", context_identifier="Body", target_view="MODEL_VIEW", parent=model3d)

# Let's create a new wall. The wall does not have any geometry yet.
wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")

# Let's use the "3D Body" representation we created earlier to add a
# new wall-like body geometry, 5 meters long, 3 meters high, and
# 200mm thick
representation = ifcopenshell.api.geometry.add_wall_representation(model,
    context=body, length=5, height=3, thickness=0.2)

# Assign our new body geometry back to our wall
ifcopenshell.api.geometry.assign_representation(model,
    product=wall, representation=representation)

# Place our wall at the origin
ifcopenshell.api.geometry.edit_object_placement(model, product=wall)

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

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

# Now specifically our wall only will be coloured grey.
ifcopenshell.api.style.assign_representation_styles(model,
    shape_representation=representation, styles=[style])

ifcopenshell.api.style.edit_presentation_style(file: ifcopenshell.file, style: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None¶

Edits the attributes of an IfcPresentationStyle

For more information about the attributes and data types of an IfcPresentationStyle, consult the IFC documentation.

Parameters:

style (ifcopenshell.entity_instance) – The IfcPresentationStyle entity you want to edit
attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

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

# Change the name of the style to "Foo"
ifcopenshell.api.style.edit_presentation_style(model, style=style, attributes={"Name": "Foo"})

ifcopenshell.api.style.edit_surface_style(file: ifcopenshell.file, style: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None¶

Edits the attributes of an IfcPresentationItem

For more information about the attributes and data types of an IfcPresentationItem, consult the IFC documentation.

The IfcPresentationItem is expected to be one of IfcSurfaceStyleShading, IfcSurfaceStyleRendering, IfcSurfaceStyleWithTextures, IfcSurfaceStyleLighting, IfcSurfaceStyleReflectance, or IfcExternallyDefinedSurfaceStyle.

To represent a colour, a nested dictionary should be used. See the example below.

Parameters:

style (ifcopenshell.entity_instance) – The IfcPresentationStyle entity you want to edit
attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

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

# Create a blank rendering style.
rendering = ifcopenshell.api.style.add_surface_style(model,
    style=style, ifc_class="IfcSurfaceStyleRendering")

# Edit the attributes of the rendering style.
ifcopenshell.api.style.edit_surface_style(model,
    style=rendering, 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.remove_style(file: ifcopenshell.file, style: ifcopenshell.entity_instance) → None¶

Removes a presentation style

All of the presentation items of the style will also be removed.

Parameters:: style (ifcopenshell.entity_instance) – The IfcPresentationStyle to remove.
Returns:: None
Return type:: None

Example:

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

# Not anymore!
ifcopenshell.api.style.remove_style(model, style=style)

ifcopenshell.api.style.remove_styled_representation(file: ifcopenshell.file, representation: ifcopenshell.entity_instance) → None¶

Removes a styled representation

Styled representations are typically associated with materials. This removes the representation but not the underlying styles.

Parameters:: representation (ifcopenshell.entity_instance) – The IfcStyledRepresentation to remove.
Returns:: None
Return type:: None

Example:

# Remove a styled representation
ifcopenshell.api.style.remove_styled_representation(model, representation=representation)

ifcopenshell.api.style.remove_surface_style(file: ifcopenshell.file, style: ifcopenshell.entity_instance) → None¶

Removes a presentation item from a presentation style

Parameters:: style (ifcopenshell.entity_instance) – The IfcPresentationItem to remove.
Returns:: None
Return type:: None

Example:

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

# Create a simple shading colour and transparency.
shading = 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
    })

# Remove the shading item
ifcopenshell.api.style.remove_surface_style(model, style=shading)

ifcopenshell.api.style.unassign_material_style(file: ifcopenshell.file, material: ifcopenshell.entity_instance, style: ifcopenshell.entity_instance, context: ifcopenshell.entity_instance) → None¶

Unassigns a style to a material

This does the inverse of assign_material_style.

Parameters:

material (ifcopenshell.entity_instance) – The IfcMaterial which you want to unassign the style from.
style (ifcopenshell.entity_instance) – The IfcPresentationStyle (typically IfcSurfaceStyle) that you want to unassign from material. This will then be applied to all objects that have that material.
context (ifcopenshell.entity_instance) – The IfcGeometricRepresentationSubContext at which this style should be unassigned. Typically this is the Model BODY context.

Returns:

None

Return type:

None

Example:

ifcopenshell.api.style.unassign_material_style(model, material=concrete, style=style, context=body)

ifcopenshell.api.style.unassign_representation_styles(file: ifcopenshell.file, shape_representation: ifcopenshell.entity_instance, styles: list[ifcopenshell.entity_instance], should_use_presentation_style_assignment: bool = False) → None¶

Unassigns styles directly assigned to an object representation

This does the inverse of assign_representation_styles.

Parameters:

shape_representation (ifcopenshell.entity_instance) – The IfcShapeRepresentation of the object that you want to unassign styles from.
styles (list[ifcopenshell.entity_instance]) – A list of presentation styles, typically IfcSurfaceStyle. The number of items in the list should correlate with the number of items in the shape_representation’s Items attribute. If you have more items than styles, the last style is used.
should_use_presentation_style_assignment (bool) – This is a technical detail to accomodate a bug in Revit. This should always be left as the default of False, unless you are finding that colours aren’t showing up in Revit. In that case, set it to True, but keep in mind that this is no longer a valid IFC. Blame Autodesk.

Returns:

None

Return type:

None

Example:

ifcopenshell.api.style.unassign_representation_styles(model,
    shape_representation=representation, styles=[style])

ifcopenshell.api.style¶

Submodules¶

Package Contents¶

`ifcopenshell.api.style`¶