OSE Piping Workbench Ports

Ports

The OSE Piping Workbench creates fittings. It uses ports to describe the ends of the fittings. The Ports helps to fit the fittings together correctly.

Ports of a tee in OSE Piping workbench.

Every port is described by:

• Its position $a\in \mathbb {R} ^{3}$.
• A normal vector $n\in \mathbb {R} ^{3}$ which points out of the fitting and it is perpendicular to the port plane.
• A 0 reference angle vector $r\in \mathbb {R} ^{3}$ it shows where is the degree 0°. $r$ must lie in the port plane.

All three vectors refer to local coordinates.

Instead of using three separate vectors, we represent the port by its position $A$ and its orientation $A$.

The position is a FreeCAD Vector $a\in \mathbb {R} ^{3}$. The orientation is a FreeCAD rotation matrix. When we apply matrix $A$ on vectors $x=(1,0,0)$, $y=(0,1,0)$, $y=(1,0,0)$, it creates vectors $x^{*}$, $y^{*}$, $y^{*}$ such that

• $x^{*}$ points in the same direction as the port's normal, $x^{*}=n$.
• $y^{*}$ shows in the same direction as the angular reference, $y^{*}=r$.

For example in a tee fitting, the matrix $A$ is a rotation along y-axis by $\phi =90^{\circ }$, and then a rotation along z axis by $\psi =-90^{\circ }$. See FreeCAD Rotation for more details about rotation.

Orientation of port 2 in a tee fitting.

Adjust two fittings

When we adjust one fitting to another we want rotate the first fitting in such a way that its socket points in opposite directions as a socket of the other fitting. Let us assume that the port of the adjusting fitting has position $a'$, orientation $A'$ with normal $n'$ and 0 degree reference $r'$. Everything refering to the local coordinates of the fitting.

The other fitting has position $p$ and rotation $R$. The local properties of its port has has local position $a$, local orientation $A$, local normal $n$ and local 0 degree reference $r$. That means the corresponding global parameter of the port are

$${\begin{aligned}a_{g}&:=p+Ra\\n_{g}&:=Rn\\r_{g}&:=Rr\\\end{aligned}}$$

We want to find a rotation matrix $B$ of the moved fitting, such that the new orientation of its port *in relating to global coordinate* has following properties:

• Its normal vector looks to opposite direction as the normal of the other fitting: $Bn'=-n_{g}$.
• Its zero-degree reference points to the same direction $Br'=r_{g}$

We compose the matrix from three matrices $A'^{-1}$$A_{r}$ and $A$.

• $A'^{-1}$ rotates the fitting in such a way that its port points to x-direction, and 0 reference to y-direction.
• $A_{r}$ rotates the fitting opposite to x-direction, but its 0 reference still points to y-direction.
• $A$ rotate oposite rotated port to the same direction as the port of the other fitting.
• $R$ rotate to corresponding global rotation.

Note. Rotation operations are not commutative and we need to perform all the rotation from right to left. We have

$$B:=R\cdot A\cdot A_{r}\cdot A'^{-1}$$

.

Ports in Python

In OsePiping.Port class the port position and orientation are stored in the Port.placement attribute as a FreeCAD.Placement object.

The matrix $A_{r}$ can be expressed as 180° rotation along the y axis: FreeCAD.Rotation(0, 180, 0).