Getting the location (coordinates) of the aircraft

[LuFlo]

The programmer documentation lacks some really basic information. I mean, come on guys, this should be documented :( I found this: http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGLocation.html
But nowhere is said WHERE to get this object. From FGAircraft? No. Directly from the executor? No. Also I am using the python wrapper and somehow there are a lot of public members missing in FGAircraft, maybe the position is there?

[seanmcleod]

I mean, come on guys, this should be documented :(

Well pull requests are welcome 😉

In terms of getting location data take a look at:

jsbsim/src/models/FGPropagate.cpp

Lines 845 to 868 in 59389f6

	PropertyManager->Tie("position/h-sl-ft", this, &FGPropagate::GetAltitudeASL, &FGPropagate::SetAltitudeASL);
	PropertyManager->Tie("position/h-sl-meters", this, &FGPropagate::GetAltitudeASLmeters, &FGPropagate::SetAltitudeASLmeters);
	PropertyManager->Tie("position/lat-gc-rad", this, &FGPropagate::GetLatitude, &FGPropagate::SetLatitude);
	PropertyManager->Tie("position/long-gc-rad", this, &FGPropagate::GetLongitude, &FGPropagate::SetLongitude);
	PropertyManager->Tie("position/lat-gc-deg", this, &FGPropagate::GetLatitudeDeg, &FGPropagate::SetLatitudeDeg);
	PropertyManager->Tie("position/long-gc-deg", this, &FGPropagate::GetLongitudeDeg, &FGPropagate::SetLongitudeDeg);
	PropertyManager->Tie("position/lat-geod-rad", this, &FGPropagate::GetGeodLatitudeRad);
	PropertyManager->Tie("position/lat-geod-deg", this, &FGPropagate::GetGeodLatitudeDeg);
	PropertyManager->Tie("position/geod-alt-ft", this, &FGPropagate::GetGeodeticAltitude);
	PropertyManager->Tie("position/h-agl-ft", this, &FGPropagate::GetDistanceAGL, &FGPropagate::SetDistanceAGL);
	PropertyManager->Tie("position/geod-alt-km", this, &FGPropagate::GetGeodeticAltitudeKm);
	PropertyManager->Tie("position/h-agl-km", this, &FGPropagate::GetDistanceAGLKm, &FGPropagate::SetDistanceAGLKm);
	PropertyManager->Tie("position/radius-to-vehicle-ft", this, &FGPropagate::GetRadius);
	PropertyManager->Tie("position/terrain-elevation-asl-ft", this,
	&FGPropagate::GetTerrainElevation,
	&FGPropagate::SetTerrainElevation);
	PropertyManager->Tie("position/eci-x-ft", this, eX, (PMF)&FGPropagate::GetInertialPosition);
	PropertyManager->Tie("position/eci-y-ft", this, eY, (PMF)&FGPropagate::GetInertialPosition);
	PropertyManager->Tie("position/eci-z-ft", this, eZ, (PMF)&FGPropagate::GetInertialPosition);
	PropertyManager->Tie("position/ecef-x-ft", this, eX, (PMF)&FGPropagate::GetLocation);
	PropertyManager->Tie("position/ecef-y-ft", this, eY, (PMF)&FGPropagate::GetLocation);
	PropertyManager->Tie("position/ecef-z-ft", this, eZ, (PMF)&FGPropagate::GetLocation);

So you could get hold of FGPropagate or query based on the property, e.g. in python.

fdm = jsbsim.FGFDMExec('..\\') # The path supplied to FGFDMExec is the location of the folders "aircraft", "engines" and "systems"
fdm.load_model('737') 

lon = fdm['position/long-gc-rad']

[LuFlo]

Thanks for the fast response! Yes, I definitely will consider doing some pull request as soon as I get a hang of JSBsim :D
Unfortunately the python wrapper seems not to include all definitions for FGPropagate, I tried for example this:

print(fdm.get_propagate().get_location())

But it only produces an error: AttributeError: 'jsbsim.FGPropagate' object has no attribute 'get_location'

I managed to get the position via the dictionary access as you showed in the example.

One more question: Where do I find definitions / documentation for the properties? For example, what is "ecef-x-ft"? Is it the location in xyz (with origin in the middle of geod) in feet? Then whats the difference between "InertialPosition" and "Location"?

[seanmcleod]

Where do I find definitions / documentation for the properties?

Often there are useful comments in the source, e.g.

jsbsim/src/models/FGPropagate.h

Lines 101 to 104 in 59389f6

	/** Represents the current location of the vehicle in Earth centered Earth
	fixed (ECEF) frame.
	units ft */
	FGLocation vLocation;

jsbsim/src/models/FGPropagate.h

Lines 316 to 318 in 59389f6

	/** Calculates and retrieves the velocity vector relative to the earth centered earth fixed (ECEF) frame.
	*/
	FGColumnVector3 GetECEFVelocity(void) const {return Tb2ec * VState.vUVW; }

There is also some specific documentation with regards to frames of reference:

https://jsbsim-team.github.io/jsbsim-reference-manual/mypages/user-manual-frames-of-reference/

[agodemar]

@LuFlo

The programmer documentation lacks some really basic information. I mean, come on guys, this should be documented :( I found this: http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGLocation.html
But nowhere is said WHERE to get this object. From FGAircraft? No. Directly from the executor? No. Also I am using the python wrapper and somehow there are a lot of public members missing in FGAircraft, maybe the position is there?

The JSBSim software library is the result of years of volunteer work. And you have all you need at your finger tips. For free.
It would be great if smart people having a look at this amazing piece of software could help us out to improve the APIs and the documentation.

[LuFlo]

I don't doubt that JSBsim is amazing software and that a lot of developer put years and years of their time into this project. I never stated the opposite. I also know very well what open source software is, I work with free and open source software every day, in my profession as well as in my free time. Yes maybe I should have formulated it differently since in text form it's easy to get the wrong impression.

I still do think that the criticism is valid though. And I don't even say that the project doesn't have documentation, quite contrary. The PDF document has 160 pages or so. But the core of a flight simulation library is to calculate position and attitude of an aircraft given some input variables. This key part (getting the core information) wasn't very obvious for me, as a person who never used JSBsim before. I would be very happy to help documenting this part, I've seen that you guys have a separate repository for the user manual. I already put some example files together which I used for my recent bug reports / discussions, these can be a basis for some useful documentation for common pitfalls. What do you think?

[agodemar]

@LuFlo that would be a great way to get involved. Thanks, also for the criticism, as in this case it brings the attention on a pitfall that can be easily treated.
There are many little things in open source projects that are as important as code. A clear documentation, of course, but also the deployment workflow as well as reproducible examples of use.
In this last area, I think Jupyter notebooks could be a handy tool.

[seanmcleod]

I've seen that you guys have a separate repository for the user manual.

Yep, this was to serve as a replacement/update of the original PDF document, but it's been stalled for a couple of years.

[LuFlo]

I think I just found out why 😅 apparently it is surprisingly difficult to get Jekyll running on modern distributions, since it relies on ruby 2.7, see here for example: rbenv/ruby-build#1940 (comment)

I think, it's still manageable in VMs which run older distributions, buts kinda painful for local development. I will take a closer look the next days.

[seanmcleod]

Nah, it stalled long before installation issues became an issue 😉

[LuFlo]

Well, that's unfortunate 😅 still, solving installation issues is worth trying :)

[agodemar]

@seanmcleod @bcoconni a better alternative to the technology that I chose more than 3 years ago for the online documentation is Docusaurus. It is supported by GitHub as well and relies on Node.js (no Jekyll).

[LuFlo]

@agodemar I opened an issue on the reference manual repository for this. I also figured out a workaround for local development, although it doesn't have live reloading. I think we can move the discussion about this topic there.