The cl-catmull-rom-spline Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-catmull-rom-spline Reference Manual

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.

Table of Contents


1 Introduction

CL-Catmull-Rom-Spline

Build Status

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:

example.gif

System Outline

: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.

License

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.

Contributing

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.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-catmull-rom-spline

Catmull-Rom Spline

Author

Kevin Secretan <github@thejach.com>

License

Public Domain

Version

0.1.0

Source

cl-catmull-rom-spline.asd.

Child Component

spline.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


3.1.1 cl-catmull-rom-spline/cl-catmull-rom-spline.asd

Source

cl-catmull-rom-spline.asd.

Parent Component

cl-catmull-rom-spline (system).

ASDF Systems

cl-catmull-rom-spline.


3.1.2 cl-catmull-rom-spline/spline.lisp

Source

cl-catmull-rom-spline.asd.

Parent Component

cl-catmull-rom-spline (system).

Packages

cl-catmull-rom-spline.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-catmull-rom-spline

Source

spline.lisp.

Nicknames
  • com.thejach.cl-catmull-rom-spline
  • cr-spline
Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Generic functions

Generic Function: add-knot (spline knot)

Given a knot as a sequence pair representing an x,y point, add it to this spline’s control knots.

Package

cl-catmull-rom-spline.

Source

spline.lisp.

Methods
Method: add-knot ((spline spline) (knot sequence))
Generic Function: next-point (spline)

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.

Package

cl-catmull-rom-spline.

Source

spline.lisp.

Methods
Method: next-point ((spline spline))
Generic Function: reset (spline)

Reinitializes the spline state so the next call to next-poin will return the beginning point of the spline.

Package

cl-catmull-rom-spline.

Source

spline.lisp.

Methods
Method: reset ((spline spline))
Generic Function: scale (spline factor)

Multiplies each knot’s x and y values by the scale factor.

Package

cl-catmull-rom-spline.

Source

spline.lisp.

Methods
Method: scale ((spline spline) (factor real))

5.1.2 Classes

Class: spline

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.

Package

cl-catmull-rom-spline.

Source

spline.lisp.

Direct methods
Direct slots
Slot: knots
Initform

(make-array 1 :fill-pointer 0 :adjustable t)

Readers

knots.

Writers

(setf knots).

Slot: coeffs
Initform

(make-array 1 :fill-pointer 0 :adjustable t)

Readers

coeffs.

Writers

(setf coeffs).

Slot: knots-count
Initform

0

Readers

knots-count.

Writers

(setf knots-count).

Slot: current-knot
Initform

1

Readers

cur-knot.

Writers

(setf cur-knot).

Slot: current-t
Initform

0.0

Readers

cur-t.

Writers

(setf cur-t).

Slot: delta-t

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.

Initform

0.1

Initargs

:dt

Readers

dt.

Writers

(setf dt).

Slot: endpoints-computed?
Readers

endpoints-computed?.

Writers

(setf endpoints-computed?).

Slot: coeffs-computed?
Readers

coeffs-computed?.

Writers

(setf coeffs-computed?).


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Macros

Macro: knot-i-x (spline i)
Package

cl-catmull-rom-spline.

Source

spline.lisp.

Macro: knot-i-y (spline i)
Package

cl-catmull-rom-spline.

Source

spline.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Function: coeff->idx (coeff)
Package

cl-catmull-rom-spline.

Source

spline.lisp.

Function: coeff-x (spline coeff)
Package

cl-catmull-rom-spline.

Source

spline.lisp.

Function: coeff-y (spline coeff)
Package

cl-catmull-rom-spline.

Source

spline.lisp.

Function: compute-coefficients (spline)

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.

Package

cl-catmull-rom-spline.

Source

spline.lisp.

Function: dot-product (m1 m2)
Package

cl-catmull-rom-spline.

Source

spline.lisp.

Function: set-coeffs (spline i ax ay bx by cx cy dx dy)
Package

cl-catmull-rom-spline.

Source

spline.lisp.


5.2.3 Generic functions

Generic Reader: coeffs (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: coeffs ((spline spline))

automatically generated reader method

Source

spline.lisp.

Target Slot

coeffs.

Generic Writer: (setf coeffs) (object)
Package

cl-catmull-rom-spline.

Methods
Writer Method: (setf coeffs) ((spline spline))

automatically generated writer method

Source

spline.lisp.

Target Slot

coeffs.

Generic Reader: coeffs-computed? (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: coeffs-computed? ((spline spline))

automatically generated reader method

Source

spline.lisp.

Target Slot

coeffs-computed?.

Generic Writer: (setf coeffs-computed?) (object)
Package

cl-catmull-rom-spline.

Methods
Writer Method: (setf coeffs-computed?) ((spline spline))

automatically generated writer method

Source

spline.lisp.

Target Slot

coeffs-computed?.

Generic Function: compute-endpoints (spline)
Package

cl-catmull-rom-spline.

Methods
Method: compute-endpoints ((spline spline))

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

Source

spline.lisp.

Generic Reader: cur-knot (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: cur-knot ((spline spline))

automatically generated reader method

Source

spline.lisp.

Target Slot

current-knot.

Generic Writer: (setf cur-knot) (object)
Package

cl-catmull-rom-spline.

Methods
Writer Method: (setf cur-knot) ((spline spline))

automatically generated writer method

Source

spline.lisp.

Target Slot

current-knot.

Generic Reader: cur-t (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: cur-t ((spline spline))

automatically generated reader method

Source

spline.lisp.

Target Slot

current-t.

Generic Writer: (setf cur-t) (object)
Package

cl-catmull-rom-spline.

Methods
Writer Method: (setf cur-t) ((spline spline))

automatically generated writer method

Source

spline.lisp.

Target Slot

current-t.

Generic Reader: dt (object)
Generic Writer: (setf dt) (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: dt ((spline spline))
Writer Method: (setf dt) ((spline spline))

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.

Source

spline.lisp.

Target Slot

delta-t.

Generic Reader: endpoints-computed? (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: endpoints-computed? ((spline spline))

automatically generated reader method

Source

spline.lisp.

Target Slot

endpoints-computed?.

Generic Writer: (setf endpoints-computed?) (object)
Package

cl-catmull-rom-spline.

Methods
Writer Method: (setf endpoints-computed?) ((spline spline))

automatically generated writer method

Source

spline.lisp.

Target Slot

endpoints-computed?.

Generic Reader: knots (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: knots ((spline spline))

automatically generated reader method

Source

spline.lisp.

Target Slot

knots.

Generic Writer: (setf knots) (object)
Package

cl-catmull-rom-spline.

Methods
Writer Method: (setf knots) ((spline spline))

automatically generated writer method

Source

spline.lisp.

Target Slot

knots.

Generic Reader: knots-count (object)
Package

cl-catmull-rom-spline.

Methods
Reader Method: knots-count ((spline spline))

automatically generated reader method

Source

spline.lisp.

Target Slot

knots-count.

Generic Writer: (setf knots-count) (object)
Package

cl-catmull-rom-spline.

Methods
Writer Method: (setf knots-count) ((spline spline))

automatically generated writer method

Source

spline.lisp.

Target Slot

knots-count.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   K   M   N   R   S  
Index Entry  Section

(
(setf coeffs): Private generic functions
(setf coeffs): Private generic functions
(setf coeffs-computed?): Private generic functions
(setf coeffs-computed?): Private generic functions
(setf cur-knot): Private generic functions
(setf cur-knot): Private generic functions
(setf cur-t): Private generic functions
(setf cur-t): Private generic functions
(setf dt): Private generic functions
(setf dt): Private generic functions
(setf endpoints-computed?): Private generic functions
(setf endpoints-computed?): Private generic functions
(setf knots): Private generic functions
(setf knots): Private generic functions
(setf knots-count): Private generic functions
(setf knots-count): Private generic functions

A
add-knot: Public generic functions
add-knot: Public generic functions

C
coeff->idx: Private ordinary functions
coeff-x: Private ordinary functions
coeff-y: Private ordinary functions
coeffs: Private generic functions
coeffs: Private generic functions
coeffs-computed?: Private generic functions
coeffs-computed?: Private generic functions
compute-coefficients: Private ordinary functions
compute-endpoints: Private generic functions
compute-endpoints: Private generic functions
cur-knot: Private generic functions
cur-knot: Private generic functions
cur-t: Private generic functions
cur-t: Private generic functions

D
dot-product: Private ordinary functions
dt: Private generic functions
dt: Private generic functions

E
endpoints-computed?: Private generic functions
endpoints-computed?: Private generic functions

F
Function, coeff->idx: Private ordinary functions
Function, coeff-x: Private ordinary functions
Function, coeff-y: Private ordinary functions
Function, compute-coefficients: Private ordinary functions
Function, dot-product: Private ordinary functions
Function, set-coeffs: Private ordinary functions

G
Generic Function, (setf coeffs): Private generic functions
Generic Function, (setf coeffs-computed?): Private generic functions
Generic Function, (setf cur-knot): Private generic functions
Generic Function, (setf cur-t): Private generic functions
Generic Function, (setf dt): Private generic functions
Generic Function, (setf endpoints-computed?): Private generic functions
Generic Function, (setf knots): Private generic functions
Generic Function, (setf knots-count): Private generic functions
Generic Function, add-knot: Public generic functions
Generic Function, coeffs: Private generic functions
Generic Function, coeffs-computed?: Private generic functions
Generic Function, compute-endpoints: Private generic functions
Generic Function, cur-knot: Private generic functions
Generic Function, cur-t: Private generic functions
Generic Function, dt: Private generic functions
Generic Function, endpoints-computed?: Private generic functions
Generic Function, knots: Private generic functions
Generic Function, knots-count: Private generic functions
Generic Function, next-point: Public generic functions
Generic Function, reset: Public generic functions
Generic Function, scale: Public generic functions

K
knot-i-x: Private macros
knot-i-y: Private macros
knots: Private generic functions
knots: Private generic functions
knots-count: Private generic functions
knots-count: Private generic functions

M
Macro, knot-i-x: Private macros
Macro, knot-i-y: Private macros
Method, (setf coeffs): Private generic functions
Method, (setf coeffs-computed?): Private generic functions
Method, (setf cur-knot): Private generic functions
Method, (setf cur-t): Private generic functions
Method, (setf dt): Private generic functions
Method, (setf endpoints-computed?): Private generic functions
Method, (setf knots): Private generic functions
Method, (setf knots-count): Private generic functions
Method, add-knot: Public generic functions
Method, coeffs: Private generic functions
Method, coeffs-computed?: Private generic functions
Method, compute-endpoints: Private generic functions
Method, cur-knot: Private generic functions
Method, cur-t: Private generic functions
Method, dt: Private generic functions
Method, endpoints-computed?: Private generic functions
Method, knots: Private generic functions
Method, knots-count: Private generic functions
Method, next-point: Public generic functions
Method, reset: Public generic functions
Method, scale: Public generic functions

N
next-point: Public generic functions
next-point: Public generic functions

R
reset: Public generic functions
reset: Public generic functions

S
scale: Public generic functions
scale: Public generic functions
set-coeffs: Private ordinary functions

Jump to:   (  
A   C   D   E   F   G   K   M   N   R   S