Add Farneback motion estimation method

[dominique-brunet-eccc]

This is to add the Farnebäck method (from OpenCV) for motion field estimation with an optional smoothing and renormalization of the motion vector field. This method is currently used operationally by ECCC for radar extrapolation as the method is fast and generally accurate.

Two examples from the Gallery have been edited to add the Farnebäck method: examples/plot_optical_flow.py and examples/optical_flow_methods_convergence.py.

This is my first pull request, please let me know if you need anything else.

[dominique-brunet-eccc]

Here are the outputs from the example Gallery:

examples/optical_flow_methods_convergence.py:
farneback computation time: 0.4 [s]

farneback computation time: 0.4 [s]

farneback computation time: 0.4 [s]

plot_optical_flow.py:
Computing the motion field with the Farneback method.
mult factor of smoothed motion field= 1.7847746191151432
--- 0.3482193946838379 seconds ---

[Copilot]

Pull request overview

Adds a new OpenCV-based dense optical flow backend (Farnebäck) to pysteps.motion, and updates gallery examples to demonstrate and compare it alongside existing motion-estimation methods.

Changes:

• Register a new "farneback" motion method in pysteps.motion.interface.
• Introduce pysteps.motion.farneback.farneback with optional smoothing + magnitude renormalization.
• Update two Sphinx-Gallery examples to showcase the new method.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
pysteps/motion/interface.py	Registers the new "farneback" method and documents it in the method list.
pysteps/motion/farneback.py	Implements Farnebäck dense optical flow wrapper with optional smoothing/renormalization.
examples/plot_optical_flow.py	Adds a new example section demonstrating Farnebäck usage.
examples/optical_flow_methods_convergence.py	Adds Farnebäck to the convergence comparison example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 18.66667% with 61 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.56%. Comparing base (29a317b) to head (7da7083).

Files with missing lines	Patch %	Lines
pysteps/motion/farneback.py	16.43%	61 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #542      +/-   ##
==========================================
- Coverage   83.89%   83.56%   -0.34%     
==========================================
  Files         168      169       +1     
  Lines       14678    14753      +75     
==========================================
+ Hits        12314    12328      +14     
- Misses       2364     2425      +61     

Flag	Coverage Δ
unit_tests	83.56% <18.66%> (-0.34%)	⬇️

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.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dominique-brunet-eccc]

I added tests/test_motion_farneback.py to get better test coverage. I think it addressed all the automated code review issues. Please let me know if anything else is needed.

[dnerini]

Hi @dominique-brunet-eccc and thanks for the exciting contribution! If I remember well, Farneback is the optical flow routine used in the original implementation of STEPS at BOM (but @alanseed or @loforest will correct me if I'm wrong), which makes this PR particurlarly special!

I looked into your changes and found this PR in excellent state! The implementation is clean and follows the pysteps standards. You already extended the relevant interfaces, documentation, and test coverage.

Thanks also for quickly adressing to the automated review from Copilot. At this point, I'm left with very few and very minor comments, after which I think this PR is ready to be merged.

[dominique-brunet-eccc]

Thank you @dnerini for your kind comments. I am quite excited to finally get this pull request completed. I want to acknowledge my (now retired) colleague Norbert Driedger who did the actual work of finding a suitable motion estimation method for a large domain like North America. My contribution was simply to refactor the code for PySTEPS.

[alanseed]

@dominique-brunet-eccc @dnerini Thanks for this nice addition to the suite of tracking algorithms, looking forward to trying it out. The original optical flow was quite rough, we calculated the flow using least squares solution of differential equations over blocks with rain and then interpolated these u,v onto the grid. I found that using some form of temporal smoothing made a big difference since the advection vector does not change that much in 5 mins.