Add quiver trace type for vector field visualization

[degzhaus]

Overview

This PR adds a new scatterquiver trace type to Plotly.js for visualizing vector fields. The implementation includes:

• New trace type: scatterquiver for quiver/vector field plots
• Complete implementation: supplyDefaults, calc, plot, hover, and attributes
• Comprehensive testing: Jasmine unit tests and visual regression tests
• Mock data: Three test cases (basic, gradient, meshgrid)
• Integration: Properly integrated into the build system

Features

• Vector field visualization with customizable arrow scaling
• Support for gradient fields and meshgrid data
• Configurable arrow appearance (scale, angle, line styling)
• Full hover support and interaction

Screenshots

Examples taken from:
https://plotly.com/python/quiver-plots/

Here is a gist of the 2 plots used in the examples:
https://gist.github.com/degzhaus/2fb3c08cbc228682125f94bce52ba7d1

Basic Quiver Plot (0-quiver-meshgrid.html)

Adding colorscale: [[0, 'blue'], [1, 'blue']], to var data = [{:

Quiver Plot with Points (1-quiver-gradient.html)

Adding colorscale: 'Viridis', to var data = [:

Testing

• ✅ All Jasmine unit tests passing (6/6)
• ✅ Visual regression tests with mock data
• ✅ Manual testing with HTML examples

Files Added/Modified

• src/traces/scatterquiver/ - Complete trace implementation
• lib/index.js & lib/index-strict.js - Build integration
• test/jasmine/tests/scatterquiver_test.js - Unit tests
• test/image/mocks/scatterquiver_*.json - Mock data
• test/jasmine/assets/mock_lists.js - Test integration

Draft Log

• draftlogs/7584_add.md - Changelog entry

This addresses the need for vector field visualization in Plotly.js, similar to matplotlib's quiver plots.

[degzhaus]

Hello, I am new to this project and attempting to contribute my first PR.

Unfortunately, I am struggling to get the build to pass. Specifically, the publish-dist-node-v22 step:
https://app.circleci.com/pipelines/github/plotly/plotly.js/12658/workflows/ae5271e7-9971-4db1-a713-b42f0625901f/jobs/282198

I tried running npm run schema and pushing the change here:
9463b3f

But still encountering the issue.

Any insight would be greatly appreciated. Thank you!

Edit: tagging a few recent commiters for visibility, thanks so much! (cc @camdecoster @alexshoe @emilykl)

[emilykl]

Hi @degzhaus, thank you for working on this contribution!

As it stands currently, the devtools dashboard needs to be running in order for npm run schema to work properly. So you should run npm start and leave it running, and then in another terminal run npm run schema. (@camdecoster is working on a PR to eliminate that step, see #7589)

You can also download plot-schema.json from the "Artifacts" tab in CircleCI and commit it.

[degzhaus]

Hi @degzhaus, thank you for working on this contribution!

As it stands currently, the devtools dashboard needs to be running in order for npm run schema to work properly. So you should run npm start and leave it running, and then in another terminal run npm run schema. (@camdecoster is working on a PR to eliminate that step, see #7589)

You can also download plot-schema.json from the "Artifacts" tab in CircleCI and commit it.

Thank you so much, @emilykl! That was very helpful and unblocked me.

Unfortunately, I have been struggling with the no-gl-jasmine test in ci:
https://app.circleci.com/pipelines/github/plotly/plotly.js/12700/workflows/8b80de4d-1bad-455d-baef-72bc47c31042/jobs/283463

If you have any insight, I would greatly appreciate it. Thanks again!

Edit: @emilykl i figured it out! Pardon my flailing at last night. So exciting! I have a couple of tests to add and this will be ready for review.

Thanks again for your insights and help!

[emilykl]

@degzhaus Great news, glad you're unblocked! Thank you for your work on this. Quiver is a plot type we've gotten a lot of requests for.

A few high-level comments on the API:

• This trace type is fairly distinct from existing scatter* trace types; let's go with the name quiver instead.

• The most similar already-existing trace type is the 3d cone trace, so the attributes of quiver should match the existing API of cone as closely as possible for consistency. For example, rather than the scale property it should use sizemode and sizeref as the cone trace does. (Obviously, some attributes like z and w are not relevant in a 2d context).

• Any attributes for configuring the size/scale of the arrowhead should match the arrowhead config options for annotations

  • It's also not necessary to include those options in a first version of this trace type, but any attributes that are added should be consistent with what's already in the library

• There's a few other things I noticed in the attributes as well:

  • The scaleratio attribute doesn't belong; the scale ratio between the axes should be a property of the axes themselves, not the trace. The axis scale ratio can already be configured using the existing axis.scaleratio attribute.
  • It's unclear to me how the angle attribute interacts with u and v, since u and v are already sufficient to fully determine the arrow's angle. The angle attribute should probably be removed.

[degzhaus]

@degzhaus Great news, glad you're unblocked! Thank you for your work on this. Quiver is a plot type we've gotten a lot of requests for.

A few high-level comments on the API:

• This trace type is fairly distinct from existing scatter* trace types; let's go with the name quiver instead.

• The most similar already-existing trace type is the 3d cone trace, so the attributes of quiver should match the existing API of cone as closely as possible for consistency. For example, rather than the scale property it should use sizemode and sizeref as the cone trace does. (Obviously, some attributes like z and w are not relevant in a 2d context).

• Any attributes for configuring the size/scale of the arrowhead should match the arrowhead config options for annotations

  • It's also not necessary to include those options in a first version of this trace type, but any attributes that are added should be consistent with what's already in the library

• There's a few other things I noticed in the attributes as well:

  • The scaleratio attribute doesn't belong; the scale ratio between the axes should be a property of the axes themselves, not the trace. The axis scale ratio can already be configured using the existing axis.scaleratio attribute.
  • It's unclear to me how the angle attribute interacts with u and v, since u and v are already sufficient to fully determine the arrow's angle. The angle attribute should probably be removed.

Amazing, thank you so much for taking a look and providing great guidance, Emily! Looking forward to spinning a cycle on this feedback.

[emilykl]

@degzhaus One more comment — it would be great to include colorscale attributes in quiver so that arrows can be colored according to the magnitude of the vector. These attributes are added to the cone trace here; something similar can be done for the quiver trace. And then obviously those attributes need to be referenced in the plotting code to assign the appropriate color.

[degzhaus]

Alrighty, @emilykl and @gpdf , thanks again for your insightful feedback on this pr. I think I have addressed all except the drawing of the arrows themselves, which might be addressable as a followup?

I added a gist and updated screenshots. Looking forward to the next round of reviews.

[emilykl]

Great news @degzhaus! I've started looking at the code and I'll get back to you soon with another round of review.

One quick question: your PR description refers to some Jasmine test files and image mocks which I don't see in the diff, did you maybe forget to push some files?

[degzhaus]

@degzhaus One more comment — it would be great to include colorscale attributes in quiver so that arrows can be colored according to the magnitude of the vector. These attributes are added to the cone trace here; something similar can be done for the quiver trace. And then obviously those attributes need to be referenced in the plotting code to assign the appropriate color.

Amazing, thank you so much @emilykl !

I did indeed forget to push the tests, which i have done now here:
12a46e6

One thing I'm spinning my wheels on now is the image generation. I generated them locally here:
9287e5c

But as you can see here, they are failing in ci:
https://app.circleci.com/pipelines/github/plotly/plotly.js/12822/workflows/a9ae7478-acf1-4d50-817c-3e7fbb34e8c3/jobs/286792/artifacts

One notable strangeness is that they look good in my commit, but look strange in the ci artifacts. One example:

Thanks again for all your help with this PR!

[degzhaus]

@degzhaus One more comment — it would be great to include colorscale attributes in quiver so that arrows can be colored according to the magnitude of the vector. These attributes are added to the cone trace here; something similar can be done for the quiver trace. And then obviously those attributes need to be referenced in the plotting code to assign the appropriate color.

Amazing, thank you so much @emilykl !

I did indeed forget to push the tests, which i have done now here: 12a46e6

One thing I'm spinning my wheels on now is the image generation. I generated them locally here: 9287e5c

But as you can see here, they are failing in ci: https://app.circleci.com/pipelines/github/plotly/plotly.js/12822/workflows/a9ae7478-acf1-4d50-817c-3e7fbb34e8c3/jobs/286792/artifacts

One notable strangeness is that they look good in my commit, but look strange in the ci artifacts. One example:

Thanks again for all your help with this PR!

Okay, I see what is happening now, @emilykl !

I was looking at the diff, not the raw image that CI generates. Here is an example:

CI generates the following image for diff-quiver_simple.png:

And corresponding diff for the same image:

So, maybe something is different with my local versioning for dependencies?

My only fear is that if I swap in the raw images that CI generates, that it is actually wrong and/or could break or flake in the future. Hmm 🤔

Thanks again for everything, and I hope you have a splendid day!

[degzhaus]

@degzhaus One more comment — it would be great to include colorscale attributes in quiver so that arrows can be colored according to the magnitude of the vector. These attributes are added to the cone trace here; something similar can be done for the quiver trace. And then obviously those attributes need to be referenced in the plotting code to assign the appropriate color.

Amazing, thank you so much @emilykl !
I did indeed forget to push the tests, which i have done now here: 12a46e6
One thing I'm spinning my wheels on now is the image generation. I generated them locally here: 9287e5c
But as you can see here, they are failing in ci: https://app.circleci.com/pipelines/github/plotly/plotly.js/12822/workflows/a9ae7478-acf1-4d50-817c-3e7fbb34e8c3/jobs/286792/artifacts
One notable strangeness is that they look good in my commit, but look strange in the ci artifacts. One example:
Thanks again for all your help with this PR!

Okay, I see what is happening now, @emilykl !

I was looking at the diff, not the raw image that CI generates. Here is an example:

CI generates the following image for diff-quiver_simple.png:

And corresponding diff for the same image:

So, maybe something is different with my local versioning for dependencies?

My only fear is that if I swap in the raw images that CI generates, that it is actually wrong and/or could break or flake in the future. Hmm 🤔

Thanks again for everything, and I hope you have a splendid day!

@emilykl I got it 🥳 I hadn't worked with the baselines before, so took a little getting used to.

So excited! I will clean up some commits in the morning.

Thanks again!