maspack.interpolation

Class NumericList

java.lang.Object

maspack.interpolation.NumericList

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<NumericListKnot>, Scannable

public class NumericList
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Iterable<NumericListKnot>, Scannable

A linked list of vector values arranged in order with respect to a parameter t. Can be interpolated to produce a continuous vector function.

A numeric list can be constructed to contain a set of subvectors representing rotations, using a representation specified by a RotationRep. For Linear, Cubic and CubicStep interpolation, rotation subvectors are interpolated as curves on the surface of SO(3), as originally described by Ken Shoemake in his SIGGRAPH 1985 paper "Animating Rotation with Quaternion Curves".

Field Summary

Fields

Modifier and Type	Field and Description
boolean	debug

Constructor Summary

Constructors

Constructor and Description
NumericList(int vsize) Creates an empty numeric list for holding vectors of a prescribed size.
NumericList(int vsize, RotationRep rotRep, int[] offsets) Creates an empty numeric list containing rotation subvectors with specified representation and offsets.

Method Summary

Modifier and Type	Method and Description
NumericListKnot	add(double t, double... vals) Creates a knot with the specified values and time and adds it into this numeric list.
NumericListKnot	add(NumericListKnot knot) Adds a knot into this numeric list.
NumericListKnot	add(NumericListKnot knot, NumericListKnot last)
NumericListKnot	add(Vector vals, double t) Creates a knot with the specified values and time and adds it into this numeric list.
NumericListKnot	addAndAdjustRotations(NumericListKnot knot) Adds a knot into this numeric list, and adjust the value of any rotation subvector to the (redundant) representation "closest" to that in the nearest existing knot.
void	adjustRotationValues(VectorNd vr, VectorNd v, double t) Copies the values v into vr, while adjusting the value of any rotation subvector to the (redundant) representation "closest" to that in the knot nearest to t.
NumericListKnot	adjustRotationValues(VectorNd vr, VectorNd v, double t, NumericListKnot last) Copies the values v into vr, while adjusting the value of any rotation subvector to the (redundant) representation "closest" to that in the knot nearest to t.
void	applyMovingAverageSmoothing(int winSize) Smooths the values in this list by applying a mean average filter over a moving window of specified size.
void	applySavitzkyGolaySmoothing(int winSize, int deg) Smooths the values in this list by applying Savitzky-Golay smoothing over a moving window of specified size.
static void	checkRotationSubvecOffsets(int[] offsets, RotationRep rotRep, int vsize) Checks a set of specified rotation subvector offsets to ensure that they do not overlap and all fit within the overall vector.
void	clear() Removes all knots in the numeric list.
void	clearAfter(NumericListKnot knot) Removes all knots after a specific knot in this list.
java.lang.Object	clone() Returns a deep copy of this numeric list.
boolean	equals(NumericList list) Returns true if the contents of this numeric list equal the contents of another numeric list.
NumericListKnot	findKnotAtOrBefore(double t, NumericListKnot last) Finds the knot whose t value is closest to, and if possible less or equal to, a specified value.
NumericListKnot	findKnotClosest(double t) Finds the knot whose t value is closest to a specified value.
NumericListKnot	findKnotClosest(double t, NumericListKnot last)
int	getDerivSize() Returns the size of the derivative vector associated with this list.
NumericListKnot	getFirst() Returns the first knot in this list.
Interpolation	getInterpolation() Returns the interpolation method for this list.
Interpolation.Order	getInterpolationOrder() Returns the interpolation order for this list.
NumericListKnot	getKnot(int idx) Returns the idx-th knot in this list, or null if so such knot exists;
NumericListKnot	getLast() Returns the last knot in this list.
VectorNd	getMaxValues() Returns a vector giving the maximum values across all knots in this list.
void	getMinMaxValues(double[] minMax)
void	getMinMaxValues(VectorNd min, VectorNd max)
VectorNd	getMinValues() Returns a vector giving the minimum values across all knots in this list.
int	getNumKnots() Returns the number of knots in this list.
RotationRep	getRotationRep() Returns the representation associated with rotation subvectors of this list, or null if there are no rotation subvectors.
int[]	getRotationSubvecOffsets() Returns an array giving the offsets of any rotation subvectors associated with this list.
void	getSumSquaredValues(VectorNd sumsqr) Returns the sum of the square of each vector element over all the knots.
double[][]	getValues() Returns the values of this numeric list as a two dimensional array of doubles.
int	getVectorSize() Returns the size of the vectors associated with this list.
void	interpolate(VectorNd v, double t) Interpolates the value associated with a particular value of t, based on the current contents of this list.
NumericListKnot	interpolate(VectorNd v, double t, Interpolation.Order order, boolean extendData, NumericListKnot last) Interpolates the value associated with a particular value of t, based on the current contents of this list.
NumericListKnot	interpolate(VectorNd v, double t, Interpolation method, NumericListKnot last)
void	interpolateCubic(VectorNd v, NumericListKnot prev, double t)
void	interpolateDeriv(VectorNd v, double t) Finds the derivative associated with a particular value of t, by differentiating the function implied by the knot points and the list's interpolation method, as returned by getInterpolation().
NumericListKnot	interpolateDeriv(VectorNd v, double t, Interpolation.Order order, NumericListKnot last) Finds the derivative associated with a particular value of t, by differentiating the function implied by the knot points and the interpolation order specified by order.
NumericListKnot	interpolateDeriv(VectorNd v, double t, Interpolation method, NumericListKnot last)
boolean	isEmpty() Returns true if this list is empty.
boolean	isWritable() Returns true if this component should in fact be written to secondary storage.
java.util.Iterator<NumericListKnot>	iterator() Returns an iterator over all the knots in this numeric list.
void	numericalDeriv(VectorNd v, double t) Finds the derivative associated with a particular value of t, based on numerical differentation of the current knot points.
NumericListKnot	numericalDeriv(VectorNd v, double t, NumericListKnot last) Finds the derivative associated with a particular value of t, based on numerical differentation of the current knot points.
int	numRotationSubvecs() Queries the number of rotation subvectors.
NumericListKnot	remove(double t) Removes and return the knot at time t, if any.
void	remove(NumericListKnot knot) Removes a knot from this numeric list.
void	scale(double s) Uniformly scales all the values in this list
void	scan(ReaderTokenizer rtok, java.lang.Object ref) Scans this element from a ReaderTokenizer.
void	setInterpolation(Interpolation method) Sets the interpolation method for this list.
void	setInterpolationOrder(Interpolation.Order order) Sets the interpolation order for this list.
void	setValues(double[][] vals) Sets the values of this numeric list from a two dimensional array of doubles.
void	setValues(NumericList src, double tscale, double toffset) Sets the values of this numeric list from those of another numeric list.
void	shiftTime(double t)
java.lang.String	toString() Returns a string representation of this numeric list.
java.lang.String	toString(NumberFormat fmt) Returns a String representation of this numeric list, in which each element is formatted using a C printf style as decribed by the parameter NumberFormat.
java.lang.String	toString(java.lang.String fmtStr) Returns a String representation of this numeric list, in which each element is formatted using a C printf style format string.
java.lang.String	toStringSuper()
void	write(java.io.PrintWriter pw, NumberFormat fmt, java.lang.Object ref) Writes a text description of this element to a PrintWriter.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

debug

public boolean debug

Constructor Detail

NumericList

public NumericList(int vsize)

Creates an empty numeric list for holding vectors of a prescribed size.

Parameters:

vsize - size of the vectors that will form this list

NumericList

public NumericList(int vsize,
                   RotationRep rotRep,
                   int[] offsets)

Creates an empty numeric list containing rotation subvectors with specified representation and offsets.

Parameters:

vsize - size of the vectors that will form this list

rotRep - how rotations are represented with the subvectors

offsets - offsets for the rotation subvectors

Method Detail

setInterpolation

public void setInterpolation(Interpolation method)

Sets the interpolation method for this list. The default is Step with no end data extension.

Parameters:

method - new interpolation method.

setInterpolationOrder

public void setInterpolationOrder(Interpolation.Order order)

Sets the interpolation order for this list. The default is Step.

Parameters:

order - new interpolation order;

getInterpolation

public Interpolation getInterpolation()

Returns the interpolation method for this list.

Returns:

interpolation method

See Also:

setInterpolation(maspack.interpolation.Interpolation)

getInterpolationOrder

public Interpolation.Order getInterpolationOrder()

Returns the interpolation order for this list.

Returns:

interpolation order

See Also:

setInterpolationOrder(maspack.interpolation.Interpolation.Order)

getVectorSize

public int getVectorSize()

Returns the size of the vectors associated with this list.

getDerivSize

public int getDerivSize()

Returns the size of the derivative vector associated with this list. This will be different from the list's vector size if the list contains rotation subvectors using a representation whose numeric size is not equal to three.

Returns:

derivative vector size

getRotationRep

public RotationRep getRotationRep()

Returns the representation associated with rotation subvectors of this list, or null if there are no rotation subvectors.

Returns:

rotation subvector representation

getRotationSubvecOffsets

public int[] getRotationSubvecOffsets()

Returns an array giving the offsets of any rotation subvectors associated with this list. The array will have length 0 if there are no rotation subvectors.

Returns:

offsets for the rotation subvectors

checkRotationSubvecOffsets

public static void checkRotationSubvecOffsets(int[] offsets,
                                              RotationRep rotRep,
                                              int vsize)

Checks a set of specified rotation subvector offsets to ensure that they do not overlap and all fit within the overall vector.

Parameters:

offsets - offset values to be checked

rotRep - rotation representation associated with the subvectors

vsize - overall vector size

numRotationSubvecs

public int numRotationSubvecs()

Queries the number of rotation subvectors.

Returns:

number of rotation subvectors

add

public NumericListKnot add(NumericListKnot knot)

Adds a knot into this numeric list. The knot will be added at the proper location so that all t values are monotonically increasing. Any existing knot which has the same t value as the new knot will be removed and returned.

Parameters:

knot - knot to add to the list

Returns:

existing knot with the same t value, if any

Throws:

java.lang.IllegalArgumentException - if the knot's vector has a size not equal to the vector size for this list.

See Also:

getVectorSize()

addAndAdjustRotations

public NumericListKnot addAndAdjustRotations(NumericListKnot knot)

Adds a knot into this numeric list, and adjust the value of any rotation subvector to the (redundant) representation "closest" to that in the nearest existing knot. The knot will be added at the proper location so that all t values are monotonically increasing. Any existing knot which has the same t value as the new knot will be removed and returned.

Parameters:

knot - knot to add to the list

Returns:

existing knot with the same t value, if any

Throws:

java.lang.IllegalArgumentException - if the knot's vector has a size not equal to the vector size for this list.

See Also:

getVectorSize()

add

public NumericListKnot add(Vector vals,
                           double t)

Creates a knot with the specified values and time and adds it into this numeric list. The knot will be added at the proper location so that all t values are monotonically increasing. Any existing knot which has the same t value as the new knot will be removed and returned.

Parameters:

vals - values for the knot

t - time at which the knot should be added

Returns:

knot that was added

Throws:

java.lang.IllegalArgumentException - if values has a size less than the vector size for this list.

See Also:

getVectorSize()

add

public NumericListKnot add(double t,
                           double... vals)

Creates a knot with the specified values and time and adds it into this numeric list. The knot will be added at the proper location so that all t values are monotonically increasing. Any existing knot which has the same t value as the new knot will be removed and returned.

Parameters:

t - time at which the knot should be added

vals - values for the knot; the number must be >= the list's vector size

Returns:

knot that was added

Throws:

java.lang.IllegalArgumentException - if values has a size less than the vector size for this list.

See Also:

getVectorSize()

add

public NumericListKnot add(NumericListKnot knot,
                           NumericListKnot last)

shiftTime

public void shiftTime(double t)

getMinValues

public VectorNd getMinValues()

Returns a vector giving the minimum values across all knots in this list. Should not be modified.

getMaxValues

public VectorNd getMaxValues()

Returns a vector giving the maximum values across all knots in this list. Should not be modified.

getMinMaxValues

public void getMinMaxValues(double[] minMax)

getMinMaxValues

public void getMinMaxValues(VectorNd min,
                            VectorNd max)

getSumSquaredValues

public void getSumSquaredValues(VectorNd sumsqr)

Returns the sum of the square of each vector element over all the knots.

Parameters:

sumsqr - returns the mean square values

remove

public NumericListKnot remove(double t)

Removes and return the knot at time t, if any.

Parameters:

t - time of the knot to remove

Returns:

removed knot, if any

remove

public void remove(NumericListKnot knot)

Removes a knot from this numeric list. It is up to the application to ensure that the knot is currently a member of this list.

Parameters:

knot - knot to remove

clearAfter

public void clearAfter(NumericListKnot knot)

Removes all knots after a specific knot in this list. It is up to the application to ensure that the specified knot is a member of the list.

Parameters:

knot - all knots following this one will be removed

findKnotAtOrBefore

public NumericListKnot findKnotAtOrBefore(double t,
                                          NumericListKnot last)

Finds the knot whose t value is closest to, and if possible less or equal to, a specified value.

Parameters:

t - specified value

Returns:

nearest knot less than t

findKnotClosest

public NumericListKnot findKnotClosest(double t)

Finds the knot whose t value is closest to a specified value.

Parameters:

t - specified value

Returns:

knot closest to t

findKnotClosest

public NumericListKnot findKnotClosest(double t,
                                       NumericListKnot last)

interpolate

public void interpolate(VectorNd v,
                        double t)

Interpolates the value associated with a particular value of t, based on the current contents of this list. The interpolation is done using the list's interpolation method, as returned by getInterpolation(). If t lies before the start or after the end of the list, the interpolation value is set to the first or last knot value.

Parameters:

v - stores the interpolation result

t - value to interpolate for

interpolateDeriv

public void interpolateDeriv(VectorNd v,
                             double t)

Finds the derivative associated with a particular value of t, by differentiating the function implied by the knot points and the list's interpolation method, as returned by getInterpolation(). If t lies before the start or after the end of the list, the derivative will be zero.

Parameters:

v - stores the derivative result

t - value to find the derivative at

numericalDeriv

public void numericalDeriv(VectorNd v,
                           double t)

Finds the derivative associated with a particular value of t, based on numerical differentation of the current knot points. This is done by linearly interpolating numerical derivatives computed at the mid-points between knots. If t lies before the start or after the end of the list, the derivative will be zero.

Parameters:

v - stores the derivative result

t - value to find the derivative for

adjustRotationValues

public void adjustRotationValues(VectorNd vr,
                                 VectorNd v,
                                 double t)

Copies the values v into vr, while adjusting the value of any rotation subvector to the (redundant) representation "closest" to that in the knot nearest to t.

Parameters:

vr - stores the result

v - values to copy and adjust if needed

t - time associated with the values

adjustRotationValues

public NumericListKnot adjustRotationValues(VectorNd vr,
                                            VectorNd v,
                                            double t,
                                            NumericListKnot last)

Copies the values v into vr, while adjusting the value of any rotation subvector to the (redundant) representation "closest" to that in the knot nearest to t.

The method returns the knot that is nearest to t. By using this returned value as the last argument in subsequent method calls, one can traverse forward or backward (in time) along the list with O(1) complexity.

Parameters:

vr - stores the result

v - values to copy and adjust if needed

t - time associated with the values

last - knot point used to start the search for the knot containing t

Returns:

nearest knot to t

interpolateCubic

public void interpolateCubic(VectorNd v,
                             NumericListKnot prev,
                             double t)

interpolate

public NumericListKnot interpolate(VectorNd v,
                                   double t,
                                   Interpolation method,
                                   NumericListKnot last)

interpolateDeriv

public NumericListKnot interpolateDeriv(VectorNd v,
                                        double t,
                                        Interpolation method,
                                        NumericListKnot last)

interpolate

public NumericListKnot interpolate(VectorNd v,
                                   double t,
                                   Interpolation.Order order,
                                   boolean extendData,
                                   NumericListKnot last)

Interpolates the value associated with a particular value of t, based on the current contents of this list. The interpolation order is specified by order. If t lies before the start or after the end of the list, the interpolation value is set to either the first or last knot value, or zero, depending on whether extendData is true or false.

The method returns the nearest knot that is at or before t. By using this returned value as the last argument in subsequent method calls, one can traverse forward or backward (in time) along the list with O(1) complexity.

Parameters:

v - stores the interpolation result

t - value to interpolate for

order - interpolation order

extendData - if true, data is extended beyond the start and end of the list based on the first and last knot values

last - knot point used to start the search for the knot containing t

Returns:

nearest knot at or before t

interpolateDeriv

public NumericListKnot interpolateDeriv(VectorNd v,
                                        double t,
                                        Interpolation.Order order,
                                        NumericListKnot last)

Finds the derivative associated with a particular value of t, by differentiating the function implied by the knot points and the interpolation order specified by order. If t lies before the start or after the end of the list, the derivative will be zero.

The method returns the nearest knot that is at or before t. By using this returned value as the last argument in subsequent method calls, one can traverse forward or backward (in time) along the list with O(1) complexity.

Parameters:

v - stores the derivative result

t - value to find the derivative at

order - interpolation order

last - knot point used to start the search for the knot containing t

Returns:

nearest knot at or before t

numericalDeriv

public NumericListKnot numericalDeriv(VectorNd v,
                                      double t,
                                      NumericListKnot last)

Finds the derivative associated with a particular value of t, based on numerical differentation of the current knot points. This is done by linearly interpolating numerical derivatives computed at the mid-points between knots. If t lies before the start or after the end of the list, the derivative will be zero.

The method returns the nearest knot that is at or before t. By using this returned value as the last argument in subsequent method calls, one can traverse forward or backward (in time) along the list with O(1) complexity.

Parameters:

v - stores the derivative result

t - value to find the derivative for

last - knot point used to start the search for the knot containing t

Returns:

nearest knot at or before t

getFirst

public NumericListKnot getFirst()

Returns the first knot in this list.

Returns:

first knot in this list

getLast

public NumericListKnot getLast()

Returns the last knot in this list.

Returns:

last knot in this list

getKnot

public NumericListKnot getKnot(int idx)

Returns the idx-th knot in this list, or null if so such knot exists;

Returns:

idx-th knot

getNumKnots

public int getNumKnots()

Returns the number of knots in this list.

Returns:

number of knots

isEmpty

public boolean isEmpty()

Returns true if this list is empty.

Returns:

true if this list is empty

clear

public void clear()

Removes all knots in the numeric list.

scale

public void scale(double s)

Uniformly scales all the values in this list

Parameters:

s - scale factor

applyMovingAverageSmoothing

public void applyMovingAverageSmoothing(int winSize)

Smooths the values in this list by applying a mean average filter over a moving window of specified size. This window is centered on each knot, and is reduced in size near the end knots to ensure a symmetric fit. The end knot values are not changed.

Parameters:

winSize - size of the averaging window. The value should be odd; if it is even, it will be incremented internally to be odd. The method does nothing if the value is is less than 1. Finally, winSize will be reduced if necessary to fit the number of knots.

applySavitzkyGolaySmoothing

public void applySavitzkyGolaySmoothing(int winSize,
                                        int deg)

Smooths the values in this list by applying Savitzky-Golay smoothing over a moving window of specified size. Savitzky-Golay smoothing works by fitting the data values in the window to a polynomial of degree deg, and then using this to recompute the value in the middle of the window. The polynomial is also used to interpolate the first and last winSize/2 values, since it is not possible to center the window on these.

Parameters:

deg - degree of the smoothing polynomial. Must be at least 1.

winSize - size of the averaging window. The value must be >= deg+1 and should also be odd; if it is even, it will be incremented internally to be odd. Finally, winSize will be reduced if necessary to fit the number of knots.

iterator

public java.util.Iterator<NumericListKnot> iterator()

Returns an iterator over all the knots in this numeric list.

Specified by:

iterator in interface java.lang.Iterable<NumericListKnot>

Returns:

iterator over ths knots

getValues

public double[][] getValues()

Returns the values of this numeric list as a two dimensional array of doubles. This facilitates reading the values into a matlab array. The array is arranged so that each knot point corresponds to a row, the first column gives the time values, and the remaining columns give the knot point values.

Returns:

Values of this numeric list

setValues

public void setValues(double[][] vals)

Sets the values of this numeric list from a two dimensional array of doubles. This facilitates settings the values from a matlab array. The arrangement of the array is described in getValues().

Parameters:

vals - Values used to set this numeric list

setValues

public void setValues(NumericList src,
                      double tscale,
                      double toffset)

Sets the values of this numeric list from those of another numeric list. The vector size of the source list must be greater than or equal to that of this list; extra values are ignored.

The time values t in this list are set from the time values ts in the source list according to

 t = tscale ts + toffset
 

Parameters:

src - numeric list to copy values from

tscale - scale factor for source time values

toffset - offset for source time values

equals

public boolean equals(NumericList list)

Returns true if the contents of this numeric list equal the contents of another numeric list.

Parameters:

list - numeric list to compare with

Returns:

true if the lists are equal

toString

public java.lang.String toString()

Returns a string representation of this numeric list.

Overrides:

toString in class java.lang.Object

Returns:

string representation of this list

toString

public java.lang.String toString(java.lang.String fmtStr)

Returns a String representation of this numeric list, in which each element is formatted using a C printf style format string. For a description of the format string syntax, see NumberFormat.

Parameters:

fmtStr - numeric format specification

Returns:

String representation of this list

toString

public java.lang.String toString(NumberFormat fmt)

Returns a String representation of this numeric list, in which each element is formatted using a C printf style as decribed by the parameter NumberFormat. When called numerous times, this routine can be more efficient than toString(String), because the NumberFormat does not need to be recreated each time from a specification string.

Parameters:

fmt - numeric format

Returns:

String representation of this list

toStringSuper

public java.lang.String toStringSuper()

clone

public java.lang.Object clone()

Returns a deep copy of this numeric list.

Overrides:

clone in class java.lang.Object

isWritable

public boolean isWritable()

Returns true if this component should in fact be written to secondary storage. This gives subclasses control over whether or not they are actually written out.

Specified by:

isWritable in interface Scannable

Returns:

true if this component should be written to secondary storage.

write

public void write(java.io.PrintWriter pw,
                  NumberFormat fmt,
                  java.lang.Object ref)
           throws java.io.IOException

Writes a text description of this element to a PrintWriter. The text description should be compatable with scan and complete enough to allow full reconstruction of the element.

Specified by:

write in interface Scannable

Parameters:

pw - stream for writing the element

fmt - numeric formating information

ref - optional reference object which can be used for producing references to other objects

Throws:

java.io.IOException - if an I/O error occured

scan

public void scan(ReaderTokenizer rtok,
                 java.lang.Object ref)
          throws java.io.IOException

Scans this element from a ReaderTokenizer. The expected text format is assumed to be compatible with that produced by write.

Specified by:

scan in interface Scannable

Parameters:

rtok - Tokenizer from which to scan the element

ref - optional reference object which can be used for resolving references to other objects

Throws:

java.io.IOException - if an I/O or formatting error occured