## CatmullRom.jl

Centripetal Catmull-Rom curves for interpoint traversal
Author JeffreySarnoff
Popularity
12 Stars
Updated Last
8 Months Ago
Started In
June 2018

# CatmullRom.jl

## General Perspective

Catmull-Rom splines are a workhorse of computer graphics. Using the centripetal parameterization, they become a very handy general purpose tool for fast, attractive curvilinear blending. Often, they give interpoint "motion" a naturalistic feel.

Cem Yuksel's Research

Parameterization and Applications of Catmull-Rom Curves

Centripetal Catmull-Rom Pathmaking optional arguments
`catmullrom( points )` `catmullrom( points, n_segments_between_neighbors )`
`catmullrom_by_arclength( points )` `catmullrom_by_arclength( points, (min_segments, max_segments) )`

## Uniform Intermediation

There are two ways to connect path-adjacent points using Centripetal Catmull-Rom machinery. The most often used method places a given number of curvilinear waypoints between each adjacent pair from the original points. All neighbors become connected by that given number of intermediating places. Though the places differ, the proportional advancing between abcissae is consistent. Trying a few different values may help you visualize the significance that is of import.

``````crpoints = catmullrom( points )

crpoints = catmullrom( points, n_segments_between_neighbors )
``````

## Arclength Relative Allocation

When the points' coordinates are spread differently along distinct axes, the interpoint distances along one coordinate have a very different nature from the intercoordinate spreads along another coordinate axis. The distances separating adjacent point pairs may vary substantively. This is particularly true when working in higher dimensional regions of an orthonormal coordinate space. One may use more intermediating placements between adjacent points that are relatively far apart, and fewer between adjacent points that are in close relative proximity.

``````crpoints = catmullrom_by_arclength( points )

crpoints = catmullrom_by_arclength( points, (min_segments_between_neighbors, max_segments_between_neighbors) )
``````

``````using CatmullRom, Plots

result = catmullrom(points, n_segments_per_pair)    # your points, how many new points to place between adjacents
# result is a vector of coordinates, e.g. [xs, ys, zs]
plot(result...,)
``````

When your points have nonuniform separation, or separation extents vary with coordinate dimension, it is of benefit to allocate more of the new inbetween points where there are relatively greater distances between your adjacent points. The most appropriate measure for comparison and weighting is interpoint arclength. This package implements a well-behaved approximation to Catmull-Rom arclengths appropriate to the centripetal parameterization. You can use this directly.

``````using CatmullRom, Plots

result = catmullrom_by_arclength(points) # result is a vector of coordinates, e.g. [xs, ys, zs]

result = catmullrom_by_arclength(points, (atleast_min_segments, atmost_max_segments))
# min, max pertain to each pair of neighboring points
xs, ys = result
plot(xs, ys)
``````

## Open and Closed Curves

You may work with open paths or with closed paths. A closed path is a point sequence where the first point and the last point have identical coordinantes. To ensure that a sequence of points is properly closed, use `close_seq!(<sequence>)`. If the last point is the same as the first it does nothing. If the last has only tiny differences from the first, a copy of the first point overwrites the last. Otherwise, a copy of the first point is postpended to the sequence. The sequence is altered in place. It is good practice to use this function with closed curves.

``````close_seq!( points )            # this is the only function that may change some part of your data
# any change is limited to copying the first point into the last
points = close_seq!( points )   # (the same thing)
``````

## Points along a path

A sequence of 2D, 3D .. nD points is required. There is no limit on the number of coordinate dimensions. The first coordinate of each point become the abcissae (e.g. the `x` coordinate values). The second [, third etc.] become [successive] ordinates (e.g. the `ys`, `zs` ...).

Every point in a givne sequence must has the same number of constiuent coordinates. Coordinates are considered to be values along orthonormal axes. All ordinate axes are fitted with respect to the same abcissae. So, the arcs that connect successive `y`s are arcs hewn from a succession of `(x_i, y_i)` ordered pairs and the arcs connecting successive `z`s are arcs hewn from a succession of `(x_i, z_i)` ordered pairs. It is easy to work with other axial pairings. To generate arcs using the sequence of `(y_i, z_i)` pairs: `ys_zs = catmullrom( collect(zip(ys, zs)) )`.

The point sequence itself may be provided as a vector of points or as a tuple of points.

Type used for a Point example coordinates are retrievable you support
small vector [1.0, 3.5 ] coord(point, i) = point[i] builtin
small tuple (1.0, 3.5) coord(point, i) = point[i] builtin
StaticVector SVector( 1.0, 3.5 ) coord(point, i) = point[i] builtin
NamedTuple (x = 1.0, y = 3.5 ) coord(point, i) = point[i] builtin
struct Point(1.0, 3.5) coord(point, i) = point[i] getindex
``````struct Point{T}
x::T
y::T
z::T
end

function Base.getindex(point::Point{T}, i::Integer) where T
if i == 1
point.x
elseif i == 2
point.y
elseif i == 3
point.z
else
throw(DomainError("i must be 1, 2, or 3 (not \$i)"))
end
end
``````

## Centripetal Catmull-Rom Examples 𝓪

### the first and last points are special from Wikipedia Catmull-Rom splines over two points are made with their neighbors. A new point preceeds your first and another follows your last.
By appending new outside points, the generated curve includes your extremals.
This just happens with the internal flow. To do it yourself use `catmullrom(points, extend=false)`.

## hints

• If your points are disaggregated (e.g. all the `xs` in vec_of_xs, all the `ys` in vec_of_ys)

• aggregate them this way `points = collect(zip(xs, ys, zs))`
• Often, abcissae (`xs`) are given in an ascending or in a descending sequence

• `x[i-1] < x[i] < x[i+1]` or `x[i-1] > x[i] > x[i+1]`
• With closed curves, expect one of these adjacency triplets

• `x[i-1] < x[i] > x[i+1]` or `x[i-1] > x[i] < x[i+1]`

## also consider

Interpolations.jl

## references

Parameterization and Applications of Catmull-Rom Curves

The Centripetal Catmull-Rom Spline

Catmull-Rom spline without cusps or self-intersections

### Required Packages

View all packages

### Used By Packages

No packages found.