Celestia Forums

Proposal Summary : Create a flowchart of the Celestia program

It is proposed that several people contribute to a flowchart of the Celestia program. This work can be mostly done by the B Team. That means the core developers do not need to spend time helping. The non-core developers would be the B Team which actively contributes to the flowchart and other explanations of the C++ program.

The flowchart can have several levels in a hierarchy of details. The simplest flowchart may feature a loop in simulation.cpp to update and render Celestia, as in this part of a document :

for (;;)
{
sim->update(tick);
sim->render(*renderer);
}

That is from the 3 year old documentation in http://cvs.sourceforge.net/viewcvs.py/c ... cvs-markup

This flowchart would be visible on the internet. It would be on a website that would accept new flowchart versions to be posted by the B Team members.

Conclusion
This flowchart and documentation would grow over several weeks to include many layers of details. Future developers could look at the flowchart and documentation to help them write appropriate software. The author of this proposal would benefit from the teachings of B Team members who are more knowledgeable. It is with great respect for Chris Laurel and the A Team that it is proposed that this will be no burden on them.

Thanks for the link in your post....

I was actually about to post the question : "Is there a flow chart for Celestia? I would very much like one..."

I have tried contacting Chris, and would very much like to be involved in the Celestia project as I hope to produce my own suggestions / modifications / path of developement... To date I have had no responce to any of these emails / posts..

So if anyone can throw me a bone, or some info, or anything in terms of the dev. team and what is and isn't acceptable to do I would love to hear from them....

Thanks.

Hello Scratt,

Welcome to the B Team. You said, "So if anyone can throw me a bone, or some info, or anything in terms of the dev. team and what is and isn't acceptable to do I would love to hear from them".

It is acceptable for you to modify the open source program. Your new program might not be accepted into the official programs in the central SourceForge Repository. But if your changes are worthy, they could become part of the latest Celestia code distribution. That choice is up to Chris.

Please describe your level of skill in C++. Also, are you skilled in making flowcharts from other people's programs?

Where on the internet can we post the flowcharts?

Here is the first attempt at a flowchart for the program. Please make corrections to this top level flowchart and send the new version to this thread. Also, the next step is to label each box with the C++ program name that is used. After the top level flowchart is approved by forum readers, each block will be expanded into a more detailed flowchart. The hierarchy of levels of flowcharts will gradually be created to reach a degree of detailing that is useful for developers. That goal of detailing does not need to show all functions, just the flow of information and control.

Refresh your browser to see the latest flowchart version.


Refresh your browser to see the latest flowchart version.

GlobeMaker wrote:Hello Scratt,

Welcome to the B Team. You said, "So if anyone can throw me a bone, or some info, or anything in terms of the dev. team and what is and isn't acceptable to do I would love to hear from them".

It is acceptable for you to modify the open source program. Your new program might not be accepted into the official programs in the central SourceForge Repository. But if your changes are worthy, they could become part of the latest Celestia code distribution. That choice is up to Chris.

Please describe your level of skill in C++. Also, are you skilled in making flowcharts from other people's programs?

Where on the internet can we post the flowcharts?

Thanks for the info, and the welcome.

C++. Not too shabby! I am a low level coder by choice.. Have written my own Scene Graphs and such in 6502, x86, 680xx etc. etc. And made the transition to C and C++ reluctantly many moons ago.

Never really made serious flow charts. I am one of those horrible people that holds it all in my head.. But I can certainly help with this as I am wading my way through Celestia wrapping my head around it at the moment.. Although it has to be said my platform of choice is Mac, and not PeeCee.

Let me know how I can help and I'll factor it into my work path..

Scratt said, "Let me know how I can help and I'll factor it into my work path".

You could verify the accuracy of the top level flowchart. In particular, there is a loop that gives fast frame rates that give the impression of smooth motion. Does this loop reside in render.cpp ?

But the loop must allow keyboard and mouse info, so it may loop in winmain, celestiacore and render.cpp . (For your Mac it might be called macmain.)

I want to be sure the fast loop is accurately shown at the top level. If it only covers celestiacore.cpp and render.cpp then we need to know that.

celestiacore has this line : sim->update(dt);

render.cpp has these lines :
// Render all the bodies in the render list.
for (i = nEntries - 1; i >= 0; i--)
{...
glMatrixMode(GL_MODELVIEW);


Also simulation.cpp has

// Tick the simulation by dt seconds
void Simulation::update(double dt)
{
realTime += dt;
static void renderSphere_DOT3_VP(const RenderInfo& ri,
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE);

I am reading the source code, too. Thanks for the help.

Rev. 4, December 28, 2005

The Top Level Flowchart box "UPDATE" is expanded here.

(Refresh your screen to see the lastest document.).

No loops are being shown yet in this UPDATE explanation.
This forum post today only expands the nested UPDATE software.
This is to make clearer the sequence of events in the software.
Since there is not yet any branching in this explanation,
a flowchart will not yet be drawn for the UPDATE box.
Only text will be used to describe the sequence of events
as C++ classes call into a hierarchy of sub-classes and functions.


UPDATE sequence of events


1 WinMain has loop using appCore, an instance of CelestiaCore
2 appCore->tick() is in the WinMain loop:
while (msg.message != WM_QUIT)
3 CelestiaCore::tick() increments currentTime += dt;

4 CelestiaCore tick() then calls Simulation ... sim->update(dt);

5 Simulation's update(note 2) increments realTime += dt;

6 Simulation calls Observer's update(note 2),
(*iter)->update(dt, timeScale);
That update has this code:
void Observer::update(double dt, double timeScale)
{
realTime += dt;
simTime += (dt / 86400.0) * timeScale;


Observer has code to provide position to Universe class.
Code clues follow:
UniversalCoord Observer::getPosition() const
Point3d Observer::getRelativePosition(const Point3d& p) const
{...
UniversalCoord position = getPosition();
double dx = (double) (position.x - x);
double dy = (double) (position.y - y);
double dz = (double) (position.z - z);
return Point3d(dx / LY, dy / LY, dz / LY);
}

The Point3d has vector operations defined in vecmath.h

Observer's update has this:
UniversalCoord origin = centerObj.getPosition(simTime);

and Observer has : Vec3d toUniversal(
... astro::CoordinateSystem frame)
{switch (frame)
{
case astro::ObserverLocal:
{
Quatf q = observer.getOrientation();
Quatd qd(q.w, q.x, q.y, q.z);
return v * qd.toMatrix3();
}

7 Simulation calls Universe
closestSolarSystem = universe->getNearestSolarSystem(activeObserver->getPosition());

8 Universe does not use Observer class, uses only
"position vector v" from the Observer class algorithm

Universe class has this :
SolarSystem* Universe::getNearestSolarSystem(const UniversalCoord& position) const
{
Point3f pos = (Point3f) position;
Point3f lyPos(pos.x * 1.0e-6f, pos.y * 1.0e-6f, pos.z * 1.0e-6f);
ClosestStarFinder closestFinder(1.0f);
starCatalog->findCloseStars(closestFinder, lyPos, 1.0f);
return getSolarSystem(closestFinder.closestStar);
}

9 Universe calls solarsys.cpp which loads the solarsys.ssc file

10 SolarSystem loads the solarsys.ssc file which has:
CustomOrbit "vsop87-mercury"
EllipticalOrbit {
Period 0.2408 ...


11 SolarSystem calls Body class and Orbit:
static Body* CreatePlanet(PlanetarySystem* system,
... Orbit* orbit = CreateOrbit(system, planetData, path, usePlanetUnits);
That was in solarsys.cpp


12 Body calls orbit.cpp or customorbit.cpp which call orbit.h:

orbit.h has code :
class OrbitSampleProc
{
public:
virtual void sample(double t, const Point3d&) = 0;
};

orbit.cpp or customorbit.cpp :
Orbit* Body::getOrbit() const
{
return orbit;
}

or a CustomOrbit has code like:
return CreateVSOP87Orbit(name);

13 Orbit calls sample() which is in samporbit.cpp :
void EllipticalOrbit::sample(double start, double t, int nSamples,
OrbitSampleProc& proc) const


14 samporbit.cpp has code defining sample : :
void SampledOrbit::sample(double start, double t, int nSamples,
OrbitSampleProc& proc) const
That has math that samples the orbit positions.


15 orbit.h defines OrbitSampleProc which used Point3d for
various orbits like SynchronousOrbit
Point3d positionAtTime(double jd) const;
OrbitSampleProc is used in these classes in orbit.h :
EllipticalOrbit, SynchronousOrbit, CachingOrbit, and MixedOrbit


16 The orbit points that were sampled are believed to be
used to move the planet in front of the observer. Usually, CachingOrbit
is used, but sometimes that is invalidated and another orbit needs
to be calculated.

17 customorbit.cpp has
if (name == "mercury")
return new MixedOrbit(new MercuryOrbit(), yearToJD(-4000), yearToJD(4000), astro::SolarMass);

customorbit.cpp calls CreateVSOP87Orbit from vsop87.cpp

18 The orbit of Mercury is defined in vsop87.cpp :
Orbit* CreateVSOP87Orbit(const string& name)
{
if (name == "vsop87-mercury")
{
Orbit* o = new VSOP87Orbit(mercury_L, 6,
mercury_B, 6,
mercury_R, 5,
0.2408 * 365.25,
60000000.0);
return new MixedOrbit(o, yearToJD(-4000), yearToJD(4000),
astro::SolarMass);

________________________________________________________

Notes :

1
The classes are named like the C++ programs :
winmain.cpp has WinMain class
celestiacore.cpp has CelestiaCore class
simulation.cpp has Simulation class
observer.cpp has Observer class
universe.cpp has Universe class
body.cpp has Body class
orbit.cpp has Orbit class
etc...

2
The overloaded "update" functions are used in two classes :
Simulation sim->update(dt);
Observer (*iter)->update(dt, timeScale);
The same word (update) uses one parameter in Simulation
and two parameters in Observer. That is called overloading.

3
The updating encompasses two activities :
Updating the observer's perspective
Updating the universe's materials

4
Branching is present but not shown. For example, branches work on
galaxies, nebulas, stars, planets, satellites. This explanation is focussing
on the one branch for planetary bodies. That is for me to study details
leading up to my rocket motor software that would accelerate .3ds
bodies in front of the observer.

5
This explanation was not approved by any expert in Celestia.
Also, the flowchart was not approved or even critiqued by anyone.

6
This UPDATE box explanation may have notes that should be for the
"Initialize" box of the flowchart, and not for UPDATE. As time goes on,
that will be corrected, if needed.

7
What are Point3d and Point3f ?
They seem to be defined in vecmath.h :

template<class T> class Point3
{
public:
inline Point3();
inline Point3(const Point3&);
inline Point3(T, T, T);
inline Point3(T*);

inline T& operator[](int) const;
inline Point3& operator+=(const Vector3<T>&);
inline Point3& operator-=(const Vector3<T>&);
inline Point3& operator*=(T);

inline T distanceTo(const Point3&) const;
inline T distanceToSquared(const Point3&) const;
inline T distanceFromOrigin() const;
inline T distanceFromOriginSquared() const;

T x, y, z;
};

also in vecmath.h :

typedef Point3<float> Point3f;
typedef Point3<double> Point3d;

That answers the question, What are Point3d and Point3f ?
They are the classes with double precision and the floating point number
representations of the vectors and their operators.

vecmath.h also has templates for Matrix3 and Vector3 classes
These are mentioned because Point3d is used in many functions and
this will start the process of familiarization at the level of detail that
will be useful for implementing rocket motors.