bim2sim.utilities package

Submodules

bim2sim.utilities.check_docstrings module

bim2sim.utilities.common_functions module

bim2sim.utilities.common_functions.all_subclasses(cls, as_names: bool = False, include_self: bool = False)

Get all subclasses of the given subclass, even subsubclasses and so on

Args:: cls: class for which to find subclasses as_names: boolean, if True the subclasses are returned as names include_self: boolean, if True include evaluated class to subclasses.

bim2sim.utilities.common_functions.angle_equivalent(angle)

bim2sim.utilities.common_functions.combine_usages(common_usages, custom_usages) → dict: combines the custom and common usages to one dictionary

bim2sim.utilities.common_functions.create_plotly_graphs_from_df(self)

bim2sim.utilities.common_functions.download_library(repo_url: str, branch_name: str, clone_dir: Path)

Clones a Git repository and checks out a specific branch, or updates the repository if it already exists.

This function clones the specified Git repository into the given directory and checks out the specified branch. If the directory already exists and is a Git repository, it will perform a ‘git pull’ to update the repository instead of cloning.

Args:

repo_url (str): The URL of the Git repository to clone or update. branch_name (str): The name of the branch to check out. clone_dir (Path): The directory where the repository should be cloned

or updated.

Returns:

None

Raises:

git.GitCommandError: If there is an error during the cloning, checkout,: or pull process.

Exception: If the directory exists but is not a Git repository.

bim2sim.utilities.common_functions.filter_elements(elements: dict | list, type_name, create_dict=False) → list | dict

Filters the inspected elements by type name (e.g. Wall) and returns them as list or dict if wanted

Args:: elements: dict or list with all bim2sim elements type_name: str or element type to filter for create_dict (Boolean): True if a dict instead of a list should be

created
Returns:: elements_filtered: list of all bim2sim elements of type type_name

bim2sim.utilities.common_functions.get_common_pattern_usage() → dict

bim2sim.utilities.common_functions.get_custom_pattern_usage(custom_usages_path: Path) → dict: gets custom usages based on given json file.

bim2sim.utilities.common_functions.get_material_templates()

bim2sim.utilities.common_functions.get_pattern_usage(use_conditions: dict, custom_usages_path: Path): get usage patterns to use it on the thermal zones get_usage

bim2sim.utilities.common_functions.get_spaces_with_bounds(elements: dict)

Get spaces (ThermalZone) that provide space boundaries.

This function extracts spaces from an instance dictionary and returns those spaces that hold space boundaries.

Args:: elements: dict[guid: element]

bim2sim.utilities.common_functions.get_type_building_elements()

bim2sim.utilities.common_functions.get_type_building_elements_hvac()

bim2sim.utilities.common_functions.get_use_conditions_dict(custom_use_cond_path: Path) → dict

bim2sim.utilities.common_functions.group_by_levenshtein(entities, similarity_score)

Groups similar entities based on the similarity of their ‘Name’ attribute.

Args:

entities (list): A list of objects with a ‘Name’ attribute. similarity_score (float): Similarity threshold between 0 and 1.

0 means all objects will be grouped together, 1 means only identical
strings are grouped.

Returns:

dict: A dictionary where keys are representative entities and values are: lists of similar entities.

bim2sim.utilities.common_functions.remove_umlaut(string): Removes umlauts from strings and replaces them with the letter+e convention :param string: string to remove umlauts from :return: unumlauted string

bim2sim.utilities.common_functions.rm_tree(pth): Remove an empty or non-empty directory using pathlib

bim2sim.utilities.common_functions.translate_deep(text, source='auto', target='en'): translate function that uses deep_translator package with Google Translator

bim2sim.utilities.common_functions.validateJSON(json_data: str | Path)

bim2sim.utilities.common_functions.vector_angle(vector): returns the angle between y-axis and vector

bim2sim.utilities.common_functions.wildcard_match(pattern, text)

Check if a text string matches a pattern containing ‘*’ wildcards.

Args:

pattern (str): The pattern string that may contain ‘*’ wildcards. text (str): The text string to be compared against the pattern.

Returns:

bool: True if the text matches the pattern, considering wildcards.: False otherwise.

bim2sim.utilities.pyocc_tools module

Common tools for handling OCC Shapes within the bim2sim project.

class bim2sim.utilities.pyocc_tools.PyOCCTools

Bases: object

Class for Tools handling and modifying Python OCC Shapes

static check_pnt_in_solid(solid: TopoDS_Solid, pnt: gp_Pnt, tol=1e-06) → bool

Check if a gp_Pnt is inside a TopoDS_Solid.

This method checks if a gp_Pnt is included in a TopoDS_Solid. Returns True if gp_Pnt is included, else False.

Args:: solid: TopoDS_Solid where the gp_Pnt should be included pnt: gp_Pnt that is tested tol: tolerance, default is set to 1e-6

Returns: True if gp_Pnt is included in TopoDS_Solid, else False

static compare_direction_of_normals(normal1: gp_XYZ, normal2: gp_XYZ) → bool: Compare the direction of two surface normals (vectors). True, if direction is same or reversed :param normal1: first normal (gp_Pnt) :param normal2: second normal (gp_Pnt) :return: True/False

static fix_face(face: TopoDS_Face, tolerance=0.001) → TopoDS_Face: Apply shape healing on a face.

static fix_shape(shape: TopoDS_Shape, tolerance=0.001) → TopoDS_Shape: Apply shape healing on a shape.

static flip_orientation_of_face(face: TopoDS_Face) → TopoDS_Face: Flip the orientation of a TopoDS_Face.

static get_center_of_edge(edge): Calculates the center of the given edge. The center point is the center of mass.

static get_center_of_face(face: TopoDS_Face) → gp_Pnt: Calculates the center of the given face. The center point is the center of mass.

static get_center_of_shape(shape: TopoDS_Shape) → gp_Pnt: Calculates the center of the given shape. The center point is the center of mass.

static get_center_of_volume(volume: TopoDS_Shape) → gp_Pnt

Compute the center of mass of a TopoDS_Shape volume.

Args:: volume: TopoDS_Shape

Returns: gp_Pnt of the center of mass

static get_face_from_shape(shape: TopoDS_Shape) → TopoDS_Face: Return first face of a TopoDS_Shape.

static get_faces_from_shape(shape: TopoDS_Shape) → List[TopoDS_Face]: Return all faces from a shape.

static get_footprint_of_shape(shape: TopoDS_Shape) → TopoDS_Face: Calculate the footprint of a TopoDS_Shape.

static get_number_of_vertices(shape: TopoDS_Shape) → int: get number of vertices of a shape

static get_points_of_face(shape: TopoDS_Shape) → List[gp_Pnt]: This function returns a list of gp_Pnt of a Surface :param shape: TopoDS_Shape (Surface) :return: pnt_list (list of gp_Pnt)

static get_shape_area(shape: TopoDS_Shape) → float: compute area of a space boundary

static get_shape_volume(shape: TopoDS_Shape) → float

This function computes the volume of a shape and returns the value as a float. Args:

shape: TopoDS_Shape

Returns:: volume: float

static local_placement(plc): Get Local Placement of an IfcProducts Objectplacement

static make_faces_from_pnts(pnt_list: List[Tuple[float]] | List[gp_Pnt]) → TopoDS_Face: This function returns a TopoDS_Face from list of gp_Pnt :param pnt_list: list of gp_Pnt or Coordinate-Tuples :return: TopoDS_Face

static make_shell_from_faces(faces: list[OCC.Core.TopoDS.TopoDS_Face]) → TopoDS_Shell

Creates a TopoDS_Shell from a list of TopoDS_Face.

Args:: faces: list of TopoDS_Face

Returns: TopoDS_Shell

make_solid_from_shape(base_shape: TopoDS_Shape) → TopoDS_Solid

Make a TopoDS_Solid from a TopoDS_Shape.

Args:: base_shape: TopoDS_Shape

Returns: TopoDS_Solid

static make_solid_from_shell(shell: TopoDS_Shell) → TopoDS_Solid

Create a TopoDS_Solid from a given TopoDS_Shell.

Args:: shell: TopoDS_Shell

Returns: TopoDS_Solid

static move_bound_in_direction_of_normal(bound, move_dist: float, reverse=False) → TopoDS_Shape: Move a BIM2SIM Space Boundary in the direction of its surface normal by a given distance.

static move_bounds_to_vertical_pos(bound_list: [], base_face: TopoDS_Face) → list[OCC.Core.TopoDS.TopoDS_Shape]

static obj2_in_obj1(obj1: TopoDS_Shape, obj2: TopoDS_Shape) → bool

Checks if the center of obj2 is actually in the shape of obj1.

This method is used to compute if the center of mass of a TopoDS_Shape is included in another TopoDS_Shape. This can be used to determine, if a HVAC element (e.g., IfcSpaceHeater) is included in the TopoDS_Shape of an IfcSpace.

Args:: obj1: TopoDS_Shape of the larger element (e.g., IfcSpace) obj2: TopoDS_Shape of the smaller element (e.g., IfcSpaceHeater,

IfcAirTerminal)

Returns: True if obj2 is in obj1, else False

static remove_coincident_and_collinear_points_from_face(face: TopoDS_Face) → TopoDS_Face: removes collinear and coincident vertices iff resulting number of vertices is > 3, so a valid face can be build.

static remove_coincident_vertices(vert_list: List[gp_Pnt]) → List[gp_Pnt]: remove coincident vertices from list of gp_Pnt. Vertices are coincident if closer than tolerance.

static remove_collinear_vertices2(vert_list: List[gp_Pnt]) → List[gp_Pnt]: remove collinear vertices from list of gp_Pnt. Vertices are collinear if cross product less tolerance.

static scale_edge(edge: TopoDS_Edge, factor: float) → TopoDS_Shape: Scales the given edge by the given factor, using the center of mass of the edge as origin of the transformation.

static scale_face(face: TopoDS_Face, factor: float, predefined_center: gp_Pnt = None) → TopoDS_Shape: Scales the given face by the given factor, using the center of mass of the face as origin of the transformation. If another center than the center of mass should be used for the origin of the transformation, set the predefined_center.

static scale_shape(shape: TopoDS_Shape, factor: float, predefined_center: gp_Pnt = None) → TopoDS_Shape: Scales the given shape by the given factor, using the center of mass of the shape as origin of the transformation. If another center than the center of mass should be used for the origin of the transformation, set the predefined_center.

static sew_shapes(shape_list: list[OCC.Core.TopoDS.TopoDS_Shape]) → TopoDS_Shape

static simple_face_normal(face: TopoDS_Face, check_orientation: bool = True) → gp_XYZ: Compute the normal of a TopoDS_Face.

static triangulate_bound_shape(shape: TopoDS_Shape, cut_shapes: list[OCC.Core.TopoDS.TopoDS_Shape] = []) → TopoDS_Shape

Triangulate bound shape.

Args:: shape: TopoDS_Shape cut_shapes: list of TopoDS_Shape
Returns:: Triangulated TopoDS_Shape

bim2sim.utilities.svg_utils module

bim2sim.utilities.svg_utils.combine_svgs_complete(file_path: Path, storey_guids: list, result_str: str) → None: Add color mapping svg to floor plan svg.

bim2sim.utilities.svg_utils.combine_two_svgs(main_svg_path: Path, color_svg_path: Path, output_svg_path: Path)

Combines the content of a child SVG file into a parent SVG file.

Args:: main_svg_path (Path): Path to the parent SVG file. color_svg_path (Path): Path to the child SVG file. output_svg_path: Path to the output SVG file.
Returns:: str: Combined SVG content as a string.

bim2sim.utilities.svg_utils.convert_ifc_to_svg(ifc_file_instance: IfcFileClass, target_path: Path) → Path: Create an SVG floor plan based on the given IFC file using IfcConvert

bim2sim.utilities.svg_utils.create_svg_floor_plan_plot(ifc_file_class_inst: IfcFileClass, target_path: Path, svg_adjust_dict: dict, result_str: str)

Creates an SVG floor plan plot for every storey and adjust its design.

This function first creates an SVG floor plan for the provided IFC file based on IfcConvert, then it splits the SVG floor plan into one file per storey. In the last step the floor plans for each storey can be adjusted regarding their background color and the text. This is useful to create a heatmap that e.g. shows the highest temperature in the specific room and colorize the rooms based on the data.

Args:

svg_adjust_dict: nexted dict that holds guid of storey, spaces and the attributes for “color” and “text” to overwrite existing data in the floor plan. See example for more information ifc_file_class_inst: bim2sim IfcFileClass instance target_path: Path to store the SVG files result_str (str): name of the results plotted (used for file naming)

Example:

# create nested dict, where “2eyxpyOx95m90jmsXLOuR0” is the storey guid # and “0Lt8gR_E9ESeGH5uY_g9e9”, “17JZcMFrf5tOftUTidA0d3” and path_to_ifc_file = Path(“my_path_to_ifc_folder/AC20-FZK-Haus.ifc”) ifc_file_instance = ifcopenshell.open(path_to_ifc_file) target_path = Path(“my_target_path”)

svg_adjust_dict = {

“2eyxpyOx95m90jmsXLOuR0”: {

{“space_data”:

“0Lt8gR_E9ESeGH5uY_g9e9”: {: “color”: “#FF0000”, “text”: ‘my_text’

}, “17JZcMFrf5tOftUTidA0d3”: {

“color”: “#FF0000”, “text”: ‘my_text2’

}, “2RSCzLOBz4FAK$_wE8VckM”: {

“color”: “#FF0000”, “text”: ‘my_text3’

},

}

} create_svg_floor_plan_plot(

path_to_ifc_file, target_path, svg_adjust_dict)

bim2sim.utilities.svg_utils.modify_svg_elements(svg_adjust_dict: dict, path: Path)

Adjusts SVG floor plan for based on input data.

Based on the inputs, you can colorize the different spaces in the SVG and/or add text to the space for each storey. The input is a nested dictionary that holds the relevant data.

Args:: svg_adjust_dict: nexted dict that holds guid of storey, spaces and the attributes for “color” and “text” to overwrite existing data in the floor plan. path: Path where the basic SVG files are stored.

bim2sim.utilities.svg_utils.split_svg_by_storeys(svg: Path): Splits the SVG of one building into single SVGs for each storey.

bim2sim.utilities.test module

class bim2sim.utilities.test.IntegrationBase

Bases: object

Base class mixin for Integration tests

create_project(ifc_names: dict, plugin: str) → Project

create project in temporary directory which is cleaned automatically

after test.

Args:

ifc_names: dict with key: IFCDomain and value: name of ifc located: in directory test/resources/hydraulic/ifc

plugin: e.g. ‘hkesim’, ‘aixlib’, …

Returns:

project: bim2sim project

model_domain_path() → str | None

setUp() → None

tearDown()

static test_resources_path() → Path

weather_file_path() → Path

class bim2sim.utilities.test.RegressionTestBase

Bases: IntegrationBase

Base class for regression tests.

create_regression_setup(tolerance)

model_domain_path() → str

run_regression_test()

setUp()

bim2sim.utilities.types module

class bim2sim.utilities.types.AttributeDataSource(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumerator for data_source of attributes.

This Enumerator defines various sources from which attribute data can be derived. It categorizes the origin of attributes used in a given context, allowing for standardized reference and handling of these data sources in the application.

Following enumerations exist:

ifc_attr: Represents real IFC attributes derived directly from the IFC: objects attributes.

default_ps: Indicates attributes sourced from default property sets. default_association: Attributes obtained from default associations. finder: Attributes found through the finder searching mechanism. patterns: Attributes identified through pattern recognition. function: Attributes determined through functions of the attribute

evaluation or calculations.

default: Represents the default attribute source when no specific source is defined. decision: Attributes derived from answered decisions. manual_overwrite: Attributes that were manually overwritten during the process without the definition of a specific data source. enrichment: Attributes enriched or supplemented with additional information. space_boundary: Attributes derived from space boundary definitions.

decision = 8

default = 7

default_association = 3

default_ps = 2

enrichment = 10

finder = 4

function = 6

ifc_attr = 1

manual_overwrite = 9

patterns = 5

space_boundary = 11

class bim2sim.utilities.types.IFCDomain(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration for ifc file domains.

arch = 1

hydraulic = 3

mixed = 5

sanitary = 4

unknown = 6

ventilation = 2

class bim2sim.utilities.types.LOD(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Level of detail in form of an enumeration. The different meaning depends on the specific simulation settings.

full = 3

ignore = 0

low = 1

medium = 2

class bim2sim.utilities.types.ZoningCriteria(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

all_criteria = 5

external = 1

external_orientation = 3

external_orientation_usage = 4

usage = 2

bim2sim.utilities.visualize_spaces module

Thermal Zone Visualization Module

This module provides functionality to visualize thermal zones and save the output as an image. It includes functions to convert RGB values to OCC-compatible colors and to generate visualizations of thermal zones grouped by various criteria.

Example:: For an example, please see e4_visualize_zone_binding.py in PluginTEASER.
Functions:: rgb_color(rgb): Returns an OCC viewer compatible color quantity based on r,g,b values. visualize_zones(zone_dict, folder_structure): Visualizes the thermal zones and saves the picture as a .png.
Notes:: Any additional information about the module, its purpose, and its usage can be included here.

bim2sim.utilities.visualize_spaces.rgb_color(rgb) → Quantity_Color

Returns a OCC viewer compatible color quantity based on r,g,b values.

Args:: rgb: must be a tuple with 3 values [0,1]. e.g. (0, 0.5, 0.7)
Returns:: Quantity_Color object which is compatible with with the OCC viewer.

bim2sim.utilities.visualize_spaces.visualize_zones(thermal_zones: list[bim2sim.elements.bps_elements.ThermalZone], path: Path, filename: str | None = None)

Visualizes the ThermalZone element entities and saves the picture as a .png. Fetches the ThermalZone which are grouped before and creates an abstract building image, where each grouped zone has its own color. Afterwards, a legend is added with zone names and corresponding colors. The file is exported as .png to the export folder.

Args:: thermal_zones: list of ThermalZone and AggregatedThermalZone instances path: pathlib Path where image is exported to filename: str of filename
Returns:: No return value, image is saved directly.