Make WindEffects configurable on a location basis

[hidmic]

🎉 New feature

Closes #1354.

Summary

This patch turns the force approximation scaling factor in the WindEffects plugin into a piecewise scalar field, configurable from the SDF file. It can still be configured as a scalar, so it remains backwards compatible.

Test it

An integration test case has been added to the INTEGRATION_wind_effects test suite.

Checklist

• Signed all commits for DCO
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• codecheck passed (See contributing)
• All tests passed (See test coverage)
• While waiting for a review on your PR, please help review another open pull request to support the maintainers

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by messages.

[hidmic]

There are a few questions that remain to be answered:

• Is the force approximation scaling factor the best place to introduce a dependency on link location? Should the wind velocity itself be dependent on location instead?
• Should Polynomial3, SeparableFunction3d, and PiecewiseScalarField3d be here in an anonymous namespace or over at ignition-math? If so, sdformat parsing needs to be put elsewhere.
• Are we OK with a dynamic schema for convenience? Right now, <force_approximation_scaling_factor> can take either a scalar or nested structures.
• Is a bounds attribute OK for managing open and closed subspaces? I don't like it very much, but I couldn't come up with anything better.

On a related note, I couldn't easily run codecheck. Maybe I'm not using the right directory layout?

[hidmic]

FYI @caguero

[hidmic]

Talking to @azeey earlier today, he rightly pointed out that simply applying forces to link frame origins does not allow for torques to be developed at the interface between regions.

Then the question is how we model wind forces. Right now we make them proportional to the link mass and linear velocity w.r.t that of the wind. We could compute the solid geometries that result from the intersection between a link's collision geometry and each region (a là CSG), assume homogeneous density, and apply the same model to each solid geometry independently.

I wonder though, if forces proportional to some cross-section area normal to the direction of the wind wouldn't give us "better" results (the definition of good, let alone better, is quite blurry to me).

[hidmic]

Is the force approximation scaling factor the best place to introduce a dependency on link location? Should the wind velocity itself be dependent on location instead?

Hmm, a piecewise vector field for wind velocity would indeed be simpler to reason about than this scaling factor (which is bound to the approximation model).

[arjo129]

Talking to @azeey earlier today, he rightly pointed out that simply applying forces to link frame origins does not allow for torques to be developed at the interface between regions.

Then the question is how we model wind forces. Right now we make them proportional to the link mass and linear velocity w.r.t that of the wind. We could compute the solid geometries that result from the intersection between a link's collision geometry and each region (a là CSG), assume homogeneous density, and apply the same model to each solid geometry independently.

I wonder though, if forces proportional to some cross-section area normal to the direction of the wind wouldn't give us "better" results (the definition of good, let alone better, is quite blurry to me).

I had wondered about this actually. It would seem to me that there is some formulation that will be similar to the hydrodynamics formulation where we can capture the changing faces on the behaviour of the wind. However, I think we don't need to go to this detail at all for the LRAUV. One thing to note is that the LRAUV will experience torque given its CG is not the same as the link so for now I think we can get away with what we have implemented.

[caguero]

• I definitely recommend to move Polynomial3, Region3d, SeparableFunction3d, and PiecewiseScalarField3d to Ignition Math. Overall, it'll make the review easier to follow, as we'll be splitting everything into multiple PRs.

• I noticed a few style inconsistencies. E.g.: Not using this-> for every member or function, not using the function separators (////////////////////////////////////////////////) and not using Doxygen in the function declarations.

• I agree that maybe we can live with the fact that some torques won't be generated if we apply the force at the link origin.

• We probably need to parse the SDF data in this plugin, and then, pass the numeric values to the Ignition Math classes that we use.

• I recommend to document the new SDF parameters in the WindEffects.hh file. Open it to see how the current parameters are described. It'll be infinite more useful if you include an example and explain what you're trying to achieve and how that translates into the SDF parameters. It could be your test but explained for a human.

[hidmic]

I definitely recommend to move Polynomial3, Region3d, SeparableFunction3d, and PiecewiseScalarField3d to Ignition Math. Overall, it'll make the review easier to follow, as we'll be splitting everything into multiple PRs.

@caguero See gazebosim/gz-math#387. That PR can of course be further split.

I noticed a few style inconsistencies. E.g.: Not using this-> for every member or function, not using the function separators (////////////////////////////////////////////////) and not using Doxygen in the function declarations.

@caguero I think I've addressed this, though I haven't added Doxygen documentation to private functions that are implementation details (which are fairly self explanatory on their own already).

I agree that maybe we can live with the fact that some torques won't be generated if we apply the force at the link origin.

@caguero Fair enough.

We probably need to parse the SDF data in this plugin, and then, pass the numeric values to the Ignition Math classes that we use.

@caguero Done.

I recommend to document the new SDF parameters in the WindEffects.hh file. Open it to see how the current parameters are described.

@caguero Done.

It'll be infinite more useful if you include an example and explain what you're trying to achieve and how that translates into the SDF parameters. It could be your test but explained for a human.

@caguero We have class documentation and regression tests. We can add an example too if you think it's worth it.

[hidmic]

Rebased to resolve conflicts.

[hidmic]

https://build.osrfoundation.org/job/ignition_gazebo-ci-pr_any-homebrew-amd64 appears to be broken in main too.

[codecov]

Codecov Report

Merging #1357 (a6ac58b) into main (f6ba375) will increase coverage by 0.05%.
The diff coverage is 63.20%.

@@            Coverage Diff             @@
##             main    #1357      +/-   ##
==========================================
+ Coverage   62.34%   62.39%   +0.05%     
==========================================
  Files         317      317              
  Lines       24419    24489      +70     
==========================================
+ Hits        15224    15281      +57     
- Misses       9195     9208      +13     

Impacted Files	Coverage Δ
.../gui/plugins/transform_control/TransformControl.cc	7.36% <ø> (+0.01%)	⬆️
...lization_capabilities/VisualizationCapabilities.cc	3.66% <0.00%> (ø)
src/rendering/RenderUtil.cc	36.94% <0.00%> (ø)
src/systems/contact/Contact.hh	100.00% <ø> (ø)
src/systems/particle_emitter/ParticleEmitter.cc	55.40% <0.00%> (ø)
src/systems/scene_broadcaster/SceneBroadcaster.hh	100.00% <ø> (ø)
src/systems/thruster/Thruster.cc	92.30% <ø> (-0.06%)	⬇️
src/systems/wind_effects/WindEffects.cc	78.82% <79.74%> (+0.68%)	⬆️
...ems/collada_world_exporter/ColladaWorldExporter.hh	100.00% <100.00%> (ø)
...ems/kinetic_energy_monitor/KineticEnergyMonitor.hh	100.00% <100.00%> (ø)
... and 2 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8c690ff...a6ac58b. Read the comment docs.

[arjo129]

This looks good to me now.

[hidmic]

Thanks @arjo129 !

@chapulina how do we go about failing CI jobs? Do we merge despite them or do we quarantine PRs until that's solved?

[chapulina]

how do we go about failing CI jobs? Do we merge despite them or do we quarantine PRs until that's solved?

Everything that's Required must be green. For this branch, that's none of the jobs 🙃 Which means all jobs have known flakes. So we look at them and if the failures aren't new or related to the PR we merge. That's the case here, so merging!