Common Functions

Common Functions

setup/templates/common_functions.py is a reference file containing helper functions that appear across multiple scripts in this repository. Copy the functions you need into your own script — do not import the file directly.

Functions are grouped into four categories:

• Geometric Set Navigation
• Geometry Operations
• Coordinate Maths
• File Input

---

1. Geometric Set Navigation

searchHybridBody

Searches for a geometric set by name and returns it. Searches recursively through all nested sets.

def searchHybridBody(seachName, currentHybridBodies):

Parameter	Description
seachName	Name of the geometric set to find
currentHybridBodies	Collection to search (e.g. part.hybrid_bodies)

Returns: The HybridBody if found, None if not found.

hb = searchHybridBody("My_Set", part.hybrid_bodies)
if hb is None:
    print("Not found")

---

searchHybridBodyWithPath

Same as searchHybridBody, but also returns the /-separated path to the found set.

def searchHybridBodyWithPath(seachName, currentHybridBodies, currentPath=""):

Parameter	Description
seachName	Name of the geometric set to find
currentHybridBodies	Collection to search
currentPath	Accumulated path — leave empty on the first call

Returns: (HybridBody, path_string) if found, (None, None) if not found.

hb, path = searchHybridBodyWithPath("My_Set", part.hybrid_bodies)
# path == "Parent_Set/Child_Set/My_Set"

---

2. Geometry Operations

create_datum

Replaces a hybrid shape with an isolated datum of the same type, preserving its name. Supports points (1), curves (2), lines (3), circles (4), and surfaces (5). Unsupported types are skipped with a warning.

def create_datum(hybrid_shape_factory, hybrid_shape, hybrid_body, name=None):

Parameter	Description
hybrid_shape_factory	part.hybrid_shape_factory
hybrid_shape	The HybridShape to isolate
hybrid_body	Geometric set to append the new datum to
name	Optional name for the datum

Returns: None. Call part.update() after one or more create_datum calls.

create_datum(hybrid_shape_factory, my_shape, target_set, name="My_Datum")
part.update()

---

collect_all_names

Recursively collects all (shape_name, parent_set_name) tuples from a geometric set and all its nested children.

def collect_all_names(hybrid_body, name_list):

Parameter	Description
hybrid_body	The geometric set to scan
name_list	A list to append tuples to — pass an empty list on the first call

Returns: None — appends (name, parent_set_name) tuples directly to name_list.

all_names = []
collect_all_names(target_set, all_names)
# all_names == [("Shape1", "Set_A"), ("Shape2", "Set_B"), ...]

---

3. Coordinate Maths

These functions require spa_workbench = part_document.spa_workbench() for coords_relative_to_axis.

normalize_vector

Normalises a 3D vector to unit length.

def normalize_vector(vec):

Returns: (x, y, z) normalised tuple, or None if the vector has zero magnitude.

---

dot_product

Returns the dot product of two 3D vectors.

def dot_product(vec1, vec2):

Returns: Scalar dot product.

---

cross_product

Returns the cross product of two 3D vectors.

def cross_product(a, b):

Returns: Cross product as a list [x, y, z].

---

are_collinear

Checks whether three 3D points are collinear (lie on the same line). Uses the cross product method with a small epsilon for floating-point tolerance.

def are_collinear(point_a, point_b, point_c):

Returns: True if collinear, False otherwise.

---

coords_relative_to_axis

Measures a point's coordinates relative to a given axis system.

def coords_relative_to_axis(part, spa_workbench, axis_system, point, precision=6):

Parameter	Description
part	The Part object (part_document.part)
spa_workbench	part_document.spa_workbench()
axis_system	The axis system to measure relative to
point	The HybridShapePointCoord to measure
precision	Decimal places to round to (default 6)

Returns: (x, y, z) in the axis system's local coordinate frame.

spa_workbench = part_document.spa_workbench()
coords = coords_relative_to_axis(part, spa_workbench, my_axis, my_point)

---

4. File Input

get_path

Opens a wx file-open dialog and returns the selected file path, or None if cancelled. The dialog is automatically raised above CATIA using _bring_to_front (defined as a nested function inside get_path to keep it self-contained). Imports wx and ctypes internally — no wx.App(None) call is needed before calling this function.

def get_path(wildcard):

Parameter	Description
wildcard	File type filter string, e.g. '*.txt;*.csv'

Returns: Selected file path as a string, or None if cancelled.

path = get_path('*.txt;*.csv')
if path is None:
    exit()

---

All functions are available in setup/templates/common_functions.py. Copy what you need — do not import the file.