Programming Reference for VirtualLab Fusion  2025.1
Loading...
Searching...
No Matches
CartesianCoordinateSystem Class Reference

This class is subject to change. Programs using this class may require changes with a new version of VirtualLab.
Class for right-handed Cartesian coordinate systems. More...

Inheritance diagram for CartesianCoordinateSystem:

Public Member Functions

PositionedLine AxisAsPositionedLine (AxisDirection chosenAxis)
 Extracts one axis as positioned line.
 
 CartesianCoordinateSystem ()
 Default constructor, creating a new CartesianCoordinateSystem that is defined absolutely, and identical to the global coordinate system.
 
 CartesianCoordinateSystem (CartesianCoordinateSystem cs)
 Copy constructor.
 
 CartesianCoordinateSystem (IProvidesPositioningReferences positioningReferenceProvider, string positioningReferenceKey)
 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.
 
 CartesianCoordinateSystem (Position origin)
 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.
 
 CartesianCoordinateSystem (Position origin, CoordinateSystemBaseVectors axes)
 Constructor that uses a Position and a SystemBaseVectors.
 
 CartesianCoordinateSystem (Position origin, OrientationDefinitionBase orientation)
 Constructor that uses a position for the origin and an orientation of the base vectors.
 
 CartesianCoordinateSystem (Position origin, Quaternion quaternionOfBase)
 Constructor that uses a position for the origin and which creates the base vectors from a quaternion.
 
 CartesianCoordinateSystem (Position origin, Vector3D axis1, Vector3D axis2, CoordinatePlane plane)
 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.
 
 CartesianCoordinateSystem (Position origin, Vector3D xAxis, Vector3D yAxis, Vector3D zAxis)
 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.
 
 CartesianCoordinateSystem (SerializationInfo info, StreamingContext context)
 Deserialization constructor used for manual serialization.
 
override object Clone ()
 Deep copy.
 
override bool Equals (object obj, EqualityIntent equalityIntent)
 Method which checks for equal objects.
 
void GetGlobalTransformationParameters (out Quaternion globalRotationMatrix, out Vector3D globalOriginPos)
 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)\).
 
override int GetHashCode ()
 Just override.
 
List<(IProvidesPositioningReferences referenceProvider, string key)> GetReferenceHierarchy ()
 Gets the complete reference hierarchy of this. The global CS (null, "") will always be element 0 in the return list.
 
CartesianCoordinateSystem GetRotatedAndTranslatedCoordinateSystem (Vector3D offset, Quaternion rotation)
 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.
 
void GetRotationAsSphericalAnglesOfZAxis (out double theta, out double phi)
 Gets the orientation of this by calculating the sphere angles theta and phi for the z axis.
 
void OnCoordinateSystemChanged ()
 Event throwing method.
 
void SetPositioningReference (IProvidesPositioningReferences referenceProvider, string key)
 Method to set the PositioningReferenceProvider and the key for the coordinate system that serves as positioning reference.
 
override string ToString ()
 method to generate a string description of the object
 
Vector3D TransformInternalPosition2PositionInReferenceCS (Vector3D internalPos)
 Transforms a given position in this CS to the reference CS.
 
Vector3D TransformPositionInReferenceCS2InternalPosition (Vector3D externalPos)
 Transforms a given position from the reference coordinate system to this CS.
 

Static Public Member Functions

static CartesianCoordinateSystem GetCSFromAxisRotationsSequence (Position origin, AxisRotationSequence sequence)
 Constructs a new Cartesian coordinate system via axis rotation sequence.
 
static CartesianCoordinateSystem GetCSFromCartesianAnglesOfZAxis (Position origin, double zeta, double alpha, double beta, bool inclinationFirst)
 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.
 
static CartesianCoordinateSystem GetCSFromDirectionAnglesOfZAxis (Position origin, double zeta, double rho, double sigma, double tau, bool inclinationFirst)
 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.
 
static CartesianCoordinateSystem GetCSFromDirectionOfZAxis (Position origin, double zeta, Vector3D directionOfZAxis, bool inclinationFirst)
 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.
 
static CartesianCoordinateSystem GetCSFromEulerAngles (Position origin, double eulerPsi, double eulerTheta, double eulerPhi)
 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:
 
static CartesianCoordinateSystem GetCSFromOrientationDefinition (Position origin, OrientationDefinitionBase orientationDefinition)
 Constructs a new Cartesian coordinate system via any IOrientationDefinition.
 
static CartesianCoordinateSystem GetCSFromSphericalAnglesOfZAxis (Position origin, double zeta, double zPhi, double zTheta, bool inclinationFirst)
 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.
 
static void GetTransformationParametersToCommonReference (CartesianCoordinateSystem cs1, CartesianCoordinateSystem cs2, out(Quaternion globalRotationMatrix, Vector3D globalOriginPos) trafoFor1, out(Quaternion globalRotationMatrix, Vector3D globalOriginPos) trafoFor2)
 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.
 
static bool operator!= (CartesianCoordinateSystem cs1, CartesianCoordinateSystem cs2)
 Overloaded inequality operator.
 
static bool operator== (CartesianCoordinateSystem cs1, CartesianCoordinateSystem cs2)
 Overloaded equality operator.
 

Properties

CoordinateSystemBaseVectors Axes [get, set]
 Gets or sets the axes or base vectors of the coordinate system.
 
List< object > GetAllCoordinateSystemChangedEventTargets [get]
 Auxiliary method for finding all targets for the invocation of this element's CoordinateSystemChanged event.
 
CartesianCoordinateSystem GetPositioningReference [get]
 Property to get the coordinate system that serves as reference for this object.
 
bool IsDefinedAbsolutely [get]
 Are the origin's position and the axes directions defined absolutely?
 
bool IsUndefined [get]
 Gets whether the coordinate system is undefined.
 
Position Origin [get, set]
 Gets or sets the origin of the coordinate system.
 
string PositioningReferenceKey [get]
 Get the key of the reference coordinate system for this.
 
IProvidesPositioningReferences PositioningReferenceProvider [get]
 Get the object that provides the reference coordinate system for this.
 

Events

EventHandler CoordinateSystemChanged
 Event that is thrown if the Coordinate System is changed.
 

Detailed Description

This class is subject to change. Programs using this class may require changes with a new version of VirtualLab.
Class for right-handed Cartesian coordinate systems.

Constructor & Destructor Documentation

◆ CartesianCoordinateSystem() [1/9]

CartesianCoordinateSystem ( IProvidesPositioningReferences  positioningReferenceProvider,
string  positioningReferenceKey 
)

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.

Parameters
positioningReferenceProviderObject which provides the coordinate system that serves as reference for this position.
positioningReferenceKeyKey for the coordinate system (contained by PositioningReferenceProvider) which shall serve as reference for this position.
Exceptions
PositionigReferenceKeyUnknownException

◆ CartesianCoordinateSystem() [2/9]

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.

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

◆ CartesianCoordinateSystem() [3/9]

Copy constructor.

Parameters
csCoordinate system to be copied.

◆ CartesianCoordinateSystem() [4/9]

CartesianCoordinateSystem ( Position  origin,
Quaternion  quaternionOfBase 
)

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

Parameters
originPosition of the origin.
quaternionOfBaseQuaternion that describes the Cartesian base.

◆ CartesianCoordinateSystem() [5/9]

Constructor that uses a position for the origin and an orientation of the base vectors.

Parameters
originPosition of the origin.
orientationOrientation definition to create the new base vectors from.

◆ CartesianCoordinateSystem() [6/9]

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

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.

Parameters
originPosition of the origin.
axis1First base vector (meaning is set by planeIndex).
axis2Second base vector (meaning is set by planeIndex).
planeSets the meaning of axis1 and axis2 by defining which plane is spanned by the given axes.

◆ CartesianCoordinateSystem() [7/9]

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

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.

Parameters
originPosition of the origin.
xAxisDirection cosine of the x-axis.
yAxisDirection cosine of the y-axis.
zAxisDirection cosine of the z-axis.

◆ CartesianCoordinateSystem() [8/9]

Constructor that uses a Position and a SystemBaseVectors.

Parameters
originPosition of origin
axesDirections of the axes

◆ CartesianCoordinateSystem() [9/9]

CartesianCoordinateSystem ( SerializationInfo  info,
StreamingContext  context 
)

Deserialization constructor used for manual serialization.

Parameters
infothe info object used for deserialization
contextthe streaming context

Member Function Documentation

◆ AxisAsPositionedLine()

PositionedLine AxisAsPositionedLine ( AxisDirection  chosenAxis)

Extracts one axis as positioned line.

Parameters
chosenAxisAxis to extract
Returns
Positioned line with the direction of the given axis and the position of this coordinate system.

◆ Clone()

override object Clone ( )

Deep copy.

Returns
Copy of this

◆ Equals()

override bool Equals ( object  obj,
EqualityIntent  equalityIntent 
)

Method which checks for equal objects.

Parameters
objObject to compare with this.
equalityIntentDefines what kind of equality you want to check when comparing two objects, for example all values or physical equality.
Returns
true if obj and this are equal.

◆ GetCSFromAxisRotationsSequence()

static CartesianCoordinateSystem GetCSFromAxisRotationsSequence ( Position  origin,
AxisRotationSequence  sequence 
)
static

Constructs a new Cartesian coordinate system via axis rotation sequence.

Parameters
originOrigin of coordinate system in reference coordinates.
sequenceAxisRotationSequence that determines how to get the new coordinate system starting from its reference system.
Returns
New Cartesian coordinate system.

◆ GetCSFromCartesianAnglesOfZAxis()

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

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.

Parameters
originOrigin of coordinate system in reference coordinates.
zetaAngle (radian) of rotation about z-axis by using the right-hand-rule.
alphaAngle between the z-axis and the projection of the z-axis onto the x-z-plane
betaAngle between the z-axis and the projection of the z-axis onto the y-z-plane
inclinationFirstFlag to signal if z-axis is inclined first (true) or after rotation of z-axis (false).
Returns
New Cartesian coordinate system.

◆ GetCSFromDirectionAnglesOfZAxis()

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

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.

Parameters
originOrigin of coordinate system in reference coordinates.
zetaAngle (in radian) of rotation about z-axis by using the right-hand-rule.
rhoDirection cosine angle alpha in radian: angle of new z-axis with positive x-axis.
sigmaDirection cosine beta in radian: angle of new z-axis with positive y-axis.
tauDirection cosine beta in radian: angle of new z-axis with positive z-axis.
inclinationFirstFlag to signal if z-axis is inclined first (true) or after rotation of z-axis (false).
Returns
New Cartesian coordinate system.

◆ GetCSFromDirectionOfZAxis()

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

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.

Parameters
originOrigin of coordinate system in reference coordinates.
zetaAngle (radian) of rotation about z-axis by using the right-hand-rule.
directionOfZAxisDirection vector of new z-axis
inclinationFirstFlag to signal if z-axis is inclined first (true) or after rotation of z-axis (false).
Returns
New Cartesian coordinate system.

◆ GetCSFromEulerAngles()

static CartesianCoordinateSystem GetCSFromEulerAngles ( Position  origin,
double  eulerPsi,
double  eulerTheta,
double  eulerPhi 
)
static

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.
Parameters
originOrigin of coordinate system in reference coordinates.
eulerPsiEuler angle Psi (about original z-axis).
eulerThetaEuler angle Theta (about new x'-axis).
eulerPhiEuler angle Phi (about the new z'-axis).
Returns
New Cartesian coordinate system.

◆ GetCSFromOrientationDefinition()

static CartesianCoordinateSystem GetCSFromOrientationDefinition ( Position  origin,
OrientationDefinitionBase  orientationDefinition 
)
static

Constructs a new Cartesian coordinate system via any IOrientationDefinition.

Parameters
originOrigin of coordinate system in reference coordinates.
orientationDefinitionIOrientationDefinition that determines how to get the new coordinate system starting from its reference system.
Returns
New Cartesian coordinate system.

◆ GetCSFromSphericalAnglesOfZAxis()

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

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.

Parameters
originOrigin of coordinate system in reference coordinates.
zetaAngle (radian) of rotation about z-axis by using the right-hand-rule.
zPhiSpherical 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°
zThetaSpherical angle theta in radian for inclination of z-axis.
inclinationFirstFlag to signal if z-axis is inclined first (true) or after rotation about z-axis (false).
Returns
New Cartesian coordinate system, created from the given spherical angles.

◆ GetGlobalTransformationParameters()

void GetGlobalTransformationParameters ( out Quaternion  globalRotationMatrix,
out Vector3D  globalOriginPos 
)

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)\).

Parameters
globalRotationMatrixGlobal rotation matrix \(R\).
globalOriginPosOrigin \(o\) of this coordinate system in global (absolute) coordinates.

◆ GetHashCode()

override int GetHashCode ( )

Just override.

Returns

◆ GetReferenceHierarchy()

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

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

Returns
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()

CartesianCoordinateSystem GetRotatedAndTranslatedCoordinateSystem ( Vector3D  offset,
Quaternion  rotation 
)

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.

Parameters
offsetTranslation distance, defined in the external CS
rotationQuaternion describing the rotation.
Returns
The transformed coordinate system.

◆ GetRotationAsSphericalAnglesOfZAxis()

void GetRotationAsSphericalAnglesOfZAxis ( out double  theta,
out double  phi 
)

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

Parameters
thetaSphere angle theta, i.e. the inclination of the z axis to the z axis of the reference CS.
phiSphere angle phi, i.e. the azimuth angle of the z axis to the x axis of the reference CS

◆ GetTransformationParametersToCommonReference()

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

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.

Parameters
cs1Coordinate system 1 to calculate transformation parameters for.
cs2Coordinate system 2 to calculate transformation parameters for.
trafoFor1The transformation parameters for transforming from the first cs to the common reference cs with the second cs.
trafoFor2The transformation parameters for transforming from the second cs to the common reference cs with the first cs.

◆ operator!=()

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

Overloaded inequality operator.

Parameters
cs1First CartesianCoordinateSystem to compare
cs2Second CartesianCoordinateSystem to compare
Returns
Are both CartesianCoordinateSystem unequal?

◆ operator==()

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

Overloaded equality operator.

Parameters
cs1First CartesianCoordinateSystem to compare
cs2Second CartesianCoordinateSystem to compare
Returns
Are both CartesianCoordinateSystem equal?

◆ SetPositioningReference()

void SetPositioningReference ( IProvidesPositioningReferences  referenceProvider,
string  key 
)

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

Parameters
referenceProviderObject which provides the coordinate system that serves as reference for this position.
keyKey for the coordinate system (contained by PositioningReferenceProvider) which shall serve as reference for this position

◆ ToString()

override string ToString ( )

method to generate a string description of the object

Returns
the string description

◆ TransformInternalPosition2PositionInReferenceCS()

Vector3D TransformInternalPosition2PositionInReferenceCS ( Vector3D  internalPos)

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

Parameters
internalPosPosition to transform
Returns
Transformed position in reference CS

◆ TransformPositionInReferenceCS2InternalPosition()

Vector3D TransformPositionInReferenceCS2InternalPosition ( Vector3D  externalPos)

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

Parameters
externalPosPosition in the reference CS to transform
Returns
Transformed internal position

Property Documentation

◆ IsUndefined

bool IsUndefined
get

Gets whether the coordinate system is undefined.

Returns
true iff the Origin member is undefined.