catmull_rom_3d: Catmull-Rom 3D Spline Curve

In ravetools: Signal and Image Processing Toolbox for Analyzing Intracranial Electroencephalography Data

⁠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
)

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.

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.

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)

ravetools documentation built on May 23, 2026, 9:10 a.m.