# Geometry nodes¶

Geometry nodes are the backbone of a model. They determine what can move and what can not. If the model is an animal, then the geometry nodes are the joints and bones.

## Frame¶

The first and most important geometry node is the Frame node, short for Axis-Frame. The frame node represents something rigid such as a bone, a ship or a crane boom. Mathematically the frame node is a 3d reference frame with an origin and an orientation. The frame node has six degrees of freedom which can be enabled or disabled individually. This defines if and how it can move. It may also be connected to an other frame node. In that case the position, orientation and degrees of freedom are defined relative to that other frame.

Properties

The parent of an frame determines if the frame node is connected to another node. If a frame does not have a parent then it is defined relative to the global axis system.

The position of a frame determines the position of the origin of the axis system relative to its parent. The rotation of a frame determines the rotation.

Both position and rotation are 3d vectors. All components of the position and rotation vector can individually be set to “fixed” or “free”. If a component is “free” then the frame can move in this degree of freedom. When solving statics the solver will determine a value for this component such that the system is in equilibrium.

For example defining the position as (free, 0, 23) results in a frame at elevation 23 and y=0 that can slide in the x-direction. Defining both the position and rotation as (free, free, free) means a frame that is completely free to move.

3D rotations

Unlike in 2d, 3D rotations can suffer from many definition issues such as order of rotations and gimbal locks. DAVE uses a mathematically sound definition of rotation: the rotation vector.

The 3d rotation vector defines the rotation. The length of the vector is the rotation in degrees, the direction of the vector is the axis of rotation. Imagine the rotation vector as a hinge. The direction of the vector is the axis of the hinge (like in a door), the magnitude is the angle it makes. A rotation of (10,0,0) is a rotation of 10 degrees about the x-axis. A rotation of (5,0,5) is a rotation of 7.07 degrees about the (1,0,1) axis.

Some typical joints can be defined as follows: Ball-joint: rotation = (free, free, free) Hinge-joint about x : rotation = (free, 0 ,0) Hinge-joint about y : rotation = (0, free ,0) Hinge-joint about z : rotation = (0 ,0, free)

A rotation of (free, free, 0) defines a rotation vector located in the xy plane: A rotation about an horizontal axis.

For all these joints the non-free component is zero. It is mathematically possible to allow a non-zero value for one of the other components but it is difficult to interpret what is means. Try to imagine what a rotation vector of (free, free ,10) is. One may think for a moment that this is a good way to define a vessel that can roll (x=free) and pitch (y=free) but has a fixed heading of 10 degrees. But is not. It is a rotation with a minimum of 10 degrees about and axis that is at least a little vertical and uhm…. Well, not very practical. Therefore the following limitation is applied: if one or two degrees of freedom of the rotation are free, then the other component is 0. This is enforced when solving.

So how to define a vessel that can roll and pitch but has a fixed, non-zero heading? Simple: break up the rotation is different parts. First make a frame with rotation = (0,0,10) which defines the heading. Then make a second frame with rotation = (free, free, 0) and connect that to the first one.

And this is how to make a hinge about an direction of (1,2,3) : First make a frame node with its rotation set to (1,2,3), then place a second axis-frame node with (free, 0, 0) on top of it.

Stack axis-frame nodes to define rotations about directions other than the principal ones

DAVE allows us to get/set the rotations and positions using either the local or global reference frames. Setting one will also update the other. In the end the local position and rotation are used in combination with the degrees of freedom.

There are a some read-only convenience properties to get the orientation of a frame using common definitions: heel, trim, heading, tilt. These are derived from the global rotation.

Property

Documentation

inertia

The linear inertia of the axis in [mT] Aka: “Mass”
- used only for dynamics

inertia_position

The position of the center of inertia. Aka: “cog” [m,m,m] (local axis)
- used only for dynamics
- defined in local axis system

The radii of gyration of the inertia [m,m,m] (local axis)

Used to calculate the mass moments of inertia via

Ixx = rxx^2 * inertia
Iyy = rxx^2 * inertia
Izz = rxx^2 * inertia

Note that DAVE does not directly support cross terms in the interia matrix of an axis system. If you want to
use cross terms then combine multiple axis system to reach the same result. This is because inertia matrices with
diagonal terms can not be translated.

fixed

Determines which of the six degrees of freedom are fixed, if any. (x,y,z,rx,ry,rz).
True means that that degree of freedom will not change when solving statics.
False means a that is may be changed in order to find equilibrium.

These are the expressed on the coordinate system of the parent (if any) or the global axis system (if no parent)

x

The x-component of the position vector (parent axis) [m]

y

The y-component of the position vector (parent axis) [m]

z

The z-component of the position vector (parent axis) [m]

position

Position of the axis (parent axis) [m,m,m]

These are the expressed on the coordinate system of the parent (if any) or the global axis system (if no parent)

rx

The x-component of the rotation vector [degrees] (parent axis)

ry

The y-component of the rotation vector [degrees] (parent axis)

rz

The z-component of the rotation vector [degrees], (parent axis)

rotation

Rotation of the axis about its origin (rx,ry,rz).
Defined as a rotation about an axis where the direction of the axis is (rx,ry,rz) and the angle of rotation is

parent

Determines the parent of the axis. Should either be another axis or ‘None’

Other axis may be refered to by reference or by name (str). So the following are identical

p = s.new_axis(‘parent_axis’)
c = s.new_axis(‘child axis’)

c.parent = p
c.parent = ‘parent_axis’

To define that an axis does not have a parent use

c.parent = None

gx

The x-component of the global position vector [m] (global axis )

gy

The y-component of the global position vector [m] (global axis )

gz

The z-component of the global position vector [m] (global axis )

global_position

The global position of the origin of the axis system [m,m,m] (global axis)

grx

The x-component of the global rotation vector [degrees] (global axis)

gry

The y-component of the global rotation vector [degrees] (global axis)

grz

The z-component of the global rotation vector [degrees] (global axis)

tilt_x

Tilt percentage. This is the z-component of the unit y vector [%].

heel

Heel in degrees. SB down is positive [deg].
This is the inverse sin of the unit y vector(This is the arcsin of the tiltx)

tilt_y

Tilt percentage. This is the z-component of the unit -x vector [%].
So a positive rotation about the y axis results in a positive tilt_y.

trim

Trim in degrees. Bow-down is positive [deg].

This is the inverse sin of the unit -x vector(This is the arcsin of the tilt_y)

Direction (0..360) [deg] of the local x-axis relative to the global x axis. Measured about the global z axis

typically:
heading 0 –> local axis align with global axis
heading 90 –> local x-axis in direction of global y axis

The heading (0..360)[deg] assuming that the global y-axis is North and global x-axis is East and rotation accoring compass definition

global_rotation

Rotation [deg,deg,deg] (global axis)

global_transform

Read-only: The global transform of the axis system [matrix]

connection_force

The forces and moments that this axis applies on its parent at the origin of this axis system. [kN, kN, kN, kNm, kNm, kNm] (Parent axis)

If this axis would be connected to a point on its parent, and that point would be located at the location of the origin of this axis system
then the connection force equals the force and moment applied on that point.

Example:
parent axis with name A
this axis with name B
this axis is located on A at position (10,0,0)
there is a Point at the center of this axis system.
A force with Fz = -10 acts on the Point.

The connection_force is (-10,0,0,0,0,0)

This is the force and moment as applied on A at point (10,0,0)

connection_force_x

The x-component of the connection-force vector [kN] (Parent axis)

connection_force_y

The y-component of the connection-force vector [kN] (Parent axis)

connection_force_z

The z-component of the connection-force vector [kN] (Parent axis)

connection_moment_x

The mx-component of the connection-force vector [kNm] (Parent axis)

connection_moment_y

The my-component of the connection-force vector [kNm] (Parent axis)

connection_moment_z

The mx-component of the connection-force vector [kNm] (Parent axis)

applied_force

The force and moment that is applied on origin of this axis [kN, kN, kN, kNm, kNm, kNm] (Global axis)

ux

The unit x axis [m,m,m] (Global axis)

uy

The unit y axis [m,m,m] (Global axis)

uz

The unit z axis [m,m,m] (Global axis)

equilibrium_error

The unresolved force and moment that on this axis. Should be zero when in equilibrium (applied-force minus connection force, Parent axis)

## Circles and points¶

Points and circles are helpers. They define locations (points) or circular geometry (circles) that can be used by other nodes such as cables.

### Point¶

Points are locations or attachment points. They can be located on a frame, but can also be defined globally. In that case they fixed in space.

Property

Documentation

x

x component of local position [m] (parent axis)

y

y component of local position [m] (parent axis)

z

z component of local position [m] (parent axis)

position

Local position [m,m,m] (parent axis)

applied_force_and_moment_global

Applied force and moment on this point [kN, kN, kN, kNm, kNm, kNm] (Global axis)

gx

x component of position [m] (global axis)

gy

y component of position [m] (global axis)

gz

z component of position [m] (global axis)

global_position

Global position [m,m,m] (global axis)

### Circle¶

A circle is a disk or hole. A circle is located on a point. It has a diameter/radius and a direction.

Property

Documentation

axis

Direction of the sheave axis (x,y,z) in parent axis system.

Note:
The direction of the axis is also used to determine the positive direction over the circumference of the
circle. This is then used when cables run over the circle or the circle is used for geometric contacts. So
if a cable runs over the circle in the wrong direction then a solution is to change the axis direction to
its opposite: circle.axis =- circle.axis. (another solution in that case is to define the connections of
the cable in the reverse order)

global_position

Returns the global position of the center of the sheave.

Note: this is the same as the global position of the parent point.

## Geometric-Contact¶

Geometric contact can be used to model contact bewteen circlular objects (bars) or circular holes. Examples are a shackle pin in a padeye hole (pin-hole connection) or a shackle pin against the bow of another shackle (bar-bar connection).

This is a rigid and unbreakable connection constructed by a clever combination of frames. This means that it is not a connection with a stiffness (the contact is infinitely stiff). It also means that a geometric contact creates a parent-child relation between the two connected frames.

A GeometricContact can be used to construct geometric connections between circular members:
- 	steel bars and holes, such as a shackle pin in a padeye (pin-hole)
-	steel bars and steel bars, such as a shackle-shackle connection

Situation before creation of geometric contact:

Axis1
Point1
Circle1
Axis2
Point2
Circle2

Create a geometric contact with Circle1 and parent and Circle2 as child

Axis1
Point1              : observed, referenced as parent_circle_parent
Circle1         : observed, referenced as parent_circle

_axis_on_parent                 : managed
_pin_hole_connection        : managed
_connection_axial_rotation : managed
_axis_on_child      : managed
Axis2           : managed    , referenced as child_circle_parent_parent
Point2      : observed   , referenced as child_circle_parent
Circle2 : observed   , referenced as child_circle


Property

Documentation

child

The Circle that is connected to the GeometricContact [Node]

parent

The Circle that the GeometricConnection is connected to [Node]

swivel

Swivel angle between parent and child objects [degrees]

swivel_fixed

Allow parent and child to swivel relative to eachother [boolean]

rotation_on_parent

Angle between the line connecting the centers of the circles and the axis system of the parent node [degrees]

fixed_to_parent

Allow rotation around parent [boolean]

child_rotation

Angle between the line connecting the centers of the circles and the axis system of the child node [degrees]

child_fixed

inside

Type of connection: True means child circle is inside parent circle, False means the child circle is outside but the circumferences contact [boolean]