ravetools (version 0.3.2)

catmull_rom_3d: Catmull-Rom 3D Spline Curve

Description

Creates a smooth Catmull-Rom spline curve through a set of 3D key points.

Usage

catmull_rom_3d(
  points,
  curve_type = c("centripetal", "chordal", "uniform"),
  tension = 0.5,
  closed = FALSE
)

Value

An object of class "ravetools_curve" (a list) with the following elements:

points

The input key-point matrix (\(n \times 3\)).

curve_type

Character, the parameterization type.

tension

Numeric, the tension value (relevant for "uniform" only).

closed

Logical, whether the curve is closed.

get_point

A function(t) that accepts a scalar t in \([0, 1]\) and returns a named numeric vector on the curve.

get_points

A function(n) that returns an \(n \times 3\) matrix of n evenly spaced points along the curve, with column names "x", "y", "z".

get_closest_t

A function(query, coarse_n = 200L) that, given a 3-element numeric vector query (x, y, z), returns a list with elements t (the parameter value in \([0, 1]\) of the nearest point), point (the closest point on the curve as a named numeric vector), and distance (Euclidean distance from query to the curve). The search uses coarse_n uniform samples for an initial bracket followed by scalar optimization.

t_keypoints

Numeric vector of length \(n\) with the t parameter value where each key point lies on the curve. First element is always 0, last is always 1.

segment_lengths

Numeric vector of length \(n-1\) (open curve) or \(n\) (closed curve) containing the arc length of each spline segment, estimated by numerical integration.

Arguments

points

numeric matrix with at least 2 rows and exactly 3 columns (x, y, z), giving the key (control) points through which the curve passes.

curve_type

character; One of "centripetal" (default), "chordal", or "uniform". "centripetal" uses \(\alpha = 0.5\) (square-root of chord length), "chordal" uses \(\alpha = 1\) (chord length), and "uniform" is the classic formulation controlled by tension.

tension

numeric scalar in \([0, 1]\); tangent scaling factor used only when curve_type = "uniform". At 0.5 (default) the curve matches the standard Catmull-Rom formulation.

closed

logical; if TRUE the curve closes on itself by connecting the last point back to the first. Default is FALSE.

See Also

print.ravetools_curve, plot.ravetools_curve

Examples

pts <- matrix(c(
  -33.0534, -10.6213, -21.8328,
  -34.7526, -25.5089, -14.5390,
  -41.2002, -10.4606, -22.0032,
  -46.4717, -10.3567, -22.1134,
  -51.7431, -10.2528, -22.2237,
  -57.0146, -10.1488, -22.3339,
  -62.2860, -10.0449, -22.4442,
  -67.5575,  -9.9410, -22.5544
), ncol = 3, byrow = TRUE)

curve <- catmull_rom_3d(pts)
print(curve)

# Sample 100 evenly spaced points along the curve
smooth <- curve$get_points(100)
head(smooth)

# Evaluate the curve at t = 0.5 (midpoint)
curve$get_point(0.5)

# get closest point on curve
curve$get_closest_t(c(-49, -10, -22))

plot(curve, use_rgl = FALSE)