AXOM
Axom provides a robust, flexible software infrastructure for the development of multi-physics applications and computational tools.
axom::primal::KnotVector< T > Class Template Reference

Represents the knot vector for a B-Spline/NURBS Curve/Surface. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/main/src/axom/primal/geometry/KnotVector.hpp>

Classes

class  DerivativeBasisView
 
struct  DerivativeBasisWorkspace
 Scratch storage for derivativeBasisFunctionsBySpan(...) More...
 

Public Member Functions

 AXOM_STATIC_ASSERT_MSG (std::is_arithmetic< T >::value, "A knot vector must be defined using an arithmetic type")
 
std::ostream & print (std::ostream &os) const
 Simple formatted print of a knot vector instance. More...
 
Constructors for KnotVector

The KnotVector class provides constructors that allow initialization from a user-supplied array of knots and a specified degree and enforces several conditions to ensure validity:

  • the degree must be at least -1
  • the knot array must contain at least (degree + 1) elements,
  • if the knot array is not empty, its data pointer must not be nullptr.

These checks guarantee that the constructed KnotVector adheres to the requirements for B-Spline/NURBS curves, such as monotonicity, clamped ends, and appropriate internal knot multiplicity. The isValid() method is used to verify that the resulting instance meets all necessary criteria for a valid knot span.

 KnotVector (axom::ArrayView< const T > knots, int degree)
 Constructor from a user-supplied knot vector (axom::ArrayView<const T>) More...
 
 KnotVector (axom::ArrayView< T > knots, int degree)
 
 KnotVector ()
 Default constructor for an empty (invalid) knot vector. More...
 
 KnotVector (axom::IndexType npts, int degree)
 Constructor for a normalized, uniform knot vector. More...
 
 KnotVector (const T *knots, axom::IndexType nkts, int degree)
 Constructor from a user-supplied knot vector (C-style array) More...
 
 KnotVector (const axom::Array< T > &knots, int degree)
 Constructor from a user-supplied knot vector (axom::Array) More...
 
Query/modify knot vector properties and sizes
void makeUniform (axom::IndexType npts, int deg)
 Give the knot vector uniformly spaced internal knots. More...
 
int getDegree () const
 Return the degree of the knot vector. More...
 
void setDegree (int degree)
 Reset the knot vector for the given degree. More...
 
axom::IndexType getNumKnots () const
 Return the number of knots in the knot vector. More...
 
axom::IndexType getNumControlPoints () const
 Return the number of control points implied by the knot vector. More...
 
getMinKnot () const
 Return the value of the smallest knot, or 0 if there are no knots. More...
 
getMaxKnot () const
 Return the value of the largest knot, or 0 if there are no knots. More...
 
void clear ()
 Clear the list of knots. More...
 
bool isValid () const
 Return if the knot vector is valid. More...
 
bool isValidSpan (axom::IndexType span) const
 Check if a knot span is valid. More...
 
bool isValidSpan (axom::IndexType span, T t) const
 Check if a knot span is valid and contains the parameter value t. More...
 
Query/modify/access knots
axom::Array< T > & getArray ()
 Accessor for the array of knots. More...
 
const axom::Array< T > & getArray () const
 Const accessor for the array of knots. More...
 
const T & operator[] (axom::IndexType i) const
 Getter for the knot vector. More...
 
T & operator[] (axom::IndexType i)
 Setter for the knot vector. More...
 
axom::Array< T > getUniqueKnots () const
 Return an array of the unique knot values. More...
 
axom::IndexType getNumKnotSpans () const
 Return the number of valid knot spans. More...
 
Query/modify KnotVector parametrization
void normalize ()
 Normalize the knot vector to the span of [0, 1]. More...
 
void rescale (T a, T b)
 Rescale the knot vector to the span of [a, b]. More...
 
void reverse ()
 Reverse the knot vector. More...
 
void insertKnotBySpan (axom::IndexType span, T t, int r)
 Insert a knot into the vector r times. More...
 
void insertKnot (T t, int target_multiplicity)
 Insert a knot into the vector to have the given multiplicity. More...
 
bool isValidParameter (T t, T EPS=1e-5) const
 Checks if given parameter is in knot span (to a tolerance) More...
 
bool isValidInteriorParameter (T t) const
 Checks if given parameter is interior to knot span (to a tolerance) More...
 
Functions for evaluating knot vector
axom::IndexType findSpan (T t) const
 Returns the index of the knot span containing parameter t. More...
 
axom::IndexType findSpan (T t, int &multiplicity) const
 Returns the index of the knot span containing parameter t and its multiplicity. More...
 
axom::Array< T > calculateBasisFunctionsBySpan (axom::IndexType span, T t) const
 Evaluates the NURBS basis functions for span at parameter value t. More...
 
axom::Array< T > calculateBasisFunctions (T t) const
 Evaluates the NURBS basis functions for parameter value t. More...
 
axom::Array< axom::Array< T > > derivativeBasisFunctionsBySpan (axom::IndexType span, T t, int n) const
 Evaluates the NURBS basis functions and derivatives for span at parameter value t. More...
 
DerivativeBasisView derivativeBasisFunctionsBySpan (axom::IndexType span, T t, int n, DerivativeBasisWorkspace &workspace) const
 Evaluates the NURBS basis functions and derivatives using a caller-supplied workspace. More...
 
axom::Array< axom::Array< T > > derivativeBasisFunctions (T t, int n) const
 Evaluates the NURBS basis functions and derivatives for parameter value t. More...
 
Functions dealing with knot vector subdivision
void splitBySpan (axom::IndexType span, KnotVector &k1, KnotVector &k2, bool normalize=false) const
 Split a knot vector at the value at index span More...
 
void split (T t, KnotVector &k1, KnotVector &k2, bool normalize=false) const
 Split a knot vector at the value t. More...
 

Friends

bool operator== (const KnotVector< T > &lhs, const KnotVector< T > &rhs)
 Check equality of two knot vectors. More...
 
bool operator!= (const KnotVector< T > &lhs, const KnotVector< T > &rhs)
 Check inequality of two knot vectors. More...
 

Detailed Description

template<typename T>
class axom::primal::KnotVector< T >

Represents the knot vector for a B-Spline/NURBS Curve/Surface.

Template Parameters
Tthe coordinate type, e.g., double, float, etc.

Contains methods for knot vector manipulation shared between NURBS curves and surfaces. This class maintains the degree and requirements on a knot vector, namely

Monotonicity (u_i <= u_i+1) Open/Clamped-ness (degree + 1 knots at beginning and end) Continuity (maximum internal knot multiplicity = degree)

Constructor & Destructor Documentation

◆ KnotVector() [1/6]

template<typename T >
axom::primal::KnotVector< T >::KnotVector ( axom::ArrayView< const T >  knots,
int  degree 
)
inline

Constructor from a user-supplied knot vector (axom::ArrayView<const T>)

Parameters
[in]knotsthe knot vector
[in]degreethe degree of the curve
Precondition
degree >= 1. When degree is less than 0, the KnotVector is invalid
The knots can be empty when the degree is -1, otherwise knots.data() is not nullptr
See also
isValid() tests conditions for a valid knot span instance

References axom::ArrayView< T, DIM, SPACE >::data(), axom::ArrayView< T, DIM, SPACE >::empty(), axom::primal::KnotVector< T >::isValid(), axom::ArrayView< T, DIM, SPACE >::size(), and SLIC_ASSERT.

◆ KnotVector() [2/6]

template<typename T >
axom::primal::KnotVector< T >::KnotVector ( axom::ArrayView< T >  knots,
int  degree 
)
inline

◆ KnotVector() [3/6]

template<typename T >
axom::primal::KnotVector< T >::KnotVector ( )
inline

Default constructor for an empty (invalid) knot vector.

◆ KnotVector() [4/6]

template<typename T >
axom::primal::KnotVector< T >::KnotVector ( axom::IndexType  npts,
int  degree 
)
inline

Constructor for a normalized, uniform knot vector.

Parameters
[in]nptsthe number of control points
[in]degreethe degree
Precondition
degree is greater than or equal to 0, and deg < npts.

References axom::primal::KnotVector< T >::makeUniform().

◆ KnotVector() [5/6]

template<typename T >
axom::primal::KnotVector< T >::KnotVector ( const T *  knots,
axom::IndexType  nkts,
int  degree 
)
inline

Constructor from a user-supplied knot vector (C-style array)

Parameters
[in]knotsthe knot vector
[in]nktsthe length of the knot vector
[in]degreethe degree of the curve
See also
KnotVector(axom::ArrayView<const T> knots, int degree)

◆ KnotVector() [6/6]

template<typename T >
axom::primal::KnotVector< T >::KnotVector ( const axom::Array< T > &  knots,
int  degree 
)
inline

Constructor from a user-supplied knot vector (axom::Array)

Parameters
[in]knotsthe knot vector
[in]degreethe degree of the curve
See also
KnotVector(axom::ArrayView<const T> knots, int degree)

Member Function Documentation

◆ AXOM_STATIC_ASSERT_MSG()

template<typename T >
axom::primal::KnotVector< T >::AXOM_STATIC_ASSERT_MSG ( std::is_arithmetic< T >::value  ,
"A knot vector must be defined using an arithmetic type"   
)

◆ makeUniform()

template<typename T >
void axom::primal::KnotVector< T >::makeUniform ( axom::IndexType  npts,
int  deg 
)
inline

Give the knot vector uniformly spaced internal knots.

Parameters
[in]nptsThe number of (implied) control points
[in]degThe degree of the curve
Precondition
Requires that npts + deg + 1 > 0 and deg < npts

References SLIC_ASSERT.

◆ getDegree()

template<typename T >
int axom::primal::KnotVector< T >::getDegree ( ) const
inline

Return the degree of the knot vector.

◆ setDegree()

template<typename T >
void axom::primal::KnotVector< T >::setDegree ( int  degree)
inline

Reset the knot vector for the given degree.

Parameters
[in]degreeThe target degree

If the target degree is greater than the current degree, the knot vector must be expanded to remain valid (clamped)

Warning
This method will always replace existing knot values

References axom::primal::KnotVector< T >::getNumControlPoints(), axom::primal::KnotVector< T >::makeUniform(), and SLIC_ASSERT.

◆ getNumKnots()

template<typename T >
axom::IndexType axom::primal::KnotVector< T >::getNumKnots ( ) const
inline

Return the number of knots in the knot vector.

◆ getNumControlPoints()

template<typename T >
axom::IndexType axom::primal::KnotVector< T >::getNumControlPoints ( ) const
inline

Return the number of control points implied by the knot vector.

◆ getMinKnot()

template<typename T >
T axom::primal::KnotVector< T >::getMinKnot ( ) const
inline

Return the value of the smallest knot, or 0 if there are no knots.

◆ getMaxKnot()

template<typename T >
T axom::primal::KnotVector< T >::getMaxKnot ( ) const
inline

Return the value of the largest knot, or 0 if there are no knots.

◆ clear()

template<typename T >
void axom::primal::KnotVector< T >::clear ( )
inline

Clear the list of knots.

◆ isValid()

template<typename T >
bool axom::primal::KnotVector< T >::isValid ( ) const
inline

◆ isValidSpan() [1/2]

template<typename T >
bool axom::primal::KnotVector< T >::isValidSpan ( axom::IndexType  span) const
inline

Check if a knot span is valid.

Parameters
[in]spanThe span to check

A valid span is one that is within the knot vector and has a non-zero length

Returns
True if the span is valid, false otherwise

◆ isValidSpan() [2/2]

template<typename T >
bool axom::primal::KnotVector< T >::isValidSpan ( axom::IndexType  span,
t 
) const
inline

Check if a knot span is valid and contains the parameter value t.

Parameters
[in]spanThe span to check
[in]tThe parameter value

A valid span is one that is within the knot vector, has a non-zero length, and contains the parameter value t

Returns
True if the span is valid, false otherwise

References axom::primal::KnotVector< T >::isValidSpan().

◆ getArray() [1/2]

template<typename T >
axom::Array<T>& axom::primal::KnotVector< T >::getArray ( )
inline

Accessor for the array of knots.

◆ getArray() [2/2]

template<typename T >
const axom::Array<T>& axom::primal::KnotVector< T >::getArray ( ) const
inline

Const accessor for the array of knots.

◆ operator[]() [1/2]

template<typename T >
const T& axom::primal::KnotVector< T >::operator[] ( axom::IndexType  i) const
inline

Getter for the knot vector.

Parameters
[in]iThe vector index
Returns
A const reference to the knot value at index i

◆ operator[]() [2/2]

template<typename T >
T& axom::primal::KnotVector< T >::operator[] ( axom::IndexType  i)
inline

Setter for the knot vector.

Parameters
[in]iThe vector index
Precondition
Assumes that the knot vector will remain valid after the change
Returns
A reference to the knot value at index i

References axom::primal::KnotVector< T >::isValid(), and SLIC_ASSERT.

◆ getUniqueKnots()

template<typename T >
axom::Array<T> axom::primal::KnotVector< T >::getUniqueKnots ( ) const
inline

Return an array of the unique knot values.

References axom::Array< T, DIM, SPACE, StoragePolicy >::push_back().

◆ getNumKnotSpans()

template<typename T >
axom::IndexType axom::primal::KnotVector< T >::getNumKnotSpans ( ) const
inline

Return the number of valid knot spans.

◆ normalize()

template<typename T >
void axom::primal::KnotVector< T >::normalize ( )
inline

Normalize the knot vector to the span of [0, 1].

References axom::primal::KnotVector< T >::getMaxKnot(), and axom::primal::KnotVector< T >::getMinKnot().

◆ rescale()

template<typename T >
void axom::primal::KnotVector< T >::rescale ( a,
b 
)
inline

Rescale the knot vector to the span of [a, b].

Parameters
[in]aThe lower bound of the new knot vector
[in]bThe upper bound of the new knot vector
Precondition
Requires a < b

References axom::primal::KnotVector< T >::getMaxKnot(), axom::primal::KnotVector< T >::getMinKnot(), axom::utilities::lerp(), and SLIC_ASSERT.

◆ reverse()

template<typename T >
void axom::primal::KnotVector< T >::reverse ( )
inline

◆ insertKnotBySpan()

template<typename T >
void axom::primal::KnotVector< T >::insertKnotBySpan ( axom::IndexType  span,
t,
int  r 
)
inline

Insert a knot into the vector r times.

Parameters
[in]spanThe span into which the knot will be inserted
[in]tThe value of the knot to insert
[in]rThe number of times to insert the knot
Precondition
Assumes that the input span is correct for input t, and that the knot is not present enough times to exceed the degree

References axom::primal::KnotVector< T >::isValid(), axom::primal::KnotVector< T >::isValidSpan(), and SLIC_ASSERT.

◆ insertKnot()

template<typename T >
void axom::primal::KnotVector< T >::insertKnot ( t,
int  target_multiplicity 
)
inline

Insert a knot into the vector to have the given multiplicity.

Parameters
[in]tThe value of the knot to insert
[in]target_mutliplicityThe number of times the knot will be present
Precondition
Assumes that the input t is within the knot vector (up to some tolerance)
Note
If the knot is already present, it will be inserted up to the given multiplicity, or the maximum permitted by the degree

References axom::utilities::clampVal(), axom::primal::KnotVector< T >::findSpan(), axom::primal::KnotVector< T >::insertKnotBySpan(), axom::primal::KnotVector< T >::isValidParameter(), and SLIC_ASSERT.

◆ isValidParameter()

template<typename T >
bool axom::primal::KnotVector< T >::isValidParameter ( t,
EPS = 1e-5 
) const
inline

Checks if given parameter is in knot span (to a tolerance)

References axom::primal::KnotVector< T >::getMaxKnot(), and axom::primal::KnotVector< T >::getMinKnot().

◆ isValidInteriorParameter()

template<typename T >
bool axom::primal::KnotVector< T >::isValidInteriorParameter ( t) const
inline

Checks if given parameter is interior to knot span (to a tolerance)

References axom::primal::KnotVector< T >::getMaxKnot(), and axom::primal::KnotVector< T >::getMinKnot().

◆ findSpan() [1/2]

template<typename T >
axom::IndexType axom::primal::KnotVector< T >::findSpan ( t) const
inline

Returns the index of the knot span containing parameter t.

Parameters
[in]tThe parameter value

For knot vector {u_0, ..., u_n}, returns i such that u_i <= t < u_i+1 if t == u_n, returns i such that u_i < t <= u_i+1 (i.e. i = n - degree - 1)

Implementation adapted from Algorithm A2.1 on page 68 of "The NURBS Book"

Precondition
Assumes that the input t is in the span [u_0, u_n] (up to some tolerance)
Note
If t is outside the knot span up to this tolerance, it is clamped to the span
Returns
The index of the knot span containing t

References axom::primal::KnotVector< T >::getMaxKnot(), axom::primal::KnotVector< T >::getMinKnot(), axom::primal::KnotVector< T >::isValidParameter(), and SLIC_ASSERT.

◆ findSpan() [2/2]

template<typename T >
axom::IndexType axom::primal::KnotVector< T >::findSpan ( t,
int &  multiplicity 
) const
inline

Returns the index of the knot span containing parameter t and its multiplicity.

Parameters
[in]tThe parameter value
[out]multiplicityThe multiplicity of the knot at t

For knot vector {u_0, ..., u_n}, returns i such that u_i <= t < u_i+1 if t == u_n, returns i such that u_i < t <= u_i+1 (i.e. i = n - degree - 1)

Precondition
Assumes that the input t is within the knot vector (up to some tolerance)
Note
If t is outside the knot span up to this tolerance, the returned multiplicity will be equal to the degree + 1 (required for clamped curves)
Returns
The index of the knot span containing t

References axom::primal::KnotVector< T >::findSpan(), axom::primal::KnotVector< T >::getMaxKnot(), axom::primal::KnotVector< T >::getMinKnot(), axom::primal::KnotVector< T >::isValidParameter(), and SLIC_ASSERT.

◆ calculateBasisFunctionsBySpan()

template<typename T >
axom::Array<T> axom::primal::KnotVector< T >::calculateBasisFunctionsBySpan ( axom::IndexType  span,
t 
) const
inline

Evaluates the NURBS basis functions for span at parameter value t.

Parameters
[in]spanThe span in which to evaluate the basis functions
[in]tThe parameter value
Precondition
Assumes that the input t is within the correct span Implementation adapted from Algorithm A2.2 on page 70 of "The NURBS Book".
Returns
An array of the m_deg + 1 non-zero basis functions evaluated at t

References axom::primal::KnotVector< T >::isValidSpan(), and SLIC_ASSERT.

◆ calculateBasisFunctions()

template<typename T >
axom::Array<T> axom::primal::KnotVector< T >::calculateBasisFunctions ( t) const
inline

Evaluates the NURBS basis functions for parameter value t.

Parameters
[in]tThe parameter value
Precondition
Assumes that the input t is within the knot vector (up to a tolerance)
Returns
An array of the m_deg + 1 non-zero basis functions evaluated at t

References axom::primal::KnotVector< T >::calculateBasisFunctionsBySpan(), axom::primal::KnotVector< T >::findSpan(), axom::primal::KnotVector< T >::isValidParameter(), and SLIC_ASSERT.

◆ derivativeBasisFunctionsBySpan() [1/2]

template<typename T >
axom::Array<axom::Array<T> > axom::primal::KnotVector< T >::derivativeBasisFunctionsBySpan ( axom::IndexType  span,
t,
int  n 
) const
inline

Evaluates the NURBS basis functions and derivatives for span at parameter value t.

Parameters
[in]spanThe span in which to evaluate the basis functions
[in]tThe parameter value
[in]nThe number of derivatives to compute

Implementation adapted from Algorithm A2.2 on page 70 of "The NURBS Book".

Precondition
Assumes that the input t is within the provided knot span
Returns
An array of the n + 1 derivatives evaluated at t

References axom::primal::KnotVector< T >::isValidSpan(), axom::Array< T, DIM, SPACE, StoragePolicy >::resize(), SLIC_ASSERT, and axom::utilities::swap().

◆ derivativeBasisFunctionsBySpan() [2/2]

template<typename T >
DerivativeBasisView axom::primal::KnotVector< T >::derivativeBasisFunctionsBySpan ( axom::IndexType  span,
t,
int  n,
DerivativeBasisWorkspace workspace 
) const
inline

◆ derivativeBasisFunctions()

template<typename T >
axom::Array<axom::Array<T> > axom::primal::KnotVector< T >::derivativeBasisFunctions ( t,
int  n 
) const
inline

Evaluates the NURBS basis functions and derivatives for parameter value t.

Parameters
[in]tThe parameter value
[in]nThe number of derivatives to compute
Precondition
Assumes that the input t is within the knot vector (up to a tolerance)
Returns
An array of the n + 1 derivatives evaluated at t

References axom::primal::KnotVector< T >::derivativeBasisFunctionsBySpan(), axom::primal::KnotVector< T >::findSpan(), axom::primal::KnotVector< T >::isValidParameter(), and SLIC_ASSERT.

◆ splitBySpan()

template<typename T >
void axom::primal::KnotVector< T >::splitBySpan ( axom::IndexType  span,
KnotVector< T > &  k1,
KnotVector< T > &  k2,
bool  normalize = false 
) const
inline

Split a knot vector at the value at index span

Parameters
[in]spanThe span at which the knot will be split
[out]k1The first knot vector
[out]k2The second knot vector
[in]normalizeWhether to normalize the output knot vectors
Warning
Assumes that the multiplicity of the knot at which the vector will be split is equal to the degree, or the returned knot vectors will be invalid

References axom::primal::KnotVector< T >::getNumKnots(), axom::primal::KnotVector< T >::isValid(), axom::primal::KnotVector< T >::isValidSpan(), axom::primal::KnotVector< T >::normalize(), and SLIC_ASSERT.

◆ split()

template<typename T >
void axom::primal::KnotVector< T >::split ( t,
KnotVector< T > &  k1,
KnotVector< T > &  k2,
bool  normalize = false 
) const
inline

Split a knot vector at the value t.

Parameters
[in]tThe value at which the knot will be split
[out]k1The first knot vector
[out]k2The second knot vector
[in]normalizeWhether to normalize the output knot vectors
Precondition
Assumes that the input t is interior to the knot vector

References axom::primal::KnotVector< T >::findSpan(), axom::primal::KnotVector< T >::insertKnotBySpan(), axom::primal::KnotVector< T >::isValidInteriorParameter(), axom::primal::KnotVector< T >::normalize(), SLIC_ASSERT, and axom::primal::KnotVector< T >::splitBySpan().

◆ print()

template<typename T >
std::ostream& axom::primal::KnotVector< T >::print ( std::ostream &  os) const
inline

Simple formatted print of a knot vector instance.

Parameters
osThe output stream to write to
Returns
A reference to the modified ostream

Friends And Related Function Documentation

◆ operator==

template<typename T >
bool operator== ( const KnotVector< T > &  lhs,
const KnotVector< T > &  rhs 
)
friend

Check equality of two knot vectors.

Parameters
[in]lhsThe first knot vector
[in]rhsThe second knot vector
Returns
True if the knot vectors are equal, false otherwise

◆ operator!=

template<typename T >
bool operator!= ( const KnotVector< T > &  lhs,
const KnotVector< T > &  rhs 
)
friend

Check inequality of two knot vectors.

Parameters
[in]lhsThe first knot vector
[in]rhsThe second knot vector
Returns
True if the knot vectors are not equal, false otherwise

The documentation for this class was generated from the following file: