# 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 ${\displaystyle a\in \mathbb {R} ^{3}}$.
• A normal vector ${\displaystyle n\in \mathbb {R} ^{3}}$ which points out of the fitting and it is perpendicular to the port plane.
• A 0 reference angle vector ${\displaystyle r\in \mathbb {R} ^{3}}$ it shows where is the degree 0°. ${\displaystyle 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 ${\displaystyle A}$ and its orientation ${\displaystyle A}$.

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

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

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

Orientation of port 2 in a tee fitting.

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 ${\displaystyle a'}$, orientation ${\displaystyle A'}$ with normal ${\displaystyle n'}$ and 0 degree reference ${\displaystyle r'}$. Everything refering to the local coordinates of the fitting.

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

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

We want to find a rotation matrix ${\displaystyle 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: ${\displaystyle Bn'=-n_{g}}$.
• Its zero-degree reference points to the same direction ${\displaystyle Br'=r_{g}}$

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

• ${\displaystyle A'^{-1}}$ rotates the fitting in such a way that its port points to x-direction, and 0 reference to y-direction.
• ${\displaystyle A_{r}}$ rotates the fitting opposite to x-direction, but its 0 reference still points to y-direction.
• ${\displaystyle A}$ rotate oposite rotated port to the same direction as the port of the other fitting.
• ${\displaystyle 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

${\displaystyle 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 ${\displaystyle A_{r}}$ can be expressed as 180° rotation along the y axis: FreeCAD.Rotation(0, 180, 0).