% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/curve-catmull.R
\name{catmull_rom_3d}
\alias{catmull_rom_3d}
\title{\verb{Catmull-Rom} 3D Spline Curve}
\usage{
catmull_rom_3d(
  points,
  curve_type = c("centripetal", "chordal", "uniform"),
  tension = 0.5,
  closed = FALSE
)
}
\arguments{
\item{points}{numeric matrix with at least 2 rows and exactly 3 columns
(\code{x}, \code{y}, \code{z}), giving the key (control) points through
which the curve passes.}

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

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

\item{closed}{logical; if \code{TRUE} the curve closes on itself by
connecting the last point back to the first. Default is \code{FALSE}.}
}
\value{
An object of class \code{"ravetools_curve"} (a list) with the
  following elements:
\describe{
  \item{\code{points}}{The input key-point matrix (\eqn{n \times 3}).}
  \item{\code{curve_type}}{Character, the parameterization type.}
  \item{\code{tension}}{Numeric, the tension value (relevant for
    \code{"uniform"} only).}
  \item{\code{closed}}{Logical, whether the curve is closed.}
  \item{\code{get_point}}{A \code{function(t)} that accepts a scalar
    \code{t} in \eqn{[0, 1]} and returns a named numeric vector
    on the curve.}
  \item{\code{get_points}}{A \code{function(n)} that returns an
    \eqn{n \times 3} matrix of \code{n} evenly spaced points along the
    curve, with column names \code{"x"}, \code{"y"}, \code{"z"}.}
  \item{\code{get_closest_t}}{A \code{function(query, coarse_n = 200L)}
    that, given a 3-element numeric vector \code{query} (\code{x}, \code{y},
    \code{z}), returns a list with elements \code{t} (the parameter value in
    \eqn{[0, 1]} of the nearest point), \code{point} (the closest point on
    the curve as a named numeric vector), and \code{distance} (Euclidean
    distance from \code{query} to the curve).  The search uses
    \code{coarse_n} uniform samples for an initial bracket followed by
    scalar optimization.}
  \item{\code{t_keypoints}}{Numeric vector of length \eqn{n} with the
    \code{t} parameter value where each key point lies on the curve.
    First element is always \code{0}, last is always \code{1}.}
  \item{\code{segment_lengths}}{Numeric vector of length \eqn{n-1} (open
    curve) or \eqn{n} (closed curve) containing the arc length of each
    spline segment, estimated by numerical integration.}
}
}
\description{
Creates a smooth \verb{Catmull-Rom} spline curve through a set of 3D key points.
}
\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)

}
\seealso{
\code{\link{print.ravetools_curve}},
  \code{\link{plot.ravetools_curve}}
}
