Tutorial for mesh distortion in Blender Python

[mabelzhang]

🎉 New feature

Blender Python script and tutorial for programmatically distorting 3D meshes.

Upstreaming from Project DAVE.

Summary

See tutorial Markdown file.

Test it

Blender 2.92 (newer might work too) is required - I'm not sure who's the best to review this?

Follow instructions in tutorial.
Check that the tutorial renders correctly by compiling and then navigating in a browser to ign/build/ignition-gazebo7/doxygen/html/blender_distort_meshes.html

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.

[codecov]

Codecov Report

Merging #1401 (d51b4c8) into main (1e0041a) will increase coverage by 1.30%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1401      +/-   ##
==========================================
+ Coverage   62.22%   63.52%   +1.30%     
==========================================
  Files         316      317       +1     
  Lines       24317    25253     +936     
==========================================
+ Hits        15131    16043     +912     
- Misses       9186     9210      +24     

Impacted Files	Coverage Δ
include/ignition/gazebo/detail/View.hh	98.60% <0.00%> (-1.40%)	⬇️
src/SystemManager.cc	100.00% <0.00%> (ø)
src/SystemInternal.hh	100.00% <0.00%> (ø)
src/SimulationRunner.hh	100.00% <0.00%> (ø)
include/ignition/gazebo/detail/BaseView.hh	100.00% <0.00%> (ø)
include/ignition/gazebo/EntityComponentManager.hh	100.00% <0.00%> (ø)
src/EntityComponentManagerDiff.cc	81.25% <0.00%> (ø)
src/SimulationRunner.cc	94.09% <0.00%> (+2.05%)	⬆️
src/EntityComponentManager.cc	91.86% <0.00%> (+3.49%)	⬆️

---

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 1e0041a...d51b4c8. Read the comment docs.

[mayman99]

Works as expected!

imho I would personally prefer if we didn't have to use scripting inside blender or blender GUI at all to produce results, like instead of writing

   file_path = '/path/to/file.dae'
   object_prefix = 'Cube'
   distort_extent = 0.1  # float in range [0, 1]
   method = 'deform'  # method of distortion
   sys.argv = ['distort_mesh.py', file_path, object_prefix, distort_extent, method]
   exec(open('/path/to/distort_mesh.py').read());

inside the blender console, having them as a part of the script, plus a bpy import object on top.
Then the user will have to only run something like ./blender -b -P <distort_script> args... from the terminal.

[mayman99]

@mabelzhang friendly ping :)

[AzulRadio]

The script looks good.

Tested with Blender 2.93 LTS and 3.0.0 on Windows. The results are slightly different. Are these results still considered good?

2.93 LTS with 0.04 distort

3.0.0 with 0.2 distortion (default distortion in the tutorial)

[mabelzhang]

imho I would personally prefer if we didn't have to use scripting inside blender or blender GUI at all

Thanks! I didn't know you could invoke Blender from the regular command line 😅 I had looked into it before but landed on something that didn't work 😅
83a417c makes the script work from the bash command line prompt, as well as the Blender Scripting GUI Python prompt.

[mabelzhang]

The results are slightly different. Are these results still considered good?

Thank you for catching that. Yeah I adjusted the VERT_RAND_MIN and VERT_RAND_MAX and forgot to update the README. It's a bit tricky to set for the general case and will need to be tuned for each model, I think.
d5acd69 adds that documentation about distort_extent.
I've changed the tutorial distort_extent to 0.005 in 7dc4381.

[mabelzhang]

@mayman99 Sorry for the long delay, and thank you for pressing charge. We have an active budget for the supporting project again, so I can spend time on this again :)

Ready for another pass.

[codecov]

Codecov Report

Merging #1401 (fd37e2e) into main (9d24893) will increase coverage by 0.02%.
The diff coverage is n/a.

❗ Current head fd37e2e differs from pull request most recent head d5acd69. Consider uploading reports for the commit d5acd69 to get more accurate results

@@            Coverage Diff             @@
##             main    #1401      +/-   ##
==========================================
+ Coverage   63.57%   63.59%   +0.02%     
==========================================
  Files         330      330              
  Lines       25926    25925       -1     
==========================================
+ Hits        16482    16487       +5     
+ Misses       9444     9438       -6     

Impacted Files	Coverage Δ
src/EntityComponentManager.cc	90.86% <0.00%> (-0.02%)	⬇️
src/SimulationRunner.cc	92.45% <0.00%> (+0.94%)	⬆️

---

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 9d24893...d5acd69. Read the comment docs.

[mayman99]

Thanks for adding the command line usage!
lgtm 👍