Add `virtualship animate` CLI Command for Cruise Visualization

[iuryt]

Description

This idea originated from discussions around the VirtualShip website redesign (#168 ), where we considered embedding an animation to visually demonstrate how a virtual cruise works. We’d like to evolve that concept into a CLI feature within the core VirtualShip package to support both pre-run planning and post-run analysis.

---

Proposed CLI Modes

I propose two modes of operation for the animate feature:

1. Preview Mode (pre-run)

virtualship --preview animate

• Uses only the cruise schedule and mission plan
• Shows planned ship path, station locations, and deployment points (e.g., drifter drops)
• Useful for validating cruise plans before simulation

2. Results Mode (post-run)

virtualship animate

• Uses data from a completed run (e.g., particle trajectories, collected profiles)
• Animates actual trajectories and observed deployments
• Useful for presenting outcomes and full cruise visualizations

---

Why This Feature?

• Helps users verify and refine cruise plans before running simulations
• Supports teaching workflows and presentations
• Bridges planning and analysis phases visually

---

Implementation Ideas

• Make static plots for hour or so of the region of interest and the position of the instruments
• animate it with ffmpeg
• Add an inset globe map with the location of the region of interest
• Maybe "remove" from the plot "old" deployments by a defined time (e.g. 12 h)? This might help to reduce the clutter.
• Maybe show a tail for drifter trajectories?
• Maybe an interactive HTML visualization (e.g., with Leaflet, Plotly, or Bokeh)
• Instrument icons could be used to represent different types of deployments (e.g., CTD, XBT, Argo, drifters), making the animation easier to interpret at a glance.
• What would be the default basemap? We could plot the bathymetry or
• It would be nice to have that in a way people could call the function in their own code and add elements as needed.
• How should we deal with instruments that sink and drift, like Argo floats? I thought we could change the color depending on whether the instrument is profiling or drifting.
• How do we organize outputs within the VirtualShip run directory structure?
• Would users benefit from being able to toggle visibility of certain instruments in the animation? This could be something for a future implementation.

[j-atkins]

Sounds great. I'd be happy to help, let me know if you want a hand with anything!

[iuryt]

What you think about the following icons for the ship, CTD, XBT and Argo profiles? The ship was inspired on R/V Neil Armstrong.

[erikvansebille]

Nice ones, @iuryt! We can also use the icons from the VirtualShipParcels logo itself?

https://github.com/OceanParcels/virtualship_website/blob/Icons-file/public/virtualship-assets/IconsVirtualShip.svg

Perhaps @VeckoTheGecko can help clean them up a bit (make the ship front transparent)? I uploaded the file in #23

[iuryt]

Thanks! I can help making the ship transparent. Do you think that it is better to use the front view icon instead of a top view that rotates with the moving direction? I tried to leave some space in the center of the icon to make sure we could see the current deployment. For example, at the CTD stations there will be the CTD icon on top of the ship icon. Let me know what you think.

[erikvansebille]

AH sorry, I didn't realise that the top-view was useful in animating rotation of the ship along the path; that's actually a really cool idea. So yes, then go ahead and use these icons above. The ship is still in the same style as the icon in the logo.

Perhaps use a version of the more elongated Argo float that I tried to draw up, though?

For drifters, we typically use this svg:

[VeckoTheGecko]

Hey @iuryt , excuse my late response to this issue. I think this sounds like a great idea. I think it would be a good idea to start with the preview as that would be simpler than the post analysis and would allow us to have a starting point to build off of. Some things I'm wondering are:

• What sort of dependencies would we need for this feature?
  • Would these dependencies be optional dependencies, or be installed by default?

Perhaps Streamlit would be a nice way to create a dashboard which can be used. Have you used that before?

Lots of great ideas here, if we can resolve that into a more concrete item list for this feature I think that would be really helpful (if they have preferences on what this feature looks like, perhaps @ammedd or @erikvansebille could have input on that).

[iuryt]

I think that the first PR could be with the schedule only, to make it simple.
We can make it in a way that it runs through the browser with streamlit and it automatically updates with the changes in the schedule, which will be very useful for cruise adjustments. Do we want to rely on the MFP cruise planning web tool for the future, or could we even evolve this idea into a tool for the planning itself? That is probably in the long term (another PR). If we want to also make this into a cruise planning, we could export the schedule to coordinates that could be imported to MFP if the user wants to use that to request a ship.

Anyway, one question I have is how to deal with the time variation in interactive plotting. Should we have a time slider that is set by default at the end of the cruise to start by showing the whole survey, which the user can play as a video? What are your suggestions?

I also want to add each feature as a layer that can be toggled on and off. This is very useful, particularly when we have multiple instruments deployed in the same waypoint. We can also add a feature that expands the features in a waypoint on hover (something like the example below, but prettier), but I am not sure how to do that with streamlit.

Also. Since this issue is becoming more than a simple implementation. Should we convert this into a discussion, or is it fine leaving here?

[erikvansebille]

Thanks @iuryt for this comment. Quick responses below

Do we want to rely on the MFP cruise planning web tool for the future, or could we even evolve this idea into a tool for the planning itself?

I think that we don't want to create our own planning tool anytime soon. The MFP portal is widely used in (European) oceanographic institutes, so adds a layer of realism to the tool; which is actually a huge benefit from the learning perspective

Should we have a time slider that is set by default at the end of the cruise to start by showing the whole survey, which the user can play as a video?
Yes, could be nice.

Should we convert this into a discussion
Yes, good idea. I'll do that