Draws a three-dimensional vector field inside a curvilinear volume and overlays a streamline that follows the field, all in a single plotly figure. The streamline is obtained by integrating an ordinary differential equation using a fixed-step Runge-Kutta method of order four (RK4), starting from an initial point.
streamline_and_field3d(
field,
H1,
H2,
G1,
G2,
a,
b,
NX = 8,
NY = 6,
NZ = 6,
p,
t_final,
step,
arrows = c("both", "line", "cone", "none"),
arrow_scale = 0.08,
normalize_bias = 1,
normal_color = "rgba(0,0,0,0.55)",
normal_width = 2,
arrow_color = "#1d3557",
arrow_opacity = 0.95,
arrow_size = 0.35,
traj_color = "#e63946",
traj_width = 5,
traj_markers = TRUE,
traj_marker_size = 2,
scene = list(aspectmode = "data", xaxis = list(title = "x"), yaxis = list(title = "y"),
zaxis = list(title = "z")),
bg = list(paper = "white", plot = "white"),
...
)A list with:
field_points: a data frame with base positions
x, y, z and the magnitude of the field at each point,
field_segments: a data frame with columns
x0, y0, z0, x1, y1, z1 describing the arrow shafts,
traj: a data frame with the streamline data, including
time, coordinates and local speed,
fig: a plotly object containing the combined
field and streamline visualization.
A function representing the vector field. It can be given as
function(x, y, z) or function(x, y, z, t), and must
return a numeric vector of length three c(Fx, Fy, Fz).
Functions of one variable x giving the lower and
upper bounds in the y direction.
Functions of two variables x and y giving
the lower and upper bounds in the z direction.
Numeric endpoints of the interval for x. It is
assumed that b > a.
Integers greater than or equal to one specifying the sampling density of the field in the three parameter directions.
Numeric vector of length three giving the initial point of
the streamline, in the form c(x0, y0, z0).
Final integration time for the streamline. A negative value integrates backward in time.
Step size for the fixed-step RK4 integration. Must be strictly positive.
Character string indicating the arrow mode. Allowed
values are "none", "line", "cone" and
"both".
Global arrow length scale, expressed as a fraction of the largest span of the bounding box.
Numeric saturation bias used in the scaling of the vector norm. Larger values make arrow lengths saturate earlier.
Color of the arrow shafts (line segments).
Numeric width of the arrow shafts.
Color of the arrow heads (cones or chevrons).
Opacity of the arrow heads.
Relative size of the arrow heads with respect to
arrow_scale.
Color of the streamline.
Width of the streamline.
Logical; if TRUE, draws markers along the
streamline.
Size of the markers drawn on the streamline.
List with 3D scene settings for plotly, such as aspect mode and axis titles.
List with background colors for the figure, typically with
entries paper and plot.
Reserved for backward compatibility. Do not use.
The volume is defined by:
an interval for x between a and b,
lower and upper functions for y that depend on x,
lower and upper functions for z that may depend on
both x and y.
The function builds a regular grid in three parameters and maps each
grid point to the physical coordinates (x, y, z) using linear
blends between the corresponding bounds. The vector field is then
evaluated at each of these points to obtain the base positions and
vectors used to draw the arrows.
Arrow lengths are scaled using a saturated version of the vector norm. This means that small magnitudes produce short arrows, whereas very large magnitudes are limited by a bias parameter so that they do not dominate the entire plot. A global scale factor controls the typical arrow length relative to the size of the domain.
The streamline is defined as the trajectory of a particle whose
velocity at each point is given by the vector field evaluated along
the path. The field may optionally depend on time; if the function
field has a time argument, it is used during integration. The
integration runs from time zero up to a final time, with positive or
negative direction depending on the sign of the final time.
The resulting figure combines:
a set of arrows representing the vector field,
a space curve representing the streamline,
optional markers along the streamline and highlighted start and end points.
# \donttest{
H1 <- function(x) -1
H2 <- function(x) 1
G1 <- function(x, y) -0.5
G2 <- function(x, y) 0.5
field <- function(x, y, z) c(-y, x, 0.6)
out <- streamline_and_field3d(
field, H1, H2, G1, G2,
a = -2, b = 2, NX = 10, NY = 8, NZ = 5,
p = c(1, 0, 0), t_final = 2, step = 0.05,
arrows = "both", arrow_scale = 0.12, normalize_bias = 1,
normal_color = "rgba(0,0,0,0.55)", normal_width = 2,
arrow_color = "#1d3557", arrow_opacity = 0.95, arrow_size = 0.4,
traj_color = "#e63946", traj_width = 5, traj_markers = TRUE
)
# }
Run the code above in your browser using DataLab