Reference frames

[chris]

I'm currently developing a new feature for Celestia that will give SSC creators a lot more flexibility in placing and orienting objects. At the moment, you're very restricted: the reference frame of an object that orbits about a star is the J2000 ecliptic. For a planet, it's the mean equator of the object that it orbits, although in 1.5.0 you can use OrbitReferencePlane "ecliptic" to override this. Still, even 1.5.0 gives you just two choices, and the orientation of a body must be specified in the same reference frame as the orbit.

Here are a few situations in which you may want more choices:

- You may be using a tool that generates heliocentric cartesian coordinates, but uses the a coordinate system based on the J2000 Earth mean equator and equinox rather than the ecliptic. This is very common (as Selden recently discovered). It's not too hard to write a small script to rotation the coordinates to an ecliptic based system, but by specifying the appropriate reference frame in an ssc file, you don't have to.

- You want to place an object on the surface of a planet without having to do any tricky adjustment of orientation. To do this, you can just define a reference frame where the z-axis (or x-axis or y-axis--it's your choice) points up and the y axis points north. Then just place your model at the appropriate point on the surface and it will automatically be in the correct orientation (assuming that z is up in your modeler.)

- To extend the previous example . . . Suppose that you want to have a rover that moves across the surface of a planet. There is currently no good way to do this. Reference frames make it straightforward: define a reference frame as described above, with z pointing up from the center of the planet to the center of the object. Then assign the object a sampled orbit with coordinates on the surface of the planet. It's still slightly inconvenient because you'd rather use long/lat instead of cartesian coordinates in an xyz file, but otherwise it will work nicely.

- You can add a rotation to the object on the rover. It could be a uniform rotation (silly for a rover), or a SampledOrientation that would make the rover turn as it moved across the surface of the planet.

- You can use a reference frame to change the precession axis of an object with a precessing rotation.

- A natural way to describe the attitude of a spacecraft in low orbit around a planet is in a reference frame where one axies points toward the planet, and another axis points along the velocity vector. For example: http://liftoff.msfc.nasa.gov/academy/ro ... /lvlh.html

- You can define a reference frame in which a non-rotating object will always face some other object. For this frame, you'd define one axis of the frame to point from the observer object to the target object. Such a frame would be useful in ssc files, or in a script where you wanted to place the camera at a point where it will always see the sun-facing side of a planet.

I'm reluctant to be doing any new feature work in 1.5.0, but I don't want to introduce the new OrbitBarycenter and OrbitReferencePlane SSC fields only have them made immediately obsolete by reference frames in 1.5.1. I am trying to limit the scope of this new feature somewhat, so the full flexibility of reference frames may not be immediately available in 1.5.0. Later today, I'll post some sample frame definitions for ssc files.

--Chris

[Paolo]

I think that now Celestia is not very far from key frame animation.

Perhaps you've already designed the followng but it would be nice if in a future it will be possible to define something like

CustomFrame
{
Reference "... Another frame of referece (eg. probe, rover)..."
Displacement [X Y Z]
Orientation [X Y Z W]
}


That should be the base for the animation through quaternions of robotical arms, antennas and solar panels related to an object like a rover or a probe that aready has its own xyzq path.

Kind regards

[chris]

I think that now Celestia is not very far from key frame animation.

Perhaps you've already designed the followng but it would be nice if in a future it will be possible to define something like

CustomFrame
{
Reference "... Another frame of referece (eg. probe, rover)..."
Displacement [X Y Z]
Orientation [X Y Z W]
}


That should be the base for the animation through quaternions of robotical arms, antennas and solar panels related to an object like a rover or a probe that aready has its own xyzq path.

Kind regards

You will be able to do animations in a way sort of like what you've described, but having to create separate objects for each component of an articulated model is not very efficieint. We need to come up with some other method involving manipulating submeshes of a single object.

--Chris

[Paolo]

I've seen that CVS source code was updated. Is it possible to have some examples of the new data definitions using reference frames?

Kind regards

[selden]

http://www.lepp.cornell.edu/~seb/celest ... tml#5.10.2

[chris]

Here's a sample ssc body definition that will place a sphere about 1500km above the surface of the Earth:

Code: Select all

"BodyFixedTest" "Sol/Earth"
{
    Radius 400
    Texture "callisto.*"

    # 8000 km from center of Earth
    FixedPosition [ 8000 0 0 ]

    OrbitFrame {
        BodyFixed {
            Center "Sol/Earth"
        }
    }
}


Even though the position of this object is fixed within its reference frame, the frame is a body-fixed frame that rotates with the Earth. To an observer on the surface of the Earth, the object does not appear to move; an observer in space will see the object in a synchronous orbit around the Earth. My example doesn't demonstrate anything that you can't do with the Celestia 1.4.1--it's meant solely as a simple illustration of the general ssc syntax for frames.

You can set the frame for the body orientation separately. In the example below, we'll use the same frame as for the orbit:

Code: Select all

    BodyFrame {
        BodyFixed {
            Center "Sol/Earth"
        }
    }

    FixedRotation {
    }


The above example makes the rotation of the object fixed in the Earth body-fixed reference frame--it acts like a synchronous rotator.

Hopefully, this gives you some idea of how reference frames will work. I'll post some examples that do much more interesting things this weekend.

--Chris

[chris]

Edited to change the units from AU to km

Here's another reference frame example. This one uses the new two-vector reference frame to place an object at the Earth's leading triangular Lagrange point.

Code: Select all

"L4" "Sol/Earth"
{
    Radius 4000
    Color [ 1 0 0 ]

    OrbitFrame {
         TwoVector {
            Center "Sol/Earth"
            Primary {
                Type "RelativePosition"
                Axis "x"
                Observer "Sol/Earth"
                Target "Sol"
            }
            Secondary {
                Type "RelativeVelocity"
                Axis "y"
                Observer "Sol/Earth"
                Target "Sol"
            }
        }
    }

    # position at [ 0.5 0.866 0 ] AU
    FixedPosition [ 75000000 130000000 0 ]
}


Some explanation is required, though hopefully the SSC definition is at least somewhat self explanatory.

A two-vector reference frame defines a coordinate system based on two vectors. At the moment, Celestia supports two different vector types for two-vector frames: relative position and relative velocity. The primary points in the direction of the primary vector. The secondary axis point is at a right angle to the primary axis. It will not generally point in exactly the same direction as the secondary vector; rather, it points in the direction of the component of the secondary vector that is orthogonal to the primary axis. Finally, the remaining axis points in a direction orthogonal to both the primary and secondary axes and defines a right-handed coordinate system.

It will be helpful to show a diagram of the coordinate system described by my example frame, and I'll be preparing one soon. The x-axis in the example points from the Earth to the Sun. The y-axis is the Earth's velocity relative to the Sun. This is a very frame for specifying Lagrange points. All of the Lagrange points can be defined using the reference frame in the example and a different FixedPosition. The collinear Lagrange points L1, L2, and L3 will have zero y and z coordinates. These points aren't stable; however, there are stable orbits about the collinear Lagrange points, so for a realisitic scenario the orbit shouldn't just be a FixedPosition. In my L4 example, the FixedPosition is the vertex of an equiliateral triangle (in kilometers) in the reference frame. The L5 point would be at [ 75000000 -130000000 0 ].

If used as the reference frame for the body (rather than the orbit), the example frame can be used to keep an object constant oriented toward the Sun. I invite anyone who's building from CVS to try it (hint: use BodyFrame instead of OrbitFrame.) If no one does it first, I'll post the example ssc definition tomorrow.

--Chris

[chris]

Edited to change the units from AU to km

More examples: the L1 and L2 Lagrange points, which each lie approximately 1.5 million km (0.01 au) from the Earth:

Code: Select all

"L1" "Sol/Earth"
{
    Radius 4000
    Color [ 1 0 0 ]

    OrbitFrame {
         TwoVector {
            Center "Sol/Earth"
            Primary {
                Type "RelativePosition"
                Axis "x"
                Observer "Sol/Earth"
                Target "Sol"
            }
            Secondary {
                Type "RelativeVelocity"
                Axis "y"
                Observer "Sol/Earth"
                Target "Sol"
            }
        }
    }

    FixedPosition [ 1500000 0 0 ]
}

"L2" "Sol/Earth"
{
    Radius 4000
    Color [ 1 0 0 ]

    OrbitFrame {
         TwoVector {
            Center "Sol/Earth"
            Primary {
                Type "RelativePosition"
                Axis "x"
                Observer "Sol/Earth"
                Target "Sol"
            }
            Secondary {
                Type "RelativeVelocity"
                Axis "y"
                Observer "Sol/Earth"
                Target "Sol"
            }
        }
    }

    FixedPosition [ -1500000 0 0 ]
}


Soon, named frames will be implemented, which will remove the need to redefine the Earth-Sun frame every time you want to use it. In the above example, the only different between the two objects is the sign of the x coordinate for the FixedPosition 'orbit'.

--Chris

[chris]

Yet another reference frame example . . .

Here I'm defining a local frame for the orientation of the shuttle. The -z axis points from the shuttle toward the Earth and the y axis points in direction of the shuttle's velocity. The shuttle is assigned a fixed orientation within the reference frame, but since the reference frame itself is rotating, the overall effect is to orient the shuttle so that it always faces the Earth:



The ssc is slightly trickier than I'd like it to be. Since the BodyFrame references the shuttle itself, I first need to define the shuttle, and then have a second modifying definition that sets the body frame. I chose -z as the Earth-pointing axis because of the way that the Atlantis mesh was modeled.

Code: Select all

"Atlantis LVLH" "Sol/Earth"
{
    Mesh "atlantis.cmod"
    Radius 0.032

    EllipticalOrbit
    {
   Epoch         2452562.41666667
   Period         0.06415835
   SemiMajorAxis      6769.712
   Eccentricity      0.0019561
   Inclination      51.6355
   AscendingNode      171.6144
   ArgOfPericenter      2.8715
    }

    MeshCenter      [ 0 0.31 -0.08 ]

    Albedo 0.50

    FixedRotation
    {
    }
}


Modify "Atlantis LVLH" "Sol/Earth"
{
    BodyFrame {
        TwoVector {
            Center "Sol/Earth"
            Primary {
                Type "RelativePosition"
                Axis "-z"
                Observer "Sol/Earth/Atlantis LVLH"
                Target "Sol/Earth"
            }
            Secondary {
                Type "RelativeVelocity"
                Axis "y"
                Observer "Sol/Earth/Atlantis LVLH"
                Target "Sol/Earth"
            }
        }
    }
}


And to make things slightly more interesting, I can replace the FixedRotation with a UniformRotation like this:

Code: Select all

UniformRotation
{
    Period 0.03
}


This causes the shuttle to rotate about its z axis--that's the default if there's no inclination or ascending node--as it orbits the Earth. A more realistic shuttle mission would use a SampledOrientation to orient the shuttle.

Here's a page with some diagrams and an explanation of local attitudes: http://liftoff.msfc.nasa.gov/academy/ro ... /lvlh.html

--Chris

[chris]

The EquatorJ2000 frame has axes defined by the Earth's mean equatorial plane and equinox at epoch J2000. Although not the default in Celestia, the this is the standard coordinate system for a lot of ephemerides. It's the frame that JPL's HORIZONS system uses by default, though it's very easy to make HORIZONS use the ecliptical system that Celestia uses.

One application of the EquatorJ2000 frame in Celestia is for using .xyz files with coordinates in the ICRF/J2000.0 equator reference frame. It's always been possible to write a program to transform the coordinates, but now that's no longer necessary. Selden mentioned a few days ago was using an orbit tool called JAQAR (http://www.jaqar.com/swingby.html) that generated heliocentric coordinates in J2000 equatorial frame. Here's how you'd use reference frames to import that trajectory into Celestia:

Code: Select all

"Some Spacecraft" "Sol"
{
    Mesh "spacecraft.cmod"
    Radius 0.002

    SampledOrbit "jaqar.xyz"
    OrbitFrame {
        EquatorJ2000 { Center "Sol" }
    }
}


The EclipticJ2000 frame is the default frame assumed by Celestia for objects that orbit a star. Thus, for a Sun-orbiting object, setting the orbit frame to EclipticJ2000 { Center "Sol" } is identical to omitting the orbit frame completely. For an object such as a moon that does not orbit a star, the default reference frame is the mean equatorial plane of the body. But, you can override this default with another frame such as EclipticJ2000, EquatorJ2000, or something else depending upon the plane that your orbital elements are referred to.

The application of reference frames that I've described in this post is mainly a convenience feature: instead of writing small scripts to transform trajectories and orbital elements into Celestia's default reference frames you can just let Celestia do the work for you.

--Chris

[chris]

I should make it clear that the OrbitReferencePlane and OrbitBarycenter are completely replaced by reference frames. They were to be new 1.5.0 ssc fields, but reference frames are a much more general mechanism that can do everything that OrbitReferencePlane/OrbitBarycenter could and a lot more.

--Chris

[Chuft-Captain]

The EquatorJ2000 frame has axes defined by the Earth's mean equatorial plane and equinox at epoch J2000. Although not the default in Celestia, the this is the standard coordinate system for a lot of ephemerides. It's the frame that JPL's HORIZONS system uses by default, though it's very easy to make HORIZONS use the ecliptical system that Celestia uses.

One application of the EquatorJ2000 frame in Celestia is for using .xyz files with coordinates in the ICRF/J2000.0 equator reference frame. It's always been possible to write a program to transform the coordinates, but now that's no longer necessary. Selden mentioned a few days ago was using an orbit tool called JAQAR (http://www.jaqar.com/swingby.html) that generated heliocentric coordinates in J2000 equatorial frame. Here's how you'd use reference frames to import that trajectory into Celestia:

Code: Select all

"Some Spacecraft" "Sol"
{
    Mesh "spacecraft.cmod"
    Radius 0.002

    SampledOrbit "jaqar.xyz"
    OrbitFrame {
        EquatorJ2000 { Center "Sol" }
    }
}


The EclipticJ2000 frame is the default frame assumed by Celestia for objects that orbit a star. Thus, for a Sun-orbiting object, setting the orbit frame to EclipticJ2000 { Center "Sol" } is identical to omitting the orbit frame completely. For an object such as a moon that does not orbit a star, the default reference frame is the mean equatorial plane of the body. But, you can override this default with another frame such as EclipticJ2000, EquatorJ2000, or something else depending upon the plane that your orbital elements are referred to.

The application of reference frames that I've described in this post is mainly a convenience feature: instead of writing small scripts to transform trajectories and orbital elements into Celestia's default reference frames you can just let Celestia do the work for you.

--Chris

Chris,

Would this also be the appropriate reference frame for the Earth-Moon lagrange points?

[chris]

Would this also be the appropriate reference frame for the Earth-Moon lagrange points?

No. You would use something like the frame for the Earth/Sun Lagrange points. For example:

Code: Select all

"Moon L4" "Sol/Earth"
{
    Radius 4000
    Color [ 1 0 0 ]

    OrbitFrame {
         TwoVector {
            Center "Sol/Earth/Moon"
            Primary {
                Type "RelativePosition"
                Axis "x"
                Observer "Sol/Earth/Moon"
                Target "Sol/Earth"
            }
            Secondary {
                Type "RelativeVelocity"
                Axis "y"
                Observer "Sol/Earth/Moon"
                Target "Sol/Earth"
            }
        }
    }

    FixedPosition [ 192000 332600 0 ]
}


I just took the Earth/Sun Lagrange point example and replaced Sol/Earth with Sol/Earth/Moon and Sol with Sol/Earth. And of course, I modified the fixed position so that x = earth-moon-distance/2 and y = earth-moon-distance*sqrt(3)/2. I used 384000 km as the Earth-Moon distance. This is an approximation which assumes that the Moon is in a perfectly circular orbit about the Earth. I need to learn a bit more about where the Lagrange points lie on a slightly elliptical orbit.

--Chris

[Malenfant]

I should make it clear that the OrbitReferencePlane and OrbitBarycenter are completely replaced by reference frames. They were to be new 1.5.0 ssc fields, but reference frames are a much more general mechanism that can do everything that OrbitReferencePlane/OrbitBarycenter could and a lot more.

--Chris

Wait, what?

Is this going to mean that all the binaries etc that used OrbitBarycenter are going to be screwed up now? So far I've not understood a word of how these reference planes are implemented...

I mean, here's a simple binary as it is now - what's this going to look like with the reference frame code?

Code: Select all

#######################
Barycenter "Binary"
{
RA        180
Dec       0
Distance  100
}
#######################


400000 "Star1"
{
OrbitBarycenter "Binary"
SpectralType "F8IV"
AbsMag  3.10
Radius 1274164.95

   EllipticalOrbit {               
      Period          0.01095140315
      SemiMajorAxis   0.02666666667
      ArgOfPericenter 0
   }
}

"Star2"
{
OrbitBarycenter "Binary"
SpectralType "G2V"
AbsMag  4.86 # Luminosity = 1 Sol
Radius 696265

   EllipticalOrbit {               
      Period          0.01095140315
      SemiMajorAxis   0.03333333333 
      ArgOfPericenter 180
   }
}


[chris]

I should make it clear that the OrbitReferencePlane and OrbitBarycenter are completely replaced by reference frames. They were to be new 1.5.0 ssc fields, but reference frames are a much more general mechanism that can do everything that OrbitReferencePlane/OrbitBarycenter could and a lot more.

--Chris

Wait, what?

Is this going to mean that all the binaries etc that used OrbitBarycenter are going to be screwed up now? So far I've not understood a word of how these reference planes are implemented...

No, the change doesn't affect stars. I should have made it clear that I was only talking about SSC objects. I don't want to break everyone's star add-ons.

Eventually reference frames will be introduced for stc files too. I don't think that they'll be nearly as useful there; I'll mainly do it for the sake of consistency. And even when reference frames do appear in stc files, I'll make sure that OrbitBarycenter still works.

--Chris

[chris]

In an effort to make reference frames more comprehensible, I've made an image illustrating this frame used for the Earth Lagrange points:

Code: Select all

    OrbitFrame {
         TwoVector {
            Center "Sol/Earth"
            Primary {
                Axis "x"
                RelativePosition {
                    Observer "Sol/Earth"
                    Target "Sol"
                }
            }
            Secondary {
                Axis "y"
                RelativeVelocity {
                    Observer "Sol/Earth"
                    Target "Sol"
                }
            }
        }
    }


--Chris

[Malenfant]

Oh, phew .

[Paolo]

It seems to me a bit complex. Perhaps the current syntax should be improved.

Can I use a Location as reference Frame?
How can I use a reference frame for xyz paths.

Still focused on Spirit & Opportunity...

Kind regards

[chris]

:? It seems to me a bit complex. Perhaps the current syntax should be improved.

I'll do what I can to make it as easy to use as possible, but I don't think the syntax is the big problem. Lack of documentation is probably the real issue. That, and the fact that specifying coordinate systems in space when everything is moving and rotating is *hard*. If you do have suggestions on how the syntax could be improved, please share them.

Can I use a Location as reference Frame?

Not quite yet, but this probably isn't what you want for the rovers anyhow.

How can I use a reference frame for xyz paths.

Just replaced the FixedPosition orbit type with a SampledOrbit.

Still focused on Spirit & Opportunity...

You want a Mars body-fixed frame for the position. For orientation, you probably want a system where z is the local up direction, the y-axis is north, and the x-axis is east. I'll give an example of this later.

--Chris

[Cham]

With all the new commands, we seriously need some new documentation too. Or else, it will be like if no new commands have been inttroduced at all in the CVS code !