[ENH] Improve plotting contours for PlotlySurfaceFigure objects by adding add_contours method

[psadil]

• Closes [ENH] improving plot_surf_contours  #3711

Changes proposed in this pull request:

• Add add_contours method to PlotlySurfaceFigure, increasing customizability of contour lines.
• Added example of the method in plot_3d_map_to_surface_projection

[github-actions]

👋 @psadil Thanks for creating a PR!

Until this PR is ready for review, you can include the [WIP] tag in its title, or leave it as a github draft.

Please make sure it is compliant with our contributing guidelines. In particular, be sure it checks the boxes listed below.

• PR has an interpretable title.
• PR links to Github issue with mention Closes #XXXX (see our documentation on PR structure)
• Code is PEP8-compliant (see our documentation on coding style)
• Changelog or what's new entry in doc/changes/latest.rst (see our documentation on PR structure)

For new features:

• There is at least one unit test per new function / class (see our documentation on testing)
• The new feature is demoed in at least one relevant example.

For bug fixes:

• There is at least one test that would fail under the original bug conditions.

We will review it as quick as possible, feel free to ping us with questions if needed.

[codecov]

Codecov Report

Attention: Patch coverage is 96.27329% with 6 lines in your changes missing coverage. Please review.

Project coverage is 92.84%. Comparing base (abb80ff) to head (cb8ad06).
Report is 113 commits behind head on main.

Files	Patch %	Lines
nilearn/plotting/displays/_figures.py	96.15%	4 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3949      +/-   ##
==========================================
+ Coverage   91.85%   92.84%   +0.98%     
==========================================
  Files         144      147       +3     
  Lines       16419    17166     +747     
  Branches     3434     3611     +177     
==========================================
+ Hits        15082    15938     +856     
+ Misses        792      685     -107     
+ Partials      545      543       -2     

Flag	Coverage Δ
macos-latest_3.10_test_plotting	92.39% <95.65%> (?)
macos-latest_3.11_test_plotting	92.39% <95.65%> (+0.53%)	⬆️
macos-latest_3.12_test_plotting	92.39% <95.65%> (?)
macos-latest_3.8_test_plotting	92.36% <95.65%> (?)
macos-latest_3.9_test_plotting	92.37% <95.65%> (?)
ubuntu-latest_3.10_test_plotting	92.39% <95.65%> (+0.53%)	⬆️
ubuntu-latest_3.11_test_plotting	92.39% <95.65%> (?)
ubuntu-latest_3.12_test_plotting	92.39% <95.65%> (?)
ubuntu-latest_3.12_test_pre	92.39% <95.65%> (?)
ubuntu-latest_3.8_test_min	68.42% <0.00%> (?)
ubuntu-latest_3.8_test_plot_min	91.30% <12.42%> (?)
ubuntu-latest_3.8_test_plotting	92.36% <95.65%> (?)
ubuntu-latest_3.9_test_plotting	92.37% <95.65%> (?)
windows-latest_3.10_test_plotting	92.38% <95.65%> (?)
windows-latest_3.11_test_plotting	92.38% <95.65%> (?)
windows-latest_3.12_test_plotting	92.38% <95.65%> (?)
windows-latest_3.8_test_plotting	92.35% <95.65%> (?)
windows-latest_3.9_test_plotting	92.37% <95.65%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[ymzayek]

@psadil thanks for getting started on this! Will try to start a review this week

[psadil]

Tests added!

Do these seem like they're on the right track?

[Remi-Gau]

Tests added!

Thanks!!

Do these seem like they're on the right track?

Had a very quick look: it does help also understand how these methods are used, so definitely useful

[bthirion]

LGTM, thx !

[man-shu]

Thanks for resolving all the comments @psadil ! But just a few more tests :)
And then we can add this to the changelog, see: https://nilearn.github.io/stable/development.html#changelog

[psadil]

It looks like those failures for NPY201 are being triggered by different parts of the repo?

[Remi-Gau]

It looks like those failures for NPY201 are being triggered by different parts of the repo?

yes that's not you

I will merge the main branch in your PR to solve this: remember to pull first before you push again 😉

[bthirion]

Looks mostly good. A little effort on pedagogy would help.

[bthirion]

Can we make sure that the loop ends ?
What algorithm is implemented here ?

[psadil]

It's a modification of the approach listed in the original issue: #3711 (comment), with the modifications aiming to ensure that the contour does not cross itself. I'm not sure how it could fail to end, but if preferred I think I could update it to a for loop.

[bthirion]

I'd more comfortable with a for loop indeed...

[psadil]

Sounds good! I cleaned up the sorting procedure a bit and added a few more explanatory comments cb8ad06.