Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-catmull-rom-spline Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 03:33:10 2022 GMT+0.
Next: Systems, Previous: The cl-catmull-rom-spline Reference Manual, Up: The cl-catmull-rom-spline Reference Manual [Contents][Index]
This is a Common Lisp library implementing Catmull-Rom splines as described by this paper: http://algorithmist.net/docs/catmullrom.pdf
Splines provide a way to designate an ordered list of control points (knots) in a 2D plane and find a "smooth" path that travels through or around the points. CR splines have particularly nice properties for game applications:
:cl-catmull-rom-spline
is the main library code. The typical usage is to
construct a new Spline object, add some knots, then repeatedly ask for the next
point along the spline path.
:cl-catmull-rom-spline/test
contains a few unit tests.
:cl-catmull-rom-spline/example
contains a small SDL1-backed graphical example
to show off adding knots and animating an object following the path. Simply
load the system and execute (spline-example:launch)
.
Note that testing on an Ubuntu 16 system, even after apt-getting libsdl1.2-dev,
this system was raising an error on load trying to find libSDL_gfx.
Continuing the load and launching still seemed to work anyway, though. But
it's also resolveable by apt-getting libsdl-gfx1.2-dev.
This library is free software. The author disclaims copyright to this project's source code. All files in this project, unless explicitly stated otherwise, are in the public domain and distributed without any warranty. If you live in a country that does not recognize grants to the public domain, you may consider this licensed under the CC0.
Though responses may not be very quick, contributions from pull requests or emailed patches are welcome, as are drive-by code reviews or reported issues. If you don't agree to have the changes released in the public domain, please mark them explicitly otherwise.
Next: Files, Previous: Introduction, Up: The cl-catmull-rom-spline Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Catmull-Rom Spline
Kevin Secretan <github@thejach.com>
Public Domain
0.1.0
spline.lisp (file).
Next: Packages, Previous: Systems, Up: The cl-catmull-rom-spline Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: cl-catmull-rom-spline/spline.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
cl-catmull-rom-spline (system).
Previous: cl-catmull-rom-spline/cl-catmull-rom-spline.asd, Up: Lisp [Contents][Index]
cl-catmull-rom-spline (system).
Next: Definitions, Previous: Files, Up: The cl-catmull-rom-spline Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The cl-catmull-rom-spline Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Classes, Previous: Public Interface, Up: Public Interface [Contents][Index]
Given a knot as a sequence pair representing an x,y point, add it to this spline’s control knots.
For the current segment between knots, calculates the next point and
returns it as a two element vector.
If the spline contains fewer than 3 knots, an error signal is raised.
This method returns two extra multiple values for special conditions:
* When the next point has reached or would reach beyond the final knot,
#(0.0 0.0) is returned along with a second value set to T.
Otherwise this second value is nil.
* When the returned point is the final point of a segment, a third value will be T.
Reinitializes the spline state so the next call to next-poin will return the beginning point of the spline.
Multiplies each knot’s x and y values by the scale factor.
Previous: Generic functions, Up: Public Interface [Contents][Index]
Catmull-Rom splines are composed of a number of knots
(at least 3) with a piecewise path computed between
each knot, with the overall path from the first to
last knot appearing smooth. Each knot will be crossed
along the path.
Point: two-element vector representing an (x, y) coordiante.
Knots: control points determining the shape of the complete spline path.
Spline segments: the path between knots. Can be thought of as functions of time
path(t) : R -> point, from t=0 to t=1.
path(0) is the first knot in the segment, path(1) is the last knot.
(make-array 1 :fill-pointer 0 :adjustable t)
(make-array 1 :fill-pointer 0 :adjustable t)
0
1
0.0
By default this 0.1 dt means that for the first
segment, it will take 11 calls (t goes from =0 to =1)
to complete, but every other segment will start at t=0.1
to avoid repeating the knot value at t=0 and thus take
10 calls to go through. Use either shorter point distances,
or a lower dt to have smoother interpolation.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Internals, Up: Internals [Contents][Index]
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
A point on a segment can be found by applying the equation
p(t) = at^3 + bt^2 + ct + d
with coeffs a, b, c, d. The coeffs are computed below,
with e.g. a_x = 1/2(-x_{i-1} + 3x_i - 3_x{i+1} + x_{i+2})
Note the basis matrix for cardinal spline coeffs is:
[[-a 2-a a-2 a]
[2a a-3 3-2a -a]
[-a 0 a 0]
[0 1 0 0]]
where a is the spline ’tension’. As a approaches 1, the bend at each knot is less.
Catmull-Rom splines typically use the value of 0.5, we use the same.
Previous: Ordinary functions, Up: Internals [Contents][Index]
Should be called after all knots have been added. Called automatically by next-point if user forgot.
Once the user-facing knots are added, we need to compute two ’true’ auxilliary endpoints for the whole path.
Currently this is done by duplicating the the first and last knots, though this can cause kinking.
A future approach is to use reflection, which can still cause pinching but may be better.
Of course, they can be set manually if needed. (Consider subclassing rather than direct knot access.)
By default this 0.1 dt means that for the first
segment, it will take 11 calls (t goes from =0 to =1)
to complete, but every other segment will start at t=0.1
to avoid repeating the knot value at t=0 and thus take
10 calls to go through. Use either shorter point distances,
or a lower dt to have smoother interpolation.
Previous: Definitions, Up: The cl-catmull-rom-spline Reference Manual [Contents][Index]
Jump to: | (
A C D E F G K M N R S |
---|
Jump to: | (
A C D E F G K M N R S |
---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
Jump to: | C D E K S |
---|
Jump to: | C D E K S |
---|
Jump to: | C F P S |
---|
Jump to: | C F P S |
---|