diff --git a/src/ifcopenshell-python/ifcopenshell/api/drawing/assign_product.py b/src/ifcopenshell-python/ifcopenshell/api/drawing/assign_product.py index b41ce3865b..9ab5e89e9e 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/drawing/assign_product.py +++ b/src/ifcopenshell-python/ifcopenshell/api/drawing/assign_product.py @@ -21,14 +21,46 @@ import ifcopenshell.api class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, relating_product=None, related_object=None): + """Associates a product and an object, typically for annotation + + Warning: this is an experimental API. + + When you want to draw attention to a feature or characteristic (such as + a dimension, material, or name) or of a product (e.g. wall, slab, + furniture, etc), an annotation object is created. This annotation is + then associated with the product so that it can reference attributes, + properties, and relationships. + + For example, an annotation of a line will be associated with a grid + axis, such that when that grid axis moves, the annotation of that grid + axis (which is typically truncated to the extents of a drawing) will + also move. + + Another example might be a label of a furniture product, which might + have some text of the name of the furniture to be shown on drawings or + in 3D. + + :param relating_product: The IfcProduct the object is related to + :type relating_product: ifcopenshell.entity_instance.entity_instance + :param related_object: The object (typically IfcAnnotation) that the + product is related to + :type related_object: ifcopenshell.entity_instance.entity_instance + :return: The created IfcRelAssignsToProduct relationship + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + furniture = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcFurniture") + annotation = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcAnnotation") + ifcopenshell.api.run("drawing.assign_product", model, + relating_product=furniture, related_object=annotation) + """ self.file = file self.settings = { - "relating_product": None, - "related_object": None, + "relating_product": relating_product, + "related_object": related_object, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): is_grid_axis = self.settings["relating_product"].is_a("IfcGridAxis") diff --git a/src/ifcopenshell-python/ifcopenshell/api/drawing/edit_text_literal.py b/src/ifcopenshell-python/ifcopenshell/api/drawing/edit_text_literal.py index 411da1ecf1..e9c34e7da8 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/drawing/edit_text_literal.py +++ b/src/ifcopenshell-python/ifcopenshell/api/drawing/edit_text_literal.py @@ -18,11 +18,27 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, text_literal=None, attributes=None): + """Edits the attributes of an IfcTextLiteral + + For more information about the attributes and data types of an + IfcTextLiteral, consult the IFC documentation. + + :param reference: The IfcTextLiteral entity you want to edit + :type reference: ifcopenshell.entity_instance.entity_instance + :param attributes: a dictionary of attribute names and values. + :type attributes: dict, optional + :return: None + :rtype: None + + Example:: + + text = model.createIfcTextLiteral() + ifcopenshell.api.run("drawing.edit_text_literal", model, + text_literal=text, attributes={"Literal": "MY ANNOTATION"}) + """ self.file = file - self.settings = {"text_literal": None, "attributes": {}} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"text_literal": text_literal, "attributes": attributes or {}} def execute(self): for name, value in self.settings["attributes"].items(): diff --git a/src/ifcopenshell-python/ifcopenshell/api/drawing/unassign_product.py b/src/ifcopenshell-python/ifcopenshell/api/drawing/unassign_product.py index c963c5a99c..7dd1da8a34 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/drawing/unassign_product.py +++ b/src/ifcopenshell-python/ifcopenshell/api/drawing/unassign_product.py @@ -21,14 +21,38 @@ import ifcopenshell.api class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, relating_product=None, related_object=None): + """Unassigns a product and an object (typically an annotation) + + Smart annotation objects can be associated with products so that they + can annotate attributes and properties. This function lets you remove + the association, so that you may change the assocation with another + object later or leave the annotation as a "dumb" annotation. + + :param relating_product: The IfcProduct the object is related to + :type relating_product: ifcopenshell.entity_instance.entity_instance + :param related_object: The object (typically IfcAnnotation) that the + product is related to + :type related_object: ifcopenshell.entity_instance.entity_instance + :return: The created IfcRelAssignsToProduct relationship + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + furniture = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcFurniture") + annotation = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcAnnotation") + ifcopenshell.api.run("drawing.assign_product", model, + relating_product=furniture, related_object=annotation) + + # Let's change our mind and remove the relationship + ifcopenshell.api.run("drawing.unassign_product", model, + relating_product=furniture, related_object=annotation) + """ self.file = file self.settings = { - "relating_product": None, - "related_object": None, + "relating_product": relating_product, + "related_object": related_object, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): for rel in self.settings["related_object"].HasAssignments or []: