# 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.

Every port is described by:

- Its position .
- A normal vector which points out of the fitting and it is perpendicular to the port plane.
- A 0 reference angle vector it shows where is the degree 0°. 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 and its orientation .

The position is a FreeCAD Vector . The orientation is a FreeCAD rotation matrix. When we apply matrix on vectors , , , it creates vectors , , such that

- points in the same direction as the port's normal, .
- shows in the same direction as the angular reference, .

For example in a tee fitting, the matrix is a rotation along y-axis by , and then a rotation along z axis by . See FreeCAD Rotation for more details about rotation.

## 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 , orientation with normal and 0 degree reference . Everything refering to the local coordinates of the fitting.

The other fitting has position and rotation . The local properties of its port has has local position , local orientation , local normal and local 0 degree reference . That means the corresponding global parameter of the port are

We want to find a rotation matrix 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: .
- Its zero-degree reference points to the same direction

We compose the matrix from three matrices and .

- rotates the fitting in such a way that its port points to x-direction, and 0 reference to y-direction.
- rotates the fitting opposite to x-direction, but its 0 reference still points to y-direction.
- rotate oposite rotated port to the same direction as the port of the other fitting.
- 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

## 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 can be expressed as 180° rotation along the y axis: *FreeCAD.Rotation(0, 180, 0)*.