Vector-field flow analysis
Inspecting fluid or airflow simulation output in three dimensions.
Plotly · Class
go.Streamtube
go.Streamtube creates a 3D flow visualization from six equal-length one-dimensional arrays: positions x, y, z and vector components u, v, w. Optional starts coordinates choose tube origins.
How it works
Streamtube represents flow through a three-dimensional vector field. Supply matching one-dimensional coordinate arrays x, y, z and vector-component arrays u, v, w; optional starts coordinates control where tubes originate, while sizing and display options affect their appearance and count.
Syntax
plotly.graph_objects.Streamtube(arg=None, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
x | 1D array | X coordinates of the vector-field samples. |
y | 1D array | Y coordinates of the vector-field samples. |
z | 1D array | Z coordinates of the vector-field samples. |
u | 1D array | X components of the vector field. |
v | 1D array | Y components of the vector field. |
w | 1D array | Z components of the vector field. |
starts | object with x, y, and z arrays | Optional custom starting-position coordinates. |
maxdisplayed | integer | Maximum number of displayed streamtube segments. |
sizeref | number | Controls tube sizing relative to the field. |
Returns
A Streamtube trace object suitable for inclusion in a Plotly Figure.
Key points
- Use this trace type when the goal is to show three-dimensional flow through a vector field.
- The required inputs separate spatial positions from vector components.
- Custom tube origins are configured with the three starts coordinate attributes.
- Color represents vector magnitude, derived from the u, v, and w components.
- Tube radius communicates local divergence in the vector field.
Common mistakes
- The six required coordinate and vector-component arrays must have equal length.
- Without explicit starts coordinates, Plotly chooses tube origins from the x-z plane at the minimum y value.
Example: Basic 3D streamtube
import plotly.graph_objects as go
fig = go.Figure(go.Streamtube(
x=[0, 1, 0, 1], y=[0, 0, 1, 1], z=[0, 0, 0, 0],
u=[1, 1, 1, 1], v=[0, 0, 0, 0], w=[0, 0, 0, 0],
maxdisplayed=100,
sizeref=0.5
))
fig.show()Creates a 3D streamtube trace from four vector-field samples and displays it.
When to use it
Scientific field visualization
Showing direction, magnitude, and expansion or contraction across sampled spatial data.
Controlled streamtube seeding
Selecting reproducible entry regions for animated or interactive flow exploration.
Interview questions
QWhat data does go.Streamtube require?
A Streamtube trace visualizes flow in a vector field. It requires x, y, and z positions plus u, v, and w vector components, supplied as six equal-length one-dimensional arrays.
Follow-up: How can origins be controlled? Provide starts.x, starts.y, and starts.z to specify custom starting positions; otherwise Plotly derives them from the field.
QWhat do the six core arrays represent?
The x, y, and z arrays locate samples in space, while u, v, and w provide the vector's x-, y-, and z-direction components. Together they define the three-dimensional field used to generate tubes.
Follow-up: Which values influence visual encoding? The vector norm controls color, while local divergence controls tube radius.
QHow are streamtube starting positions determined?
The starts attribute lets the caller choose tube-origin coordinates through starts.x, starts.y, and starts.z. If omitted, default origins are selected from the vector field's x-z plane at minimum y.
Follow-up: Why might explicit starts be useful? They let a visualization emphasize selected regions or make flow entry points reproducible.
Related
plotly.graph_objects.Figure.add_streamtubeplotly.graph_objects.Streamtube.startsplotly.graph_objects.Streamtube.maxdisplayedplotly.graph_objects.Streamtube.sizeref