FixedRotation

Inherits Rotation

This Rotation calculates the rotation in such a way that the attached scene graph node will always be relative to some other direction or pointing at another scene graph node.

The first use-case of the FixedRotation needs exactly two of its three axes (XAxis, YAxis, ZAxis) specified with the last axis being unspecified. The axis that is missing will be calculated using a right-handed coordinate completion using the two provided axes. Each axis can be specified either by providing the Identifier of another scene graph node, or by providing a direction vector. For the general use-case of this Rotation, one of the provided axes usually is an Identifier and the other is a direction vector (see the examples below). If any of the axes is using the Identifier of another scene graph node, the Attached value must be specified and should almost always be the identifier of the scene graph node to which this Rotation belongs.

A second use-case for this Rotation is to directly specify mappings for the coordinate axes. In this use-case, two or all three axes are specified using direction vectors. The orientation of the rotated coordinate system will then be determined by the specified axes, such that the new x-axis points in the direction provided to the XAxis, for example. Note that all direction vectors are assumed to be normalized. If only two direction vectors are specified, the third direction is computed using a right-handed coordinate system completion.

Each axis has an invert option that will cause the provided axes to be considered inverted. For the direction-type of axis, this just inverts the provided values, but it is more useful for the Identifier version to construct a direction that either points towards or away from the provided scene graph node.

Lastly, each axis has an orthogonal option. If that value is specified, the provided axis is instead cross-producted with the other axis first with the resulting orthogonal vector used as the mapped axis. This is primarily useful when specifying a direction vector and wanting to ensure that the total rotation remains a valid non-skewed rotation (meaning that all three coordinate axes are orthogonal to each other) when the second axis can assume arbitrary values. Unless there is a very good reason not to, whenever an axis is specified as a direction vector, that axis’ orthogonal setting should also probably be enabled.

Members

Name

Documentation

Type

Description

Optional

Attached

This is the name of the node that this rotation is attached to, this value is only needed if any of the three axis uses the Object type. In this case, the location of the attached node is required to compute the relative direction.

String

Value of type ‘String’

Yes

XAxis

This value specifies the direction of the new X axis. If this value is not specified, it will be computed by completing a right handed coordinate system from the Y and Z axis, which must be specified instead. If this value is a string, it is interpreted as the identifier of another scenegraph node. If this value is a 3-vector, it is interpreted as a direction vector

String, or Vector3<double>

Value of type ‘String’, or Value of type ‘Vector3’

Yes

XAxisInvert

If this value is set to ‘true’, and the type is set to ‘Object’, the inverse of the pointing direction is used, causing the object to point away from the referenced object.

Boolean

Value of type ‘Boolean’

Yes

XAxisOrthogonal

This value determines whether the vector specified is used directly, or whether it is used together with another non-coordinate system completion vector to construct an orthogonal vector instead.

Boolean

Value of type ‘Boolean’

Yes

YAxis

This value specifies the direction of the new Y axis. If this value is not specified, it will be computed by completing a right handed coordinate system from the X and Z axis, which must be specified instead. If this value is a string, it is interpreted as the identifier of another scenegraph node. If this value is a 3-vector, it is interpreted as a direction vector

String, or Vector3<double>

Value of type ‘String’, or Value of type ‘Vector3’

Yes

YAxisInvert

If this value is set to ‘true’, and the type is set to ‘Object’, the inverse of the pointing direction is used, causing the object to point away from the referenced object.

Boolean

Value of type ‘Boolean’

Yes

YAxisOrthogonal

This value determines whether the vector specified is used directly, or whether it is used together with another non-coordinate system completion vector to construct an orthogonal vector instead.

Boolean

Value of type ‘Boolean’

Yes

ZAxis

This value specifies the direction of the new Z axis. If this value is not specified, it will be computed by completing a right handed coordinate system from the X and Y axis, which must be specified instead. If this value is a string, it is interpreted as the identifier of another scenegraph node. If this value is a 3-vector, it is interpreted as a direction vector

String, or Vector3<double>

Value of type ‘String’, or Value of type ‘Vector3’

Yes

ZAxisInvert

If this value is set to ‘true’, and the type is set to ‘Object’, the inverse of the pointing direction is used, causing the object to point away from the referenced object.

Boolean

Value of type ‘Boolean’

Yes

ZAxisOrthogonal

This value determines whether the vector specified is used directly, or whether it is used together with another non-coordinate system completion vector to construct an orthogonal vector instead.

Boolean

Value of type ‘Boolean’

Yes

Inherited members from Rotation

Name

Documentation

Type

Description

Optional

Type

The type of the rotation that is described in this element. The available types of rotations depend on the configuration of the application and can be written to disk on application startup into the FactoryDocumentation

String

Must name a valid Rotation type

No

TimeFrame

The time frame in which this Rotation is applied. If the in-game time is outside this range, no rotation will be applied.

Table

TimeFrame

Yes

Asset Examples

Basic

This asset creates a rotation that places coordinate axes close to a sphere with the z axis pointing towards the sphere. The coordinate axes are translated away from the sphere to make that orientation more obvious.

Making the YAxis { 0.0, 1.0, 0.0 } and actually using the orthogonal projection of that direction means that the y axis of the new coordinate system will point in the hemisphere in which the old y-axis was pointing, albeit being orthogonal to the other specified axis. That axis is pointing towards the scene graph node holding the sphere.

 1local Sphere = {
 2  Identifier = "FixedRotation_Example_Sphere",
 3  Transform = {
 4    Translation = {
 5      Type = "StaticTranslation",
 6      Position = { 2.0, 1.5, 1.0 }
 7    }
 8  },
 9  Renderable = {
10    Type = "RenderableSphericalGrid"
11  },
12  GUI = {
13    Name = "FixedRotation - Basic (Sphere)",
14    Path = "/Examples"
15  }
16}
17
18local Node = {
19  Identifier = "FixedRotation_Example",
20  Transform = {
21    Rotation = {
22      Type = "FixedRotation",
23      Attached = "FixedRotation_Example",
24      YAxis = { 0.0, 1.0, 0.0 },
25      YAxisOrthogonal = true,
26      ZAxis = "FixedRotation_Example_Sphere"
27    }
28  },
29  Renderable = {
30    Type = "RenderableCartesianAxes"
31  },
32  GUI = {
33    Name = "FixedRotation - Basic",
34    Path = "/Examples"
35  }
36}
37
38asset.onInitialize(function()
39  openspace.addSceneGraphNode(Sphere)
40  openspace.addSceneGraphNode(Node)
41end)
42
43asset.onDeinitialize(function()
44  openspace.removeSceneGraphNode(Node)
45  openspace.removeSceneGraphNode(Sphere)
46end)
Inverted Axis

This asset creates a rotation that places coordinate axes close to a sphere with the z axis pointing away from the sphere. The coordinate axes are translated away from the sphere to make that orientation more obvious.

Making the YAxis { 0.0, 1.0, 0.0 } and actually using the orthogonal projection of that direction means that the y axis of the new coordinate system will point in the hemisphere in which the old y-axis was pointing, albeit being orthogonal to the other specified axis. That axis is pointing towards the scene graph node holding the sphere.

 1local Sphere = {
 2  Identifier = "FixedRotation_Example_InvertedAxis_Sphere",
 3  Transform = {
 4    Translation = {
 5      Type = "StaticTranslation",
 6      Position = { 2.0, 1.5, 1.0 }
 7    }
 8  },
 9  Renderable = {
10    Type = "RenderableSphericalGrid"
11  },
12  GUI = {
13    Name = "FixedRotation - Inverted Axis (Sphere)",
14    Path = "/Examples"
15  }
16}
17
18local Node = {
19  Identifier = "FixedRotation_Example_InvertedAxis",
20  Transform = {
21    Rotation = {
22      Type = "FixedRotation",
23      Attached = "FixedRotation_Example_InvertedAxis",
24      YAxis = { 0.0, 1.0, 0.0 },
25      YAxisOrthogonal = true,
26      ZAxis = Sphere.Identifier,
27      ZAxisInvert = true
28    }
29  },
30  Renderable = {
31    Type = "RenderableCartesianAxes"
32  },
33  GUI = {
34    Name = "FixedRotation - Inverted Axis",
35    Path = "/Examples"
36  }
37}
38
39asset.onInitialize(function()
40  openspace.addSceneGraphNode(Sphere)
41  openspace.addSceneGraphNode(Node)
42end)
43
44asset.onDeinitialize(function()
45  openspace.removeSceneGraphNode(Node)
46  openspace.removeSceneGraphNode(Sphere)
47end)
Rotation Following One Moving Object

This asset creates a rotation that places coordinate axes orbiting close to a sphere with the z axis always pointing towards the sphere as it orbits around the sphere. The coordinate axes are translated away from the sphere to make that orientation more obvious.

Making the YAxis { 0.0, 1.0, 0.0 } and actually using the orthogonal projection of that direction means that the y axis of the new coordinate system will point in the hemisphere in which the old y-axis was pointing, albeit being orthogonal to the other specified axis. That axis is pointing towards the scene graph node holding the sphere.

 1local Sphere = {
 2  Identifier = "FixedRotation_Example_Moving_Sphere",
 3  Transform = {
 4    Translation = {
 5      Type = "KeplerTranslation",
 6      Eccentricity = 0.5,
 7      SemiMajorAxis = 0.0025,
 8      Inclination = 0.0,
 9      AscendingNode = 0.0,
10      ArgumentOfPeriapsis = 0.0,
11      MeanAnomaly = 0.0,
12      Epoch = "2000 JAN 01 12:00:00",
13      Period = 10.0
14    }
15  },
16  Renderable = {
17    Type = "RenderableSphericalGrid"
18  },
19  GUI = {
20    Name = "FixedRotation - Moving (Sphere)",
21    Path = "/Examples"
22  }
23}
24
25local Node = {
26  Identifier = "FixedRotation_Example_Moving",
27  Transform = {
28    Rotation = {
29      Type = "FixedRotation",
30      Attached = "FixedRotation_Example_Moving",
31      YAxis = { 0.0, 1.0, 0.0 },
32      YAxisOrthogonal = true,
33      ZAxis = Sphere.Identifier
34    }
35  },
36  Renderable = {
37    Type = "RenderableCartesianAxes"
38  },
39  GUI = {
40    Name = "FixedRotation - Moving",
41    Path = "/Examples"
42  }
43}
44
45asset.onInitialize(function()
46  openspace.addSceneGraphNode(Sphere)
47  openspace.addSceneGraphNode(Node)
48end)
49
50asset.onDeinitialize(function()
51  openspace.removeSceneGraphNode(Node)
52  openspace.removeSceneGraphNode(Sphere)
53end)
Rotation Following Two Moving Objects

This asset creates a rotation that places coordinate axes orbiting close to two spheres with the y axis always pointing towards the first sphere and the z axis always pointing towards the second sphere as the coordinate system moves around. The set of coordinate axes are orbiting using a KeplerTranslation that provides a configurable orbital motion. The use of the KeplerTranslation in this example is arbitrary and the FixedRotation does not depend on the use of that class. We use it in this example as we want a moving object to show that the FixedRotation will always point at the object, even as it is moving.

Note that in this example the coordinate system will be skewed as, in general, it is not guaranteed that the direction from the node to the two spheres will be an orthogonal vector.

 1local Sphere1 = {
 2  Identifier = "FixedRotation_Example_Moving_TwoObjects_Sphere1",
 3  Transform = {
 4    Translation = {
 5      Type = "StaticTranslation",
 6      Position = { 3.0, -2.0, 0.0 }
 7    }
 8  },
 9  Renderable = {
10    Type = "RenderableSphericalGrid"
11  },
12  GUI = {
13    Name = "FixedRotation - Moving Two Objects (Sphere 1)",
14    Path = "/Examples"
15  }
16}
17
18local Sphere2 = {
19  Identifier = "FixedRotation_Example_Moving_TwoObjects_Sphere2",
20  Transform = {
21    Translation = {
22      Type = "KeplerTranslation",
23      Eccentricity = 0.5,
24      SemiMajorAxis = 0.0025,
25      Inclination = 0.0,
26      AscendingNode = 0.0,
27      ArgumentOfPeriapsis = 0.0,
28      MeanAnomaly = 0.0,
29      Epoch = "2000 JAN 01 12:00:00",
30      Period = 10.0
31    }
32  },
33  Renderable = {
34    Type = "RenderableSphericalGrid"
35  },
36  GUI = {
37    Name = "FixedRotation - Moving Two Objects (Sphere 2)",
38    Path = "/Examples"
39  }
40}
41
42local Node = {
43  Identifier = "FixedRotation_Example_Moving_TwoObjects",
44  Transform = {
45    Rotation = {
46      Type = "FixedRotation",
47      Attached = "FixedRotation_Example_Moving_TwoObjects",
48      YAxis = Sphere1.Identifier,
49      YAxisOrthogonal = true,
50      ZAxis = Sphere2.Identifier
51    }
52  },
53  Renderable = {
54    Type = "RenderableCartesianAxes"
55  },
56  GUI = {
57    Name = "FixedRotation - Moving Two Objects",
58    Path = "/Examples"
59  }
60}
61
62asset.onInitialize(function()
63  openspace.addSceneGraphNode(Sphere1)
64  openspace.addSceneGraphNode(Sphere2)
65  openspace.addSceneGraphNode(Node)
66end)
67
68asset.onDeinitialize(function()
69  openspace.removeSceneGraphNode(Node)
70  openspace.removeSceneGraphNode(Sphere2)
71  openspace.removeSceneGraphNode(Sphere1)
72end)
Axis Mapping

This asset creates a rotation that shows coordinate axes in which the x and the y axes are flipped. While this could also be achieved with a ConstantRotation class, this serves as an example for more elaborate coordinate system mappings, such as converting to a coordinate system with a known coordinate axes.

 1local Node = {
 2  Identifier = "FixedRotation_Example_Mapping",
 3  Transform = {
 4    Rotation = {
 5      Type = "FixedRotation",
 6      XAxis = { 0.0, 1.0, 0.0 },
 7      YAxis = { 1.0, 0.0, 0.0 },
 8      ZAxis = { 0.0, 0.0, 1.0 }
 9    }
10  },
11  Renderable = {
12    Type = "RenderableCartesianAxes"
13  },
14  GUI = {
15    Name = "FixedRotation - Mapping",
16    Path = "/Examples"
17  }
18}
19
20asset.onInitialize(function()
21  openspace.addSceneGraphNode(Node)
22end)
23
24asset.onDeinitialize(function()
25  openspace.removeSceneGraphNode(Node)
26end)