The cl-catmull-rom-spline Reference Manual

Table of Contents

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 3.0 "Montgomery Scott" on Fri Jun 26 10:04:48 2020 GMT+0.


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

1 Introduction

CL-Catmull-Rom-Spline

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.


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

2 Systems

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


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

2.1 cl-catmull-rom-spline

Author

Kevin Secretan <github@thejach.com>

License

Public Domain

Description

Catmull-Rom Spline

Version

0.1.0

Source

cl-catmull-rom-spline.asd (file)

Component

spline.lisp (file)


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

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


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-catmull-rom-spline.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/cl-catmull-rom-spline-20200325-git/cl-catmull-rom-spline.asd

Systems

cl-catmull-rom-spline (system)


Previous: , Up: Lisp files   [Contents][Index]

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

Parent

cl-catmull-rom-spline (system)

Location

spline.lisp

Packages

cl-catmull-rom-spline

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-catmull-rom-spline

Source

spline.lisp (file)

Nicknames
Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)

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 (file)

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 (file)

Methods
Method: scale (SPLINE spline) (FACTOR real)

Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: knots
Initform

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

Readers

knots (generic function)

Writers

(setf knots) (generic function)

Slot: coeffs
Initform

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

Readers

coeffs (generic function)

Writers

(setf coeffs) (generic function)

Slot: knots-count
Initform

0

Readers

knots-count (generic function)

Writers

(setf knots-count) (generic function)

Slot: current-knot
Initform

1

Readers

cur-knot (generic function)

Writers

(setf cur-knot) (generic function)

Slot: current-t
Initform

0.0

Readers

cur-t (generic function)

Writers

(setf cur-t) (generic function)

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.

Initargs

:dt

Initform

0.1

Readers

dt (generic function)

Writers

(setf dt) (generic function)

Slot: endpoints-computed?
Readers

endpoints-computed? (generic function)

Writers

(setf endpoints-computed?) (generic function)

Slot: coeffs-computed?
Readers

coeffs-computed? (generic function)

Writers

(setf coeffs-computed?) (generic function)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: knot-i-x SPLINE I
Package

cl-catmull-rom-spline

Source

spline.lisp (file)

Macro: knot-i-y SPLINE I
Package

cl-catmull-rom-spline

Source

spline.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: coeff->idx COEFF
Package

cl-catmull-rom-spline

Source

spline.lisp (file)

Function: coeff-x SPLINE COEFF
Package

cl-catmull-rom-spline

Source

spline.lisp (file)

Function: coeff-y SPLINE COEFF
Package

cl-catmull-rom-spline

Source

spline.lisp (file)

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 (file)

Function: dot-product M1 M2
Package

cl-catmull-rom-spline

Source

spline.lisp (file)

Function: set-coeffs SPLINE I AX AY BX BY CX CY DX DY
Package

cl-catmull-rom-spline

Source

spline.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: coeffs OBJECT
Generic Function: (setf coeffs) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: coeffs (SPLINE spline)

automatically generated reader method

Source

spline.lisp (file)

Method: (setf coeffs) NEW-VALUE (SPLINE spline)

automatically generated writer method

Source

spline.lisp (file)

Generic Function: coeffs-computed? OBJECT
Generic Function: (setf coeffs-computed?) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: coeffs-computed? (SPLINE spline)

automatically generated reader method

Source

spline.lisp (file)

Method: (setf coeffs-computed?) NEW-VALUE (SPLINE spline)

automatically generated writer method

Source

spline.lisp (file)

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 (file)

Generic Function: cur-knot OBJECT
Generic Function: (setf cur-knot) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: cur-knot (SPLINE spline)

automatically generated reader method

Source

spline.lisp (file)

Method: (setf cur-knot) NEW-VALUE (SPLINE spline)

automatically generated writer method

Source

spline.lisp (file)

Generic Function: cur-t OBJECT
Generic Function: (setf cur-t) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: cur-t (SPLINE spline)

automatically generated reader method

Source

spline.lisp (file)

Method: (setf cur-t) NEW-VALUE (SPLINE spline)

automatically generated writer method

Source

spline.lisp (file)

Generic Function: dt OBJECT
Generic Function: (setf dt) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: dt (SPLINE spline)
Method: (setf dt) NEW-VALUE (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 (file)

Generic Function: endpoints-computed? OBJECT
Generic Function: (setf endpoints-computed?) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: endpoints-computed? (SPLINE spline)

automatically generated reader method

Source

spline.lisp (file)

Method: (setf endpoints-computed?) NEW-VALUE (SPLINE spline)

automatically generated writer method

Source

spline.lisp (file)

Generic Function: knots OBJECT
Generic Function: (setf knots) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: knots (SPLINE spline)

automatically generated reader method

Source

spline.lisp (file)

Method: (setf knots) NEW-VALUE (SPLINE spline)

automatically generated writer method

Source

spline.lisp (file)

Generic Function: knots-count OBJECT
Generic Function: (setf knots-count) NEW-VALUE OBJECT
Package

cl-catmull-rom-spline

Methods
Method: knots-count (SPLINE spline)

automatically generated reader method

Source

spline.lisp (file)

Method: (setf knots-count) NEW-VALUE (SPLINE spline)

automatically generated writer method

Source

spline.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-catmull-rom-spline.asd: The cl-catmull-rom-spline․asd file
cl-catmull-rom-spline/spline.lisp: The cl-catmull-rom-spline/spline․lisp file

F
File, Lisp, cl-catmull-rom-spline.asd: The cl-catmull-rom-spline․asd file
File, Lisp, cl-catmull-rom-spline/spline.lisp: The cl-catmull-rom-spline/spline․lisp file

L
Lisp File, cl-catmull-rom-spline.asd: The cl-catmull-rom-spline․asd file
Lisp File, cl-catmull-rom-spline/spline.lisp: The cl-catmull-rom-spline/spline․lisp file

Jump to:   C   F   L  

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): Internal generic functions
(setf coeffs): Internal generic functions
(setf coeffs-computed?): Internal generic functions
(setf coeffs-computed?): Internal generic functions
(setf cur-knot): Internal generic functions
(setf cur-knot): Internal generic functions
(setf cur-t): Internal generic functions
(setf cur-t): Internal generic functions
(setf dt): Internal generic functions
(setf dt): Internal generic functions
(setf endpoints-computed?): Internal generic functions
(setf endpoints-computed?): Internal generic functions
(setf knots): Internal generic functions
(setf knots): Internal generic functions
(setf knots-count): Internal generic functions
(setf knots-count): Internal generic functions

A
add-knot: Exported generic functions
add-knot: Exported generic functions

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

D
dot-product: Internal functions
dt: Internal generic functions
dt: Internal generic functions

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

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

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

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

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

N
next-point: Exported generic functions
next-point: Exported generic functions

R
reset: Exported generic functions
reset: Exported generic functions

S
scale: Exported generic functions
scale: Exported generic functions
set-coeffs: Internal functions

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

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

A.3 Variables

Jump to:   C   D   E   K   S  
Index Entry  Section

C
coeffs: Exported classes
coeffs-computed?: Exported classes
current-knot: Exported classes
current-t: Exported classes

D
delta-t: Exported classes

E
endpoints-computed?: Exported classes

K
knots: Exported classes
knots-count: Exported classes

S
Slot, coeffs: Exported classes
Slot, coeffs-computed?: Exported classes
Slot, current-knot: Exported classes
Slot, current-t: Exported classes
Slot, delta-t: Exported classes
Slot, endpoints-computed?: Exported classes
Slot, knots: Exported classes
Slot, knots-count: Exported classes

Jump to:   C   D   E   K   S  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-catmull-rom-spline: The cl-catmull-rom-spline system
cl-catmull-rom-spline: The cl-catmull-rom-spline package
Class, spline: Exported classes

P
Package, cl-catmull-rom-spline: The cl-catmull-rom-spline package

S
spline: Exported classes
System, cl-catmull-rom-spline: The cl-catmull-rom-spline system

Jump to:   C   P   S