Table of Contents

Class CartesianCoordinateSystem

Namespace
VirtualLabAPI.Core.Numerics
Assembly
VirtualLabAPI.dll

Class for right-handed Cartesian coordinate systems.

[Serializable]
public class CartesianCoordinateSystem : ManualSerialization, IEquatable<IObjectBase>, ISerializable, IDeserializationCallback, ICloneable
Inheritance
ObjectBase
SerializableObjectBase
ManualSerialization
CartesianCoordinateSystem
Implements
IEquatable<IObjectBase>
Inherited Members

Constructors

CartesianCoordinateSystem()

Default constructor, creating a new CartesianCoordinateSystem that is defined absolutely, and identical to the global coordinate system.

public CartesianCoordinateSystem()

CartesianCoordinateSystem(CartesianCoordinateSystem)

Copy constructor.

public CartesianCoordinateSystem(CartesianCoordinateSystem cs)

Parameters

cs CartesianCoordinateSystem

Coordinate system to be copied.

CartesianCoordinateSystem(IProvidesPositioningReferences, string)

Constructor, creating a new CartesianCoordinateSystem that is defined in reference to a given reference cs, it lies at (0,0,0) and is not rotated to this reference.

public CartesianCoordinateSystem(IProvidesPositioningReferences positioningReferenceProvider, string positioningReferenceKey)

Parameters

positioningReferenceProvider IProvidesPositioningReferences

Object which provides the coordinate system that serves as reference for this position.

positioningReferenceKey string

Key for the coordinate system (contained by PositioningReferenceProvider) which shall serve as reference for this position.

Exceptions

PositionigReferenceKeyUnknownException

CartesianCoordinateSystem(Position)

Constructor for a Cartesian coordinate system that is translated but not rotated with respect to the reference coordinate system. The pointer to the reference coordinate system is stored in variable origin.

public CartesianCoordinateSystem(Position origin)

Parameters

origin Position

Position of the origin with respect to the reference coordinate system, that is set via origin.ReferenceCoordinateSystem.

CartesianCoordinateSystem(Position, CoordinateSystemBaseVectors)

Constructor that uses a Position and a SystemBaseVectors

public CartesianCoordinateSystem(Position origin, CoordinateSystemBaseVectors axes)

Parameters

origin Position

Position of origin

axes CoordinateSystemBaseVectors

Directions of the axes

CartesianCoordinateSystem(Position, Quaternion)

Constructor that uses a position for the origin and which creates the base vectors from a quaternion.

public CartesianCoordinateSystem(Position origin, Quaternion quaternionOfBase)

Parameters

origin Position

Position of the origin.

quaternionOfBase Quaternion

Quaternion that describes the Cartesian base.

CartesianCoordinateSystem(Position, Vector3D, Vector3D, CoordinatePlane)

Constructor which gets the origin and only two base vectors. This may be helpful if one of the base vectors has already been created from a cross product, so creating the third base vector also by a cross product may produce large numerical problems.

public CartesianCoordinateSystem(Position origin, Vector3D axis1, Vector3D axis2, CoordinatePlane plane)

Parameters

origin Position

Position of the origin.

axis1 Vector3D

First base vector (meaning is set by planeIndex).

axis2 Vector3D

Second base vector (meaning is set by planeIndex).

plane CoordinatePlane

Sets the meaning of axis1 and axis2 by defining which plane is spanned by the given axes.

CartesianCoordinateSystem(Position, Vector3D, Vector3D, Vector3D)

Constructor that uses a position for the origin and the new axes, which must be orthogonal and should be normalized. This constructor is not recommended, because there's a significant probability for numerical inaccuracies which cause orthogonality problems. Better options may be the constructors getting a OrientationDefinitionBase or getting two axes and a plane index.

public CartesianCoordinateSystem(Position origin, Vector3D xAxis, Vector3D yAxis, Vector3D zAxis)

Parameters

origin Position

Position of the origin.

xAxis Vector3D

Direction cosine of the x-axis.

yAxis Vector3D

Direction cosine of the y-axis.

zAxis Vector3D

Direction cosine of the z-axis.

Properties

Axes

Gets or sets the axes or base vectors of the coordinate system

public CoordinateSystemBaseVectors Axes { get; set; }

Property Value

CoordinateSystemBaseVectors

GetAllCoordinateSystemChangedEventTargets

Auxiliary method for finding all targets for the invocation of this element's CoordinateSystemChanged event

public List<object> GetAllCoordinateSystemChangedEventTargets { get; }

Property Value

List<object>

GetPositioningReference

Property to get the coordinate system that serves as reference for this object

public CartesianCoordinateSystem GetPositioningReference { get; }

Property Value

CartesianCoordinateSystem

IsDefinedAbsolutely

Are the origin's position and the axes directions defined absolutely?

public bool IsDefinedAbsolutely { get; }

Property Value

bool

IsUndefined

Gets whether the coordinate system is undefined.

public bool IsUndefined { get; }

Property Value

bool

true iff the Origin member is undefined.

Origin

Gets or sets the origin of the coordinate system

public Position Origin { get; set; }

Property Value

Position

PositioningReferenceKey

Get the key of the reference coordinate system for this

public string PositioningReferenceKey { get; }

Property Value

string

PositioningReferenceProvider

Get the object that provides the reference coordinate system for this

public IProvidesPositioningReferences PositioningReferenceProvider { get; }

Property Value

IProvidesPositioningReferences

Methods

AxisAsPositionedLine(AxisDirection)

Extracts one axis as positioned line

public PositionedLine AxisAsPositionedLine(AxisDirection chosenAxis)

Parameters

chosenAxis AxisDirection

Axis to extract

Returns

PositionedLine

Positioned line with the direction of the given axis and the position of this coordinate system.

Clone()

Deep copy

public override object Clone()

Returns

object

Copy of this

Equals(object?, EqualityIntent)

Method which checks for equal objects.

public override bool Equals(object? obj, EqualityIntent equalityIntent)

Parameters

obj object

Object to compare with this.

equalityIntent EqualityIntent

Defines what kind of equality you want to check when comparing two objects, for example all values or physical equality.

Returns

bool

true if obj and this are equal.

GetCSForReflection(CartesianCoordinateSystem, OrientedPlane)

Gets the coordinate system reflected, that means mirrored, on a given plane.

public static CartesianCoordinateSystem GetCSForReflection(CartesianCoordinateSystem coordinateSystemInput, OrientedPlane mirrorPlane)

Parameters

coordinateSystemInput CartesianCoordinateSystem

The coordinate system from the coordinate system for reflection is being generated.

mirrorPlane OrientedPlane

The plane the coordinateSystemInput is mirrored on.

Returns

CartesianCoordinateSystem

The input coordinate system, mirrored at mirrorPlane.

GetCSFromAxisRotationsSequence(Position, AxisRotationSequence)

Constructs a new Cartesian coordinate system via axis rotation sequence

public static CartesianCoordinateSystem GetCSFromAxisRotationsSequence(Position origin, AxisRotationSequence sequence)

Parameters

origin Position

Origin of coordinate system in reference coordinates.

sequence AxisRotationSequence

AxisRotationSequence that determines how to get the new coordinate system starting from its reference system.

Returns

CartesianCoordinateSystem

New Cartesian coordinate system.

GetCSFromCartesianAnglesOfZAxis(Position, double, double, double, bool)

Constructs a new Cartesian coordinate system with respect to the reference cs (stored in origin) via z-rotation and Cartesian angles for the z-axis: The orientation of the coordinate system results from the reference cs in 2 steps and a certain order. A) inclinationFirst = false: (i) Rotation about z-axis with angle zeta - using the right-hand-rule, (ii) Inclination of z-axis specified by Cartesian angles. B) inclinationFirst = true: (i) Inclination of z-axis specified by Cartesian angles, (ii) Rotation about inclined z-axis by angle zeta - using the right-hand-rule.

public static CartesianCoordinateSystem GetCSFromCartesianAnglesOfZAxis(Position origin, double zeta, double alpha, double beta, bool inclinationFirst)

Parameters

origin Position

Origin of coordinate system in reference coordinates.

zeta double

Angle (radian) of rotation about z-axis by using the right-hand-rule.

alpha double

Angle between the z-axis and the projection of the z-axis onto the x-z-plane

beta double

Angle between the z-axis and the projection of the z-axis onto the y-z-plane

inclinationFirst bool

Flag to signal if z-axis is inclined first (true) or after rotation of z-axis (false).

Returns

CartesianCoordinateSystem

New Cartesian coordinate system.

GetCSFromDirectionAnglesOfZAxis(Position, double, double, double, double, bool)

Constructs a new Cartesian coordinate system with respect to the reference cs (stored in origin) via z-rotation and direction angles: The orientation of the coordinate system results from the reference cs in 2 steps and a certain order. A) inclinationFirst=false: (i) Rotation about z-axis with angle zeta - using the right-hand-rule, (ii) Inclination of z-axis specified by direction angles rho, sigma, tau with the positive x-, y- and z-axis. B) inclinationFirst = true: (i) Inclination of z-axis via rho, sigma, tau, (ii) Rotation about inclined z-axis by angle zeta - using the right-hand-rule.

public static CartesianCoordinateSystem GetCSFromDirectionAnglesOfZAxis(Position origin, double zeta, double rho, double sigma, double tau, bool inclinationFirst)

Parameters

origin Position

Origin of coordinate system in reference coordinates.

zeta double

Angle (in radian) of rotation about z-axis by using the right-hand-rule.

rho double

Direction cosine angle alpha in radian: angle of new z-axis with positive x-axis.

sigma double

Direction cosine beta in radian: angle of new z-axis with positive y-axis.

tau double

Direction cosine beta in radian: angle of new z-axis with positive z-axis.

inclinationFirst bool

Flag to signal if z-axis is inclined first (true) or after rotation of z-axis (false).

Returns

CartesianCoordinateSystem

New Cartesian coordinate system.

GetCSFromDirectionOfZAxis(Position, double, Vector3D, bool)

Constructs a new Cartesian coordinate system with respect to the reference cs (stored in origin) via z-rotation and the direction vector of the z-axis: The orientation of the coordinate system results from the reference cs in 2 steps and a certain order . A) inclinationFirst = false: (i) Rotation about z-axis with angle zeta - using the right-hand-rule, (ii) Inclination of z-axis specified by new direction axis. B) inclinationFirst = true: (i) Inclination of z-axis specified by direction vector, (ii) Rotation about inclined z-axis by angle zeta - using the right-hand-rule.

public static CartesianCoordinateSystem GetCSFromDirectionOfZAxis(Position origin, double zeta, Vector3D directionOfZAxis, bool inclinationFirst)

Parameters

origin Position

Origin of coordinate system in reference coordinates.

zeta double

Angle (radian) of rotation about z-axis by using the right-hand-rule.

directionOfZAxis Vector3D

Direction vector of new z-axis

inclinationFirst bool

Flag to signal if z-axis is inclined first (true) or after rotation of z-axis (false).

Returns

CartesianCoordinateSystem

New Cartesian coordinate system.

GetCSFromEulerAngles(Position, double, double, double)

Constructs a new Cartesian coordinate system from Euler angles. As our Euler angles definition follows the Z-X'-Z'-convention, the angles define a the rotation sequence consisting of exactly three simple rotations:

  1. rotation by Psi about the original Z axis,
  2. rotation by Theta about the new (intermediate) X' axis, which is also called 'line of nodes'
  3. rotation by Phi about the new Z' axis.
public static CartesianCoordinateSystem GetCSFromEulerAngles(Position origin, double eulerPsi, double eulerTheta, double eulerPhi)

Parameters

origin Position

Origin of coordinate system in reference coordinates.

eulerPsi double

Euler angle Psi (about original z-axis).

eulerTheta double

Euler angle Theta (about new x'-axis).

eulerPhi double

Euler angle Phi (about the new z'-axis).

Returns

CartesianCoordinateSystem

New Cartesian coordinate system.

GetCSFromOrientationDefinition(Position, OrientationDefinitionBase)

Constructs a new Cartesian coordinate system via any IOrientationDefinition

public static CartesianCoordinateSystem GetCSFromOrientationDefinition(Position origin, OrientationDefinitionBase orientationDefinition)

Parameters

origin Position

Origin of coordinate system in reference coordinates.

orientationDefinition OrientationDefinitionBase

IOrientationDefinition that determines how to get the new coordinate system starting from its reference system.

Returns

CartesianCoordinateSystem

New Cartesian coordinate system.

GetCSFromSphericalAnglesOfZAxis(Position, double, double, double, bool)

Constructs a new Cartesian coordinate system with respect to the reference cs (stored in origin) via z-rotation and spherical angles: The orientation of the coordinate system results from the reference cs in 2 steps and a certain order. A) inclinationFirst = false: (i) Rotation about z-axis with angle zeta - using the right-hand-rule, (ii) Inclination of z-axis by spherical angles phi and theta. B) inclinationFirst = true: (i) Inclination of z-axis by spherical angles phi and theta, (ii) Rotation about inclined z-axis by angle zeta - using the right-hand-rule.

public static CartesianCoordinateSystem GetCSFromSphericalAnglesOfZAxis(Position origin, double zeta, double zPhi, double zTheta, bool inclinationFirst)

Parameters

origin Position

Origin of coordinate system in reference coordinates.

zeta double

Angle (radian) of rotation about z-axis by using the right-hand-rule.

zPhi double

Spherical angle phi in radian for inclination of z-axis. This angle starts at the x-axis (zPhi = 0), while the y-axis corresponds to zPhi = 90°

zTheta double

Spherical angle theta in radian for inclination of z-axis.

inclinationFirst bool

Flag to signal if z-axis is inclined first (true) or after rotation about z-axis (false).

Returns

CartesianCoordinateSystem

New Cartesian coordinate system, created from the given spherical angles.

GetCSMirroredAtOwnXYPlane(CartesianCoordinateSystem)

Returns a coordinate system that is mirrored at its own x-y-plane.

public static CartesianCoordinateSystem GetCSMirroredAtOwnXYPlane(CartesianCoordinateSystem coordinateSystemInput)

Parameters

coordinateSystemInput CartesianCoordinateSystem

Coordinate system to mirror at own x-y-plane.

Returns

CartesianCoordinateSystem

GetGlobalTransformationParameters(out Quaternion, out Vector3D)

Get the coordinate transformation parameters (rotation matrix and the origin position) with respect to the global coordinate system. A coordinate transformation from this coordinate system (x') to the global coordinate system (x) can be done by \(x = Rx' + o\) and vice versa: \(x' = R^T(x - o)\)

public void GetGlobalTransformationParameters(out Quaternion globalRotationMatrix, out Vector3D globalOriginPos)

Parameters

globalRotationMatrix Quaternion

Global rotation matrix \(R\).

globalOriginPos Vector3D

Origin \(o\) of this coordinate system in global (absolute) coordinates.

GetHashCode()

Just override

public override int GetHashCode()

Returns

int

GetReferenceHierarchy()

Gets the complete reference hierarchy of this. The global CS (null, "") will always be element 0 in the return list.

public List<(IProvidesPositioningReferences referenceProvider, string key)> GetReferenceHierarchy()

Returns

List<(IProvidesPositioningReferences referenceProvider, string key)>

The reference hierarchy of this as a list. Element 0 will be the global CS while element [Count - 1] will be the immediate reference of this.

GetRotatedAndTranslatedCoordinateSystem(Vector3D, Quaternion)

Returns a new coordinate system that is rotated and translated by given values in reference to this and defined to the same reference like this.

public CartesianCoordinateSystem GetRotatedAndTranslatedCoordinateSystem(Vector3D offset, Quaternion rotation)

Parameters

offset Vector3D

Translation distance, defined in the external CS

rotation Quaternion

Quaternion describing the rotation.

Returns

CartesianCoordinateSystem

The transformed coordinate system.

GetRotationAsSphericalAnglesOfZAxis(out double, out double)

Gets the orientation of this by calculating the sphere angles theta and phi for the z axis

public void GetRotationAsSphericalAnglesOfZAxis(out double theta, out double phi)

Parameters

theta double

Sphere angle theta, i.e. the inclination of the z axis to the z axis of the reference CS.

phi double

Sphere angle phi, i.e. the azimuth angle of the z axis to the x axis of the reference CS

GetTransformationParametersToCommonReference(CartesianCoordinateSystem?, CartesianCoordinateSystem?, out (Quaternion globalRotationMatrix, Vector3D globalOriginPos), out (Quaternion globalRotationMatrix, Vector3D globalOriginPos))

Method which calculates the transformation parameters for transforming from two coordinates systems to their common reference cs. See e.g. the constructor of TransformationsForCartesianCoordinateSystems for an example how to use the returned parameters.

public static void GetTransformationParametersToCommonReference(CartesianCoordinateSystem? cs1, CartesianCoordinateSystem? cs2, out (Quaternion globalRotationMatrix, Vector3D globalOriginPos) trafoFor1, out (Quaternion globalRotationMatrix, Vector3D globalOriginPos) trafoFor2)

Parameters

cs1 CartesianCoordinateSystem

Coordinate system 1 to calculate transformation parameters for.

cs2 CartesianCoordinateSystem

Coordinate system 2 to calculate transformation parameters for.

trafoFor1 (Quaternion globalRotationMatrix, Vector3D globalOriginPos)

The transformation parameters for transforming from the first cs to the common reference cs with the second cs.

trafoFor2 (Quaternion globalRotationMatrix, Vector3D globalOriginPos)

The transformation parameters for transforming from the second cs to the common reference cs with the first cs.

OnCoordinateSystemChanged()

Event throwing method

public void OnCoordinateSystemChanged()

SetPositioningReference(IProvidesPositioningReferences, string)

Method to set the PositioningReferenceProvider and the key for the coordinate system that serves as positioning reference

public void SetPositioningReference(IProvidesPositioningReferences referenceProvider, string key)

Parameters

referenceProvider IProvidesPositioningReferences

Object which provides the coordinate system that serves as reference for this position.

key string

Key for the coordinate system (contained by PositioningReferenceProvider) which shall serve as reference for this position

ToString()

method to generate a string description of the object

public override string ToString()

Returns

string

the string description

TransformInternalPosition2PositionInReferenceCS(Vector3D)

Transforms a given position in this CS to the reference CS.

public Vector3D TransformInternalPosition2PositionInReferenceCS(Vector3D internalPos)

Parameters

internalPos Vector3D

Position to transform

Returns

Vector3D

Transformed position in reference CS

TransformPositionInReferenceCS2InternalPosition(Vector3D)

Transforms a given position from the reference coordinate system to this CS.

public Vector3D TransformPositionInReferenceCS2InternalPosition(Vector3D externalPos)

Parameters

externalPos Vector3D

Position in the reference CS to transform

Returns

Vector3D

Transformed internal position

Events

CoordinateSystemChanged

Event that is thrown if the Coordinate System is changed

public event EventHandler CoordinateSystemChanged

Event Type

EventHandler

Operators

operator ==(CartesianCoordinateSystem, CartesianCoordinateSystem)

Overloaded equality operator

public static bool operator ==(CartesianCoordinateSystem cs1, CartesianCoordinateSystem cs2)

Parameters

cs1 CartesianCoordinateSystem

First CartesianCoordinateSystem to compare

cs2 CartesianCoordinateSystem

Second CartesianCoordinateSystem to compare

Returns

bool

Are both CartesianCoordinateSystem equal?

operator !=(CartesianCoordinateSystem, CartesianCoordinateSystem)

Overloaded inequality operator

public static bool operator !=(CartesianCoordinateSystem cs1, CartesianCoordinateSystem cs2)

Parameters

cs1 CartesianCoordinateSystem

First CartesianCoordinateSystem to compare

cs2 CartesianCoordinateSystem

Second CartesianCoordinateSystem to compare

Returns

bool

Are both CartesianCoordinateSystem unequal?