vectorialcalculus (version 1.0.5)

tangent3d: Unit tangent vectors along a 3D parametric curve

Description

Computes numerical unit tangent vectors of a three-dimensional parametric curve at selected values of the parameter. The curve is defined by three functions that give its coordinate components. For each evaluation point, the first derivative of the curve is approximated numerically and then normalized to obtain a unit tangent direction.

Usage

tangent3d(
  X,
  Y,
  Z,
  a,
  b,
  t_points,
  h = 1e-04,
  plot = FALSE,
  n_samples = 400,
  vec_scale = NULL,
  vec_factor = 1,
  curve_line = list(color = "blue", width = 2, dash = "solid"),
  T_line = list(color = "red", width = 5, dash = "solid"),
  show_curve = TRUE,
  show_points = TRUE,
  point_marker = list(color = "black", size = 3, symbol = "circle"),
  scene = list(aspectmode = "data", xaxis = list(title = "x(t)"), yaxis = list(title =
    "y(t)"), zaxis = list(title = "z(t)")),
  bg = list(paper = "white", plot = "white"),
  tol = 1e-10
)

Value

A tibble with columns t, x, y, z, Tx, Ty and Tz, where the last three columns contain the components of the unit tangent vector at each evaluation point.

Arguments

X

Function returning the x coordinate of the curve as a function of the parameter t.

Y

Function returning the y coordinate of the curve as a function of the parameter t.

Z

Function returning the z coordinate of the curve as a function of the parameter t.

a

Lower endpoint of the parameter interval.

b

Upper endpoint of the parameter interval.

t_points

Numeric vector of parameter values at which the tangent direction is evaluated and optionally plotted.

h

Step size for centered finite-difference approximations.

plot

Logical; if TRUE, shows a 3D plotly visualization of the curve and tangent segments.

n_samples

Number of points used to sample and display the curve in the 3D plot.

vec_scale

Base length used for the tangent segments. If NULL, it is estimated as a small fraction of the overall size of the sampled curve.

vec_factor

Multiplicative factor applied to vec_scale to control the visual size of the tangent segments.

curve_line

List with plotly style options for drawing the base curve.

T_line

List with plotly style options for the tangent segments.

show_curve

Logical; if TRUE, the base curve is included in the plot.

show_points

Logical; if TRUE, the evaluation points are marked in the plot.

point_marker

List with plotly marker options for the evaluation points.

scene

List with 3D scene settings for plotly.

bg

Background colors for the figure, usually a list with entries such as paper and plot.

tol

Numeric tolerance for detecting situations in which the first derivative is too small to define a stable tangent direction.

Details

For every element of t_points, the function:

• computes a centered finite-difference approximation of the first derivative of the curve,

• evaluates the magnitude of that derivative,

• divides the derivative by its magnitude to obtain a unit vector pointing in the direction of motion of the curve at that point.

If the magnitude of the first derivative is extremely small at a given parameter value, the tangent direction becomes numerically unstable; in such cases, the function returns NA for the corresponding components and may emit a diagnostic message.

Optionally, the curve and the associated tangent directions can be shown in an interactive 3D plot using plotly. Short line segments representing the tangent direction can be anchored at each evaluation point. The sampled curve, the reference points and the tangent segments may be displayed or hidden independently.

Examples

X <- function(t) t*cos(t)
Y <- function(t) t*sin(3*t)
Z <- function(t) t
tangent3d(X, Y, Z, a = 0, b = 2*pi, t_points = c(pi/3, pi, 5*pi/3))