Create AGL property for contacts

[seanmcleod]

In response to the request in discussion - #1102

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 12 lines in your changes missing coverage. Please review.

Project coverage is 24.93%. Comparing base (c867cc7) to head (1f73cf7).

Files	Patch %	Lines
src/models/FGLGear.cpp	0.00%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1104      +/-   ##
==========================================
- Coverage   24.94%   24.93%   -0.01%     
==========================================
  Files         170      170              
  Lines       18235    18239       +4     
==========================================
  Hits         4548     4548              
- Misses      13687    13691       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bcoconni]

Thanks for the PR. Sorry, I had to rebase the code following the incompatibility with Numpy 2.0 (see PR #1107) as it was preventing your PR to be tested on the MacOSX ARM64 platform.

I'm not sure that we should return an AGL for retracted gears, at least for the following reasons:

• The position (w.r.t the aircraft structural frame) of retractable gears is not the same when the gear is retracted as it is when the gear is deployed. So when the gear is retracted the returned value would be the AGL of a fictitious point rather than the actual AGL of the gear.
• I have this vague recollection that raycasting the terrain was CPU intensive for FlightGear (this was due to LOD management when flying at high altitudes or something like that). For such terrain engines, limiting the number of raycasting computations to the bare minimum might help relieving the CPU load.

Regarding the code:

• The member variable name AGL should be more explicit such as altitude, height, altitude_above_ground, etc.
• With the addition of this new member, we should no longer need the local variable height as they would be redundant.

jsbsim/src/models/FGLGear.cpp

Lines 297 to 301 in c867cc7

	// Compute the height of the theoretical location of the wheel (if strut is
	// not compressed) with respect to the ground level
	double height = fdmex->GetInertial()->GetContactPoint(gearLoc, contact,
	normal, terrainVel,
	dummy);

[seanmcleod]

In terms of ray casting and retracted gear and performance I thought about this at the time when I noticed that the code was only calculating the AGL for the gear when the gear was extended. However this means there is a difference between aircraft with fixed undercarriage, e.g. a C-172 and aircraft like the 737 with retractable undercarriage.

There is also generally a ray cast from the CoG for each simulation time step, especially if the aerodynamics section includes a function calculating ground effects.

Also remember this is a specialised ray cast, as opposed to a generic ray cast. It's really a DEM lookup, i.e. given a lat, lon return the ground elevation for the particular DEM cell. As opposed to the general ray cast of casting a ray from altitude at some angle towards the ground with potential terrain in-between before the ray hits the ellipse etc. So I'd be surprised if this sort of DEM lookup was very CPU intensive.

In terms of retractable gear, yep, we don't have a structural location specified for the retracted state, so in the retracted state we are as you say with a fictitious point. However, one of the reasons I implemented this request over and above the original poster's request is that a while ago I came across some documentation from Boeing with regards to their simulator model for an early generation 737 which had the following in it.

In which for calculating ground effects they don't use the AGL of the CoG but rather the AGL of the main gear.

The ground effects need to be calculated for a wheels up case as well, i.e. based on the fictitious point of the main gear, so a potential reason to calculate the AGL for the gear even if they're retracted. Although I guess an FDM developer could always make use of the CoG AGL and the relevant angles and offsets as shown in the Boeing snippet to create a function to calculate the main gear's AGL.

In terms of the member name, AGL isn't that fairly clear in an aerospace domain? I could rename it or add a comment.

[bcoconni]

The ground effects need to be calculated for a wheels up case as well, i.e. based on the fictitious point of the main gear, so a potential reason to calculate the AGL for the gear even if they're retracted. Although I guess an FDM developer could always make use of the CoG AGL and the relevant angles and offsets as shown in the Boeing snippet to create a function to calculate the main gear's AGL.

Fair enough. If someone complains about an increase of their CPU load after this PR has been committed there is still remaining the option of evaluating the AGL of retracted gears on demand (i.e. only when the property getter is called).

In terms of the member name, AGL isn't that fairly clear in an aerospace domain? I could rename it or add a comment.

I've been working in the aerospace industry for 25+ years and I can confirm that we have a dedicated passion for acronyms 😄 British, American and French aerospace industry alike (and most likely others as well but I cannot tell from my personal experience regarding them). The highest score I've seen so far is 5 acronyms in a single bullet point (albeit made of several sentences) in a PowerPoint presentation. And the slide was making perfect sense to the attendance, actually I was the only person who noticed that 5 acronyms were packed in a single bullet point 😉

I could be picky and argue that AGL is mostly used for an aircraft as a whole and that the word "height" is used for structural points. For example I've never seen the acronym AGL used for the nacelle inlet distance above the ground. And the Boeing document that you mentioned is also using the word "height" for the gears. But you're the native speaker so I may be wrong 😄

Also regarding JSBSim I'm not so fond of acronyms because I know from experience that they are daunting for newcomers and we cannot assume that all our users have a solid background in aerospace jargon so I'd say that a comment is the bare minimum. And yes, there are already plenty of occurrences of acronyms in JSBSim code so we can live with one more 😄 That's just my 2 cents.

[bcoconni]

And if the property name could mention the unit (i.e. feet) that would be perfect !

[seanmcleod]

Will do. In terms of the rebasing that shouldn't affect my branch in terms of updating it to make the changes with regards to the member name, property name etc.? I can as usual for a PR simply go ahead and push another commit to my branch?

[bcoconni]

Will do. In terms of the rebasing that shouldn't affect my branch in terms of updating it to make the changes with regards to the member name, property name etc.? I can as usual for a PR simply go ahead and push another commit to my branch?

If you had not committed local changes to your branch before git pull then you can work as usual after pulling the rebased branch.

Otherwise, you'd need to rename your branch to duplicate the changes, reset the branch used for the PR, pull that branch for rebasing and finally cherry pick the changes from the duplicated branch. At least, that's how I'd proceed.

[seanmcleod]

Talking of the Boeing acronyms, took me a little while to decode HMGBT to Height Main Gear Bottom of Tire 😉

And HGCG - Height above Ground (?) Center of Gravity? No consistency in using ground?

Also realised that this must be a fictitious tire since they multiply by $\cos \phi$ and there is no mention of the lateral offset of the tire from the centerline, and then would it be positive or negative depending on whether it was the left main gear tire versus right main gear tire. So this must be a fictitious centerline tire for the 737 which doesn't have one, unlike some Airbus models.

[bcoconni]

Talking of the Boeing acronyms, took me a little while to decode HMGBT to Height Main Gear Bottom of Tire 😉

I've been told that some of the more cryptic acronyms are the legacy of the older FORTRAN compilers that were limiting the variable names to 7 letters max. There are also some cases where an acronym is starting with the X letter because FORTRAN was forcing variables starting with the letters I to N to be integers. For instance the rotating speed of the N1 spool is noted XN1 so that the value would be considered a floating point variable by the compiler 🤣

Also realised that this must be a fictitious tire since they multiply by $\cos\phi$ and there is no mention of the lateral offset of the tire from the centerline, and then would it be positive or negative depending on whether it was the left main gear tire versus right main gear tire. So this must be a fictitious centerline tire for the 737 which doesn't have one, unlike some Airbus models.

I guess this is accounting for the fact that if a wing closer to the ground then the opposite wing must be farther to the ground by the same amount in absolute value: the opposite offsets would be mutually neutralizing and the ground effect could be safely assessed from the centerline height above the ground ? Just a guess, I'm no aerodynamicist.

[seanmcleod]

Yep, I did notice references to Fortran in the document, so they obviously didn't use JSBSim within Boeing😉

[agodemar]

@seanmcleod @bcoconni great job!

[seanmcleod]

Also remember this is a specialised ray cast, as opposed to a generic ray cast. It's really a DEM lookup, i.e. given a lat, lon return the ground elevation for the particular DEM cell. As opposed to the general ray cast of casting a ray from altitude at some angle towards the ground with potential terrain in-between before the ray hits the ellipse etc.

@bcoconni it turns out the statement I made above isn't accurate, at least for the Unreal plug-in, I haven't looked at the FlightGear implementation yet. I had assumed that JSBSim hosts like Unreal, FlightGear etc. would simply be performing a DEM lookup as opposed to a general raycast.

I realised this wasn't the case for Unreal when I took a look at discussion - #1105. In looking at the code for the Unreal plugin for this discussion I noticed that they are performing a general raycast.

jsbsim/UnrealEngine/Plugins/JSBSimFlightDynamicsModel/Source/JSBSimFlightDynamicsModel/Private/JSBSimMovementComponent.cpp

Lines 130 to 155 in 2a5985c

	// Compute the raycast Origin point
	FVector StartEngineLocation;
	GeoReferencingSystem->ECEFToEngine(StartECEFLocation, StartEngineLocation);
	FVector LineCheckStart = StartEngineLocation + 200 * Up; // slightly above the starting point
	// Compute the raycast end point
	// Estimate raycast length - Altitude + 5% of ellipsoid radius in case of negative altitudes
	FVector LineCheckEnd = StartEngineLocation - (AircraftState.AltitudeASLFt * FEET_TO_METER + 0.05 * GeoReferencingSystem->GetGeographicEllipsoidMaxRadius()) * Up;
	// Prepare collision query
	FHitResult HitResult = FHitResult();
	static const FName LineTraceSingleName(TEXT("AGLevelLineTrace"));
	FCollisionQueryParams CollisionParams(LineTraceSingleName);
	CollisionParams.bTraceComplex = true;
	CollisionParams.AddIgnoredActor(Parent);
	FCollisionObjectQueryParams ObjectParams = FCollisionObjectQueryParams(ECC_WorldStatic);
	ObjectParams.AddObjectTypesToQuery(ECC_WorldDynamic);
	ObjectParams.AddObjectTypesToQuery(ECC_Pawn);
	ObjectParams.AddObjectTypesToQuery(ECC_Visibility);
	//DrawDebugLine(GetWorld(), LineCheckStart, LineCheckEnd , FColor::Blue, false, -1, 0, 3);
	// Do Query
	double HAT = 0.0;
	if (GetWorld()->LineTraceSingleByObjectType(HitResult, LineCheckStart, LineCheckEnd, ObjectParams, CollisionParams))

Thinking about it, this makes sense particularly if you want to be able to model landing on objects above ground, e.g. an aircraft carrier deck, you need a raycast to detect the aircraft carrier model's deck rather than the ocean below it. Or a helicopter landing on a building etc.

So in general I think JSBSim's hosts will make use of general raycasting rather than simple DEM lookups.

I also noticed based on the discussion that the F-16 model in JSBSim has 7 structure contacts, so there are 7 raycasts being performed on each timestep even if the landing gear is retracted.