Skip to content

PythonPart

A PythonPart as an element in the DF can be understood as a container, encapsulating AllplanElements such as:

The key feature of a PythonPart is that it can be modified parametrically.

PythonPart has properties as any other Allplan element, like Common properties or Attributes. In addition, you can introduce a hierarchy to organize your elements inside the PythonPart.

Data structure

Info

In this paragraph we will explain the background of a PythonPart. This knowledge might be helpful to, but is not required to work with PythonParts. If you want, you can jump directly to this paragraph to learn how to create a PythonPart.

The data structure behind a PythonPart is similar to the one behind a smart object (aka macro), which means it is composed of following objects:

  • The PythonPart placement (represented by the MacroPlacementElement class):

    • Places exactly one definition
    • Places means transforms the definition from its local into the global coordinate system using placement matrix

  • The PythonPart definition (represented by the MacroElement class):

    • has one or more views (aka slides or foils) with different LOD
    • is being placed in the model by one or more placements

  • The Views (represented by View class):

    • encapsulates one or more model elements (3d objects, 2d lines, circles, etc...)
    • belongs to exactly one definition

The diagram below shows the relationships described above:

erDiagram
PyP-PLACEMENT }|--|| PyP-DEFINITION: places
PyP-DEFINITION ||--|{ PyP-VIEW  : has
PyP-VIEW ||--|{ MODEL-ELEMENT-3D : encapsulates
PyP-VIEW ||--|{ MODEL-ELEMENT-2D : encapsulates

PyP-PLACEMENT ["PythonPart placement"] {
    str Name
    Matrix3D PlacementMatrix
    Attributes Attributes
    CommonProperties CommonProperties
}

PyP-DEFINITION["PythonPart definition"] {
    str Name
    str Hash 
}

PyP-VIEW["View"] {
    bool visibility2d
    bool visibility3d
    float start_scale
    float end_scale
}

MODEL-ELEMENT-3D["Model element 3D"] {
    Any Geometry
    CommonProperties CommonProperties
}

MODEL-ELEMENT-2D["Model element 2D"] {
    Any Geometry
    CommonProperties CommonProperties
}

Note

Note that the 2D and 3D elements technically have attributes, but because they are encapsulated inside the PythonPart view, these attributes cannot be accessed by Allplan reports and legends. Hence, relevant are only the attributes of the _placement_1

Create PythonPart

The easiest way to create a PythonPart is to use the PythonPartUtil class. It will take care of tasks necessary for a PythonPart, such as:

Example

Let's assume, that the variable cube is a ModelElement3D representing a cube. Here is, how we create a very simple PythonPart:

from PythonPartUtil import PythonPartUtil
...
python_part_util = PythonPartUtil(common_prop) #(1)!
python_part_util.add_pythonpart_view_2d3d(cube) #(2)!
python_part = python_part_util.create_pythonpart(build_ele) #(3)!
  1. At this stage we can control the Common properties of the PythonPart placement. This argument is optional. If not provided, currently common properties settings will be applied
  2. This will add the cube to a view, that is displayed in all scales and in both ground and isometric view. We could also provide a ModelEleList

  3. The BuildingElement object containing all the parameters and their values is necessary for the creation of the PythonPart. This ensures, that e.g.

The python_part is now a list containing both the placement and the definition. You can pass this list directly to the CreateElementResult class, like:

CreateElementResult(elements = python_part)

Views

PythonPart view visibility

A PythonPart is capable of having multiple views (aka foils or slides). Each of these slides can contain different geometry and can be shown/hidden based on:

  • the art of the view: ground view or isometric view
  • currently set scale: a more detailed representation can be shown in lower scale

A typical use-case for it is to display the PythonPart in a more detailed way in lower scales (e.g. 1:10) and in a more simplified ways in higher scales (e.g. 1:100).

These settings are stored in a PythonPartViewData object. Apply them on a view by passing the object as an optional argument to the add_pythonpart_view method.

Example

To display your PythonPart as a:

  • sphere, when the scale ranges from 1:1 to 1:50
  • cube, when the scale ranges from 1:50 to 1:9999

Create the utility as usual:

from PythonPartUtil import PythonPartUtil
...
python_part_util = PythonPartUtil()

And append the two views to the PythonPart using the utility. First one for the scale ranging from 1:1 to 1:50:

sphere_view_data = PythonPartViewData()

sphere_view_data.start_scale = 0
sphere_view_data.end_scale   = 50 #(1)!

python_part_util.add_pythonpart_view_2d3d(elements  = sphere_model_ele, #(3)!
                                          view_data = sphere_view_data) #(2)!
  1. With this setting, the view will be displayed, when the set scale is lower than or equal to 50!
  2. Here is, where we apply the view settings. this argument is optional and if not provided, the default settings defines in PythonPartViewData will be used
  3. The sphere_model_ele is the model element list containing the sphere

Now the second one with the cube, for tha scale ranging from 1:50 to 1:9999:

cube_view_data = PythonPartViewData()

cube_view_data.start_scale = 50
cube_view_data.end_scale   = 9999

python_part_util.add_pythonpart_view_2d3d(elements  = cube_model_ele, #(1)!
                                          view_data = cube_view_data)
  1. The cube_model_ele is the model element list containing the cube

Finally, create the PythonPart:

python_part = python_part_util.create_pythonpart(build_ele)

The visibility of the views can also be determined by the art of the view. Sometimes it is useful to display the PythonPart in the ground view with simplified 2D view consisting of lines, and use complex 3D solids only in the isometric view.

To achieve this, use the appropriate method of the PythonPartUtil to create the view:

Function to use Behavior
add_pythonpart_view_2d the view is visible in the ground view only
add_pythonpart_view_3d the view is visible in the isometric view only
add_pythonpart_view_2d3d the view is always visible

Note

Note, that the usage of the above mentioned methods makes it irrelevant, what is set in the properties visible_in_2d or visible_in_3d of the PythonPartViewData.

Failure

The following settings of the PythonPartViewData have at the moment no influence on the visibility behavior of the created PythonPart:

Example on GitHub

The functionalities mentioned above are shown in the example ViewSettings ( PYP | PY).

Attributes

Here's how you can save a value calculated inside the script (width) in a PythonPart's attribute (let's use the attribute @221@). First, construct a BuildingElementAttributeList

attribute_list = BuildingElementAttributeList()

Append the attribute @221@ together with the value to the list. Feel free to append as many attributes as you need:

attribute_list.add_attribute(221, width)

Assign the attributes on the PythonPart using the add_attribute_list method of the utility.

pyp_util.add_attribute_list(attribute_list)

Example on GitHub

Have a look at the example PythonPartWithAttributes ( PYP | PY). When the check box Append geometry attributes is checked, the geometrical parameters (length, width, height) are appended to the PythonPart as attributes.

Tip

When creating a PythonPart using PythonPartUtil, all the parameters with an attribute defined in the .pyp file are automatically appended to the PythonPart as attributes. You don't need to append them extra.

PythonPart attribute modification

If you use a parameter with an attribute for the geometry calculation and set the tag <AttributeEvent> to True (learn more about the modification event tags below ) you will achieve following behavior: modifying the attribute linked to this parameter with native ALLPLAN function will directly change the geometry of the PythonPart.

What happens under the hood is:

  • the attribute modification triggers the execution of the PythonPart script
  • before the execution, the values of all attributes linked with a parameter are read and their values are overtaken
  • the script is executed with new parameter values, which affects the geometry

Example on GitHub

Have a look at the example PythonPartWithAttributes ( PYP | PY).

The parameter layer thickness is linked to an attribute with the same name. Place the PythonPart in the model and modify the value of this attribute by right click -> Modify attributes. The thickness of the bottom part of the PythonPart directly after the attribute change.

Placement

To control, how the PythonPart is placed in the model, the method create_pythonpart offers two optional arguments:

  • placement_matrix
  • local_placement_matrix

These arguments require a Matrix3D describing rotation and/or translation (see this article to learn how to construct it) to place the whole PythonPart container in the desired position and orientation in the model.

pyp_util = PythonPartUtil()
...
python_part = pyp_util.create_pythonpart(build_ele, 
                                         placement_matrix = placement_mat)

Info

You can construct one matrix and pass it to one of the arguments (as shown above) or two matrices (e.g. one with rotation and second one with translation) and pass them to both arguments separately. Keep following in mind:

  • order: the transformation described in placement_matrix is applied at first, followed by the local_placement_matrix

  • the local_placement_matrix is saved in the attribute @1035@, placement_matrix is not saved in any attribute

Tip

Use this feature to rotate or move the entire PythonPart container rather than rotating/moving the individual elements inside the container. This will ensure the right behavior of the created PythonPart.

Example on GitHub

A typical use-case for this feature is, when you want to give the user control over the orientation of the PythonPart, when placing it. In this case, you rotate the whole PythonPart. It is shown in the example IdenticalRotatedPlate ( PYP | PY), where the user can rotate the PythonPart around all three XYZ axes.

Hierarchy

Your PythonPart can be complex and consist of many individual elements. If you want these elements to have their own attributes and enable the user to perform a quantity take-off on them (e.g. with Allplan reports or legends), you need to introduce a hierarchy.

There are three ways, how you can do it. As usual, there is no one perfect solution for all problems. Choose the one that best suits you. Here is the overview:

Structured PythonPart is a PythonPart with multiple so called element nodes - entities with geometrical representation and attributes, which can be organized in a multi-level hierarchy.

Pros

  • Complex hierarchy possible: PythonPart is the parent, element nodes are children which can have another element nodes as children.
  • Each element node can have its own attributes and is evaluable with Allplan reports and legends.
  • The user can manually add attributes to the element nodes using Allplan UI.
  • Element nodes preserve the attributes manually added to them when reactivating the PythonPart.
  • The hierarchy structure can vary depending on the scale (possible to introduce multiple LODs).

Cons

  • Work-in-progress feature - some workflows or features may not work as expected.
  • Incorrect representation in the IFC: all the elements in the container are represented with one IFC entity.
  • Cannot be unlinked to individual elements - the result will always be a single smart symbol.
  • Element nodes encapsulate the elements inside them the same way a smart symbol does.
  • Element nodes must have a geometrical representation.

Learn more below

PythonPart can have elements of certain type (e.g. reinforcement) linked to it as child elements.

Pros

  • Child elements are not encapsulated - manual changes to them are possible using Allplan UI
  • Simple hierarchy: PythonPart is the parent, connected elements are the children.

Cons

  • No representation of the hierarchy in IFC - PythonPart and its children are individual IFC entities.
  • Any manual changes done to the child elements are lost after reactivating the PythonPart.
  • Possible to link only certain element types.

Learn more below

PythonPart group is a simple container with multiple PythonParts.

Pros

  • Can be unlinked to individual PythonParts.
  • After unlinking, individual PythonParts behave like if they were placed individually.
  • Correct representation in the IFC: group is an IfcAssembly.
  • Simple hierarchy: group is the parent, PythonParts are the children.

Cons

  • Each member must be a fully functional PythonPart - has a script and a PYP file
  • Only flat hierarchy possible: PythonParts cannot have other Pythonparts as children.
  • Reactivating the group leads to lost of manual changes done to individual PythonParts (e.g. loosing manually added attributes).
  • Group cannot have any geometrical representation.
  • Not possible to append attributes to the group, only to the individual PythonParts.

Learn more below

Structured PythonPart

You can introduce a hierarchy into a PythonPart container. This means, that each view of the PythonPart can have multiple children. The hierarchy can have unlimited number of levels: the children can also have children, which also can have children, and so on...

The entities inside the hierarchy are referred to as element nodes. Their representation in Python API is the ElementNodeElement class. Each element node:

  • has a UUID, which needs to be:

    • unique within the hierarchy (1)

      1. Creating two elements with the same UUID will result in these two elements be considered as one logical object in ALLPLAN - they will be selected together, have the same attributes, etc...

    • generated deterministically

  • has one parent element, which can be:

    • the PythonPart itself (by default) OR
    • another element node - must be set using the SetParentID() method

  • can have it's own list of model element, common properties and attributes

The following diagram shows the relationships between entities inside a structured PythonPart:

erDiagram
PyP-PLACEMENT one or more to one PyP-DEFINITION: places
PyP-DEFINITION one to one or more PyP-VIEW  : has
PyP-VIEW one to one or more Sub-ELEMENT : has
Sub-ELEMENT one to one or more Sub-ELEMENT : has
Sub-ELEMENT one to zero or more MODEL-ELEMENT-3D : encapsulates
Sub-ELEMENT one to zero or more MODEL-ELEMENT-2D : encapsulates

PyP-PLACEMENT ["PythonPart placement"] {
    str Name
    Matrix3D PlacementMatrix
    Attributes Attributes
    CommonProperties CommonProperties
}

PyP-DEFINITION["PythonPart definition"] {
    str Name
    str Hash 
}

Sub-ELEMENT["Element node"] {
    uuid uuid
    Attributes Attributes
    CommonProperties CommonProperties
}

PyP-VIEW["View"] {
    bool visibility2d
    bool visibility3d
    float start_scale
    float end_scale
}

MODEL-ELEMENT-3D["Model element 3D"] {
    Any Geometry
    CommonProperties CommonProperties
}

MODEL-ELEMENT-2D["Model element 2D"] {
    Any Geometry
    CommonProperties CommonProperties
}

Abstract

Key takeaways from the above diagram:

  1. The element nodes are assigned to the PythonPart view, which means that the hierarchy can be dynamic and vary depending on the current scale.
  2. An element node can have another node element as child. This allows you to create unlimited number of hierarchy levels.

Info

The UUID of each element node needs to be generated deterministically i.e. it must remain the same each time the PythonPart script is executed. This ensures the attributes manually assigned to the element node (i.e. by the user using native Allplan function) are preserved with each script execution. Even if the number of the element nodes and their position in the hierarchy is dynamic.

Flat hierarchy

Let's create a simple structured PythonPart with a flat hierarchy, where the PythonPart itself is the parent element and contains two child elements:

flowchart TB

PyP["PythonPart"] --> El1["Box 1"]
PyP --> El2["Box 2"]

  1. Generate a UUID for both of them. You can use the UUID version 5 and the OID namespace, to generate the UUID based on a string, e.g. 'Box_1', like:

    import uuid
...
box_1_uuid = uuid.uuid5(uuid.NAMESPACE_OID, f'Box_1')
box_2_uuid = uuid.uuid5(uuid.NAMESPACE_OID, f'Box_2') #(1)!
    1. If in your PythonPart the number of the element nodes is dynamic and the user removes or adds new elements, the same elements should become the same string (hence, the same UUID). In this way, their attributes gets preserved despite the changes in the hierarchy structure.

  2. Create ElementNodeElements, one for each box:

    common_prop = AllplanBaseElements.CommonProperties()
node_elements = [AllplanBasisElements.ElementNodeElement(common_prop, box_1_uuid, [box_1]),
                 AllplanBasisElements.ElementNodeElement(common_prop, box_2_uuid, [box_2])]

  3. Add elements to PythonPart view. Construct PythonPartUtil in a similar way to the one for a regular PythonPart but with one difference:

    from PythonPartUtil import PythonPartUtil
...
pyp_util = PythonPartUtil()
pyp_util.add_pythonpart_view_2d3d(node_elements) #(1)!
    1. Don't add the box_1 and box_2 to the PythonPart view. Instead, add the element nodes, as they already contain the boxes.

  4. Optionally append the attributes. If you want to append the attributes to the whole PythonPart, follow the procedure described above. However, you can assign attributes to each box individually. Prepare an attribute list for each and append to the PythonPart using the method add_attribute_list_to_sub_element_in_structured_container(), like this:

    box_1_attributes = BuildingElementAttributeList()
box_1_attributes.add_attribute(507, f"Box_1")

pyp_util.add_attribute_list_to_sub_element_in_structured_container(box_1_attributes, box_1_uuid)

  5. Create the PythonPart in the same way, as if it was a regular, unstructured PythonPart:

    python_part = pyp_util.create_pythonpart(build_ele)

Nested hierarchy

It is possible to create a nested hierarchy, where an element node has other element node as child. Let's make the second box to be the child of the first box, like shown below.

flowchart TB

PyP["PythonPart"] --> El1["Box 1"]
El1 --> El2["Box 2"]

To achieve that, introduce an additional step between the steps 2 and 3. Declare the Box_1 to a parent element of the Box_2 by pointing to its UUID. Use the SetParentID method, like this:

node_elements[1].SetParentID(box_1_uuid)

Example on GitHub

The full implementation is shown in the example StructuredPythonPart ( PYP | PY). After you place the PythonPart in Allplan model, explore the parent-child relationships:

  1. Download this Report Template
  2. Run the Allplan function Reports and generate a report using the downloaded template
  3. In the report, you should see the children of the PythonPart and parent and children of each of the element node

Child elements

A PythonPart can be linked with other elements with a parent-child relationship (PythonPart being the parent). The elements are linked to the placement, which means that each placement can have different elements linked to it.

erDiagram
PyP-PLACEMENT |o..o{ FIXTURE : links
PyP-PLACEMENT }|--|| PyP-DEFINITION: places
PyP-DEFINITION ||--|{ PyP-VIEW  : has
PyP-VIEW ||--|{ MODEL-ELEMENT-3D : encapsulates
PyP-VIEW ||--|{ MODEL-ELEMENT-2D : encapsulates
PyP-PLACEMENT |o..o{ REINFORCEMENT : links
PyP-PLACEMENT |o..o{ LIBRARY-ELEMENT : links

PyP-PLACEMENT ["PythonPart placement"] {
    str Name
    Matrix3D PlacementMatrix
    Attributes Attributes
    CommonProperties CommonProperties
}

PyP-DEFINITION["PythonPart definition"] {
    str Name
    str Hash 
}

PyP-VIEW["View"] {
    bool visibility2d
    bool visibility3d
    float start_scale
    float end_scale
}

MODEL-ELEMENT-3D["Model element 3D"] {
    Any Geometry
    CommonProperties CommonProperties
}

MODEL-ELEMENT-2D["Model element 2D"] {
    Any Geometry
    CommonProperties CommonProperties
}

FIXTURE["Fixture"]
REINFORCEMENT["Reinforcement"]
LIBRARY-ELEMENT["Library element"]

A typical use-case for this kind of relationship is a PythonPart with reinforcement. The reinforcement elements are not encapsulated in the PythonPart, but linked to it. This makes the generation of bending schedules and schemas possible.

The table below shows an overview of all the elements, that can be connected like this, and the function that is to be used.

Child element Function to use
Architecture component add_architecture_elements()
Reinforcement add_reinforcement_elements()
Library element add_library_elements()
Fixtures add_fixture_elements()

Warning

Avoid including these elements directly into the PythonPart views. Although it is possible, it may lead to unexpected behavior of the PythonPart.

Bear in mind, that linked elements can be freely modified, moved or deleted by the user with Allplan native functions. But as soon as the PythonPart gets reactivated, these changes are lost.

Example on GitHub

The functionality mentioned above is shown in the example PythonPartWithSubObjects ( PYP | PY). To create a child element, check the corresponding checkbox and place the PythonPart in the model. Check the behavior, when moving the PythonPart and the sub object. Check the relationships in the Allplan Object manager.

PythonPart group

PythonPart group

Multiple PythonPart placements can be grouped together into a PythonPart group. The user interaction with a group is the same as with a regular PythonPart, but the individual group members are created as separate elements and can therefore be evaluated by Allplan reports or legends and labeled individually. This allows you to create assemblies, that are seen by the user as one, but by Allplan as many elements. A typical use-case are set-like components, that must be invoiced individually (e.g. screw, nut and washer).

erDiagram
PyP-GROUP ||--|{ PyP-PLACEMENT: has
PyP-PLACEMENT }|--|| PyP-DEFINITION: places
PyP-DEFINITION ||--|{ PyP-VIEW  : has
PyP-VIEW ||--|{ MODEL-ELEMENT-3D : encapsulates
PyP-VIEW ||--|{ MODEL-ELEMENT-2D : encapsulates

PyP-GROUP["PythonPart group"] {
    str Name
}

PyP-PLACEMENT ["PythonPart placement"] {
    str Name
    Matrix3D PlacementMatrix
    Attributes Attributes
    CommonProperties CommonProperties
}

PyP-DEFINITION["PythonPart definition"] {
    str Name
    str Hash 
}

PyP-VIEW["View"] {
    bool visibility2d
    bool visibility3d
    float start_scale
    float end_scale
}

MODEL-ELEMENT-3D["Model element 3D"] {
    Any Geometry
    CommonProperties CommonProperties
}

MODEL-ELEMENT-2D["Model element 2D"] {
    Any Geometry
    CommonProperties CommonProperties
}

Abstract

Key takeaways from the above diagram:

  1. Flat hierarchy: the individual PythonParts inside a group are all children of the PythonPart group
  2. The group itself have neither a geometrical representation nor attributes.

Info

In the following code snippets we will be using the script object contract in the script for the group as well as for individual PythonParts. Implementation as standard PythonPart or an interactor is possible as well.

To create a PythonPart group, follow these steps:

  1. Create the members as PythonParts. I.e., create a PYP file (further referred to as sub-PYP) and a script (python module, further referred to as sub-script). Create them as fully functional modifiable PythonParts, as described above .

  2. Make sure, the script object in your sub-script has a method that creates a PythonPart object. In this example, it's create_pythonpart(). You will need it later in the script for the group. If you are using PythonPartUtil, you can use the get_pythonpart() method, like:

    sub-script
    class YourSubPythonPart(BaseScriptObject):
    ...
    def create_pythonpart(self) -> PythonPart:
        python_part_util = PythonPartUtil(...)
        ...  #(1)!
        return python_part_util.get_pythonpart(self.build_ele)

    def execute(self) -> CreateElementResult:
        python_part = self.create_pythonpart()  #(2)!
        return CreateElementResult(python_part.create())
    1. Define the views, attributes and other stuff here.
    2. To create individual PythonPart, call create().

  3. Create the PYP file and python script for the group. We will further refer to them as group-PYP and group script. The parameters of the group and the individual members are saved in separate BuildingElement objects(1). In this example, these are build_ele and sub_build_ele respectively.

    1. In a typical use-case, a parameter of the group will influence the parameters of the individual members. For example, in a screw-nut-washer set, all the individual components have a diameter. When placing them as individually, you can set a different diameter for each component. In a group, you would set one diameter for all three components: screw, nut and washer.

  4. In the group script create the BuildingElement with parameter values from sub-PYP. If your sub PythonParts are script objects, use PythonPartScriptObjectUtil (1).

    1. If your sub PythonParts are standard PythonParts or interactors, you can use the BuildingElementService.read_build_ele_from_pyp()

      group script
      _, file_name = FileNameService.get_pyp_path_from_lib_struct(r"Library\Path\To\YourSubPythonPart.pyp")

result, sub_script, sub_build_ele = BuildingElementService.read_build_ele_from_pyp(file_name)
    group script
    script_obj_util = PythonPartScriptObjectUtil(self.coord_input, r"Library\Path\To\YourSubPythonPart.pyp")
sub_build_ele   = script_obj_util.build_ele_list[0] #(1)!

    1. The sub_build_ele will contain parameters of the individual PythonParts with their default values (as defined in the sub-PYP). You can alter these values, e.g. based on the parameter values from the group-PYP (saved in build_ele) like this:

      sub_build_ele.FooParameter.value = build_ele.BarParameter.value

  5. Create an instance of your sub script object class. Use create_script_object() method of the utility, like:

    group script
    sub_script_obj = script_obj_util.create_script_object()

  6. Create an empty PythonPartGroup using the from_build_ele() method.

    group script
    pythonpart_group = PythonPartGroup.from_build_ele(build_ele) #(1)!
pythonpart_group.append(pythonpart)

return CreateElementResult(pythonpart_group.create())
    1. The build_ele is the BuildingElement representing the group PYP. The one, that is given to you by the framework in the create_script_object() function in the group script.

  7. Populate the group with the individual PythonPart objects, created with create_pythonpart() method from step 2.

    Tip

    Note, that the user can modify the attributes of the individual PythonParts in the group with native ALLPLAN function, after he created the group. He can also label individual group members. To ensure, that these attributes or labels don't get lost after modifying the group, you need to:

    1. Assign each of the PythonPart in the group a key (string), unique within the group. Save it in the property sub_pythonpart_key
    2. Call PythonPartAttributeTakeoverService.check_external_sub_pyp_attribute_modification().
    group script
    for i in range(...):
    pythonpart = sub_script_obj.create_pythonpart() #(1)!
    pythonpart.placement_matrix   = AllplanGeo.Matrix3D(...) #(2)!
    pythonpart.sub_pythonpart_key =  f"Box {i + 1}" #(3)!

    PythonPartAttributeTakeoverService.check_external_sub_pyp_attribute_modification(
        [sub_build_ele], pythonpart.sub_pythonpart_key) #(4)!

    pythonpart_group.append(pythonpart)
    1. This is the function creating PythonPart from step 2
    2. To arrange individual PythonPars in the group, prepare a transformation matrix, that transforms from local coordinate system of individual PythonPart to the local coordinate system of the group.
    3. Assign a key to each PythonPart. When the number of elements in your group is dynamic, make sure that when changing the number of elements, the same elements become the same key.
    4. This call checks, whether any attributes of the individual PythonParts in the group were added/modified using native ALLPLAN function (outside the PythonPart logic) and makes sure, these changes are not lost when the group is modified.

  8. Create the group using the create() method. This gives you a model element list, which you can save in the CreateElementResult data class.

    group script
    return CreateElementResult(pythonpart_group.create())

Tip

A PythonPart group created like this can be broken down into individual PythonParts with ALLPLAN function unlink smart symbol. Afterwards, the PythonParts can be modified with double-click as if they were placed individually.

Example on GitHub

The entire implementation is shown in the example PythonPartGroup ( PYP | PY), that uses the PythonPartWithAttributes ( PYP | PY) as a subordinate PythonPart.

Display name

PythonPart display name

A PythonPart element can represent any component: from a screw to an abutment. To enable the user to easily distinguish between different types of PythonParts inside the viewport you can assign a customized display name to your PythonPart.

PythonPart display name in object manager

This customized name will be then displayed to the user, when he hovers the mouse over the PythonPart inside a viewport (as shown on the image above) which improves the UX during the element selection. Furthermore, the user will be able to group the PythonParts by this name inside the object manager, when he chooses the Type criterion (as shown on the image to the left).

To achieve this, provide the display name, when calling the create_pythonpart method:

elements = pyp_util.create_pythonpart(
    build_ele,
    type_uuid = "c0398407-1d54-4087-a8da-7d6aaffb25ec", #(1)!
    type_display_name = "PythonPart Plate"
    )
  1. Beside the display name, you can provide a UUID for the element type, your PythonPart represents. It will override the PythonPart_TypeUUID in the created element. This will allow you to set-up a filter for selecting only your type of PythonPart, which can be very useful when building a script for modification.

Info

The same functionality is available also for PythonPart groups inside the constructor of the PythonPartGroup class.

Creation vs. modification mode

A PythonPart can be run in creation mode (when e.g. started from ALLPLAN Library) or in a modification mode (when reactivated per double-click on an existing PythonPart element). Sometimes, you want your PythonPart to behave differently in both situations

To check, whether a standard PythonPart was started in modification mode, use the DocumentManager. It is a singleton, that stores the information about the modified PythonPart element. If there is no PythonPart element, the script is run in creation mode:

from DocumentManager import DocumentManager
...
if DocumentManager.get_instance().pythonpart_element.IsNull():
    ### introduce actions for creation mode here
else:
    ### introduce actions for modification mode here

The information, whether a script object is run in modification or creation mode, is passed by the framework to the script object class constructor in the BaseScriptObjectData class. Extend the constructor method from the base class BaseScriptObject and you will have access to the property is_modification_mode:

class YourScriptObject(BaseScriptObject):

    def __init__(self,
                 build_ele         : BuildingElement,
                 script_object_data: BaseScriptObjectData):

        super().__init__(script_object_data) #(1)!

    def foo(self, ...):
        if self.is_modification_mode:
            ### introduce actions for modification mode here
        else:
            ### introduce actions for creation mode here
  1. Extend the constructor of the base class!

In an interactor, whether the script is run in creation or modification mode, can be determined based on the list with UUIDs of the modified elements. Empty list = creation mode. The list is passed by the framework to the constructor of the interactor class. You can get it from the property modification_element_list, like:

def create_interactor(interactor_data: BaseInteractorData) -> YourInteractor:
    return YourInteractor(interactor_data)
...
class YourInteractor(BaseInteractor):

    def __init__(self, interactor_data: BaseInteractorData):
        self.is_modification = interactor_data.modification_element_list.is_modification_element() #(1)!

    def foo(self, ...):
        if self.is_modification:
            ### introduce actions for modification mode here
        else:
            ### introduce actions for creation mode here
  1. The modification_element_list is of type ModificationElementList, which is a list of UUIDs of modified elements. It's empty in creation mode. Use the dedicated method is_modification_element() to check, whether it is the case.

Tip

If you want to hide/disable some controls in the property palette for the modification mode, you can implement it directly in the PYP file e.g., like:

<Visible>__is_input_mode()</Visible>

Learn more in this article.

Modification events

If you want your PythonPart element to update (recalculate) after the user has performed a modification with a native ALLPLAN function (e.g., moved the PythonPart or changed its attributes), add an event tag to the <Script> section of the PYP-file, e.g. like:

<Element>
    <Script>
        <Name>Path\To\YourPythonPart.py</Name>
        <Title>The title</Title>
        <Version>1.2</Version>
        <MoveEvent>True</MoveEvent>
    </Script>

This results in the PythonPart being recalculated directly after this operation. The script is executed in the same way, as when reactivating PythonPart with double-click and terminating with ++ESC++.

You can add following tags:

Tag Recalculation is triggered, when
<AttributeEvent> attributes of the PythonPart has been modified
<CopyEvent> the PythonPart element was copied
<DeleteEvent> the PythonPart element was deleted
<MoveEvent> the PythonPart element was moved
<VisibleEvent> the PythonPart element was hidden/shown

Tip

For the sake of performance and avoiding PythonParts to recalculate in situations, when there is no recalculation needed, add only these tags to PYP that you really need.

Info

There are situations when PythonPart script is executed without having you to add any tag. For example:

  • when you added at least one parameter of value type PlaneReferences into your PYP file and the planes have changed. The PythonPart is executed with the execution_event equal to ePlaneChanges (more about execution events below )

  • when you associated your PythonPart with another element (see here how to do it) and this element has been modified. In this case, the PythonPart script is executed with the execution_event equal to eConnection

Script implementation

When the PythonPart script is executed, the information what event has triggered the execution is passed by the PythonParts framework in the property execution_event of the BaseScriptObjectData (when using script object contract) or the BaseInteractorData (when using interactor contract). So, you can react to each event in a specific way.

class MyScriptObject(BaseScriptObject):

    def __init__(self, build_ele, script_object_data):
        super().__init__(script_object_data)
        self.build_ele = build_ele

    def foo(self):
        if self.execution_event == AllplanSettings.ExecutionEvent.eCreation:
            # this will be executed during the creation of the element

        elif self.execution_event == AllplanSettings.ExecutionEvent.eMove:
            # this will be executed when the PythonPart was moved

def create_interactor(interactor_data: BaseInteractorData) -> YourInteractor:
    return YourInteractor(interactor_data)
...
class YourInteractor(BaseInteractor):

    def __init__(self, interactor_data: BaseInteractorData):
        self.execution_event = interactor_data.execution_event

    def foo(self):
        if self.execution_event == AllplanSettings.ExecutionEvent.eCreation:
            # this will be executed during the creation of the element

        elif self.execution_event == AllplanSettings.ExecutionEvent.eMove:
            # this will be executed when the PythonPart was moved

Tip

When a PythonPart has been moved or copied, you can get the transformation matrix that was used to move/copy the PythonPart from the original to the target position. It's saved in the modification_matrix property of the BaseInteractorData or BaseScriptObjectData

Info

The <DeleteEvent> is an exception! When a PythonPart with this tag gets deleted, only the function execute_pre_element_delete() is called and not the entire script!

def execute_pre_element_delete(doc                  : AllplanEleAdapter.DocumentAdapter,
                               build_ele_list       : list[BuildingElement],
                               modification_ele_list: ModificationElementList) -> None:

    # all the instruction here are executed before the PythonPart gets deleted

Have a look on the example PythonPartConnection ( PYP | PY)

Example

Have a look at the example PythonPartWithAttributes ( PYP | PY). in which the AttributeEvent is activated. This leads to change of the geometry directly after the attribute Layer thickness is modified.

Update of identical PythonParts

Update of identical PythonParts

After a PythonPart has been changed, ALLPLAN searches through the DF for other PythonParts with the same hash. If some are found, a dialog box, as shown on the right, appears. After the user hits yes, ALLPLAN recreates these PythonParts, applying the same values to their parameters, as the ones specified for the originally modified PythonPart, ensuring all the identical PythonParts remains identical after the modification.

In some cases, we want two PythonParts to be considered identical, despite some parameter values being different. E.g. a parameter responsible for rotation is not relevant, because two PythonParts rotated differently, are still the same. In this case, it makes sense to exclude these rotation parameters from the identical check. To achieve this, add the <ExcludeIdentical> tag to the <Parameter>.

<ExcludeIdentical>True</ExcludeIdentical>

Example on GitHub

Have a look on the example IdenticalRotatedPlate ( PYP | PY).

In this example, a plate can be rotated around all three axes. The rotation angle is entered in the palette as a parameter. If all parameters would be used for an identical check, plates with identical geometry, but not identical rotation angles will not be considered identical. Setting the <ExcludeIdentical> tag to True in the rotation parameter solves this issue.

Modify existing PythonParts

You can build a script that is modifying existing PythonParts. This might be useful, if you want to cover a complex modification workflow or allow bulk modification of many PythonParts and you want to provide the user with a tool just for that.

Info

The modification of a PythonPart is different from modifying any other element, because it is usually followed by the recalculation (running the Python script through). If your modification does not require it, you can follow the instructions for a general element modification in this article

The modification of an existing PythonPart requires you to implement the selection, which is possible only with a script object or an interactor. In the following description, the selected_pyp ist the BaseElementAdapter pointing to the PythonPart

Tip

With the PythonPartByNameFilter you can construct a filter object, that filters only the PythonParts of the same type (created by the same script) as the selected PythonPart

pyp_name_filter = PythonPartByNameFilter(selected_pyp)

The simplest modification of a PythonPart consists of two steps:

  1. Prepare new parameter values. Build a list with ModifiedParameterData. Each entry in this list represents a parameter modification.

    new_param_data = [ModifiedParameterData("Length", new_length), #(1)!
                  ModifiedParameterData("Width", new_width), #(2)!
                  ]

    1. If the new value depends on the old one, you can read the old values like:

      _, _, old_parameters = AllplanBaseElements.PythonPartService.GetParameter(selected_pyp)
old_length = ParameterListUtil.get_value_double(old_parameters, "Length")
new_length = old_length + 1000.0

    2. Order matters! Each list entry calls the modify_element_property method in exactly the same order, as given in the list.

  2. Recalculate the PythonPart. Use the static method ModifyPythonPartParameterUtil.execute() to do that.

    ModifyPythonPartParameterUtil.execute(selected_pyp, self.coord_input, new_param_data) #(1)!

    1. If you just want to update the PythonPart, without changing any parameter, just pass an empty list:

      ModifyPythonPartParameterUtil.execute(selected_pyp, self.coord_input, [])

    The method call basically simulates1 following actions:

    • double-click on a PythonPart to modify it
    • changing the properties in the palette as specified new_param_data
    • hitting Esc to close it

Tip

Just like during manual modification, if there are several identical PythonParts in the model, the user will get the pop-up about updating identical PythonParts. To suppress it, define a context manager like:

class SurpressIdenticalUpdate:
    pyp_settings = AllplanSettings.PythonPartsSettings.GetInstance()

    def __init__(self):
        self.original_state = AllplanSettings.UpdateIdenticalPythonPartsState.eUndefinded

    def __enter__(self):
        self.original_state = self.pyp_settings.UpdateIdenticalPythonParts
        self.pyp_settings.UpdateIdenticalPythonParts = AllplanSettings.UpdateIdenticalPythonPartsState.eDoNotUpdateIdentical

    def __exit__(self, exc_type, exc_value, traceback):
        self.pyp_settings.UpdateIdenticalPythonParts = self.original_state

And use it while performing the modification:

with SurpressIdenticalUpdate():
    # whatever action is introduced here, the pop-up will be surpressed
    ModifyPythonPartParameterUtil.execute(selected_pyp, self.coord_input, new_param_data)

# and here everything is back to normal

Tip

If, after selecting a PythonPart, you want to show its palette to the user, let him/her do the input and recalculate PythonPart after that, you can introduce this workflow step with the ModifyPythonPartUtil. Assign it to the script_object_interactor property of your interactor:

def start_next_input(self):
    self.palette_service.close_palette()  #(1)!
    self.script_object_interactor = ModifyPythonPartUtil(self.sel_result.sel_element)
    self.script_object_interactor.start_input(self.coord_input)
  1. It will open the palette of the modified PythonPart, so make sure to close the palette of your modification PythonPart.

Example on GitHub

To see the full implementation, have a look on the following examples:

PythonPart transaction

In some situations it's required to undertake some actions after the elements are created. A good example is the rearrangement of the reinforcement mark numbers. We can do this only after the reinforcement is created, because only then ALLPLAN is able to recognize identical shapes.

The class PythonPartTransaction takes care of exactly that. It creates model elements and subsequently introduces additional steps, so that you as a developer doesn't have to implement them. These steps can involve:

  • taking care of correct creation of PrecastElements
  • recreating reinforcement labels added with native ALLPLAN function
  • connecting existing elements and the PythonPart
  • rearrangement of the reinforcement mark numbering
  • creation of the undo step

Note

When you create your script as a Standard PythonPart, the transaction is executed by the framework for you. In an Interactor PythonPart you have to implement it yourself.

Example

Before executing the transaction, the object has to be constructed first:

pyp_transaction = PythonPartTransaction(self.coord_input.GetInputViewDocument())

After constructing the transaction, we can call the execute method. We call it at the point, where we would create the elements from the model_ele_list in the drawing file:

pyp_transaction.execute(placement_matrix       = AllplanGeo.Matrix3D(),
                        view_world_projection  = self.coord_input.GetViewWorldProjection(),
                        model_ele_list         = model_element_list, #(1)!
                        modification_ele_list  = self.modification_ele_list, #(2)!
                        rearrange_reinf_pos_nr = ReinforcementRearrange(), #(5)!
                        append_reinf_pos_nr    = True,
                        uuid_parameter_name    = "",  #(3)!
                        use_system_angle       = True) #(4)!
  1. Here we pass the list of model elements that we want to create. For elements, that requires additional actions after the creation (like e.g. a PrecastElement), these actions will be introduced by the framework, as they are already implemented in the execute method.
  2. In a modification mode, this list should contain UUIDs of the modified elements, so that these elements preserves their other unique identifications after the modification (e.g. IfcID). In a PythonPart script constructed as an Interactor you get this list the create_interactor function.
  3. If you want to save the UUID of the PythonPart, you create, in one of its parameters, you can provide the name of this parameter here. This might be important, if you create a PythonPart that should react accordingly, when being modified after being copied by the user. Because after being copied, the PythonPart becomes a new UUID, but its parameters remain. This is how you can make the copied PythonPart remember the UUID of the PythonPart it originated from.
  4. When set to True, the elements are rotated accordingly to consider the crosshair rotation during the creation.
  5. See the documentation of ReinforcementRearrange class to learn about possible settings.

After calling the execute method, elements from the model_ele_list are created in the model. Subsequently, a series of actions are performed. See the documentation of the method for more details.

Example on GitHub

For a complete usage of PythonPartTransaction, see the example WallInteractor ( PYP | PY)

  1. During the update, few features are turned off for better performance e.g., handles are not shown. ↩

Placeholder