Utilities and Helpers

These modules contain common utility and helper functions for B-Spline / NURBS curve and surface evaluation operations.

Utilities

The utilities module contains common utility functions for NURBS-Python library and its extensions.

geomdl.utilities.generate_knot_vector(degree, num_ctrlpts, **kwargs)

Generates an equally spaced knot vector.

It uses the following equation to generate knot vector:

m = n + p + 1

where;

p: degree, n+1: number of control points, m+1: number of knots

Keyword Arguments:

  • clamped: Flag to choose from clamped or unclamped knot vector options. Default: True
Parameters:
  • degree (int) – degree
  • num_ctrlpts (int) – number of control points
Returns:

knot vector

Return type:

list

Helpers

The helpers module contains common functions required for evaluating both surfaces and curves, such as basis function computations, knot vector span finding, etc.

geomdl.helpers.basis_function(degree, knot_vector, span, knot)

Computes the non-vanishing basis functions for a single parameter.

Implementation of Algorithm A2.2 from The NURBS Book by Piegl & Tiller.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • span (int) – knot span, i
  • knot (float) – knot or parameter, u
Returns:

basis functions

Return type:

list

geomdl.helpers.basis_function_all(degree, knot_vector, span, knot)

Computes all non-zero basis functions of all degrees from 0 up to the input degree for a single parameter.

A slightly modified version of Algorithm A2.2 from The NURBS Book by Piegl & Tiller.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • span (int) – knot span, i
  • knot (float) – knot or parameter, u
Returns:

basis functions

Return type:

list

geomdl.helpers.basis_function_ders(degree, knot_vector, span, knot, order)

Computes derivatives of the basis functions for a single parameter.

Implementation of Algorithm A2.3 from The NURBS Book by Piegl & Tiller.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • span (int) – knot span, i
  • knot (float) – knot or parameter, u
  • order (int) – order of the derivative
Returns:

derivatives of the basis functions

Return type:

list

geomdl.helpers.basis_function_ders_one(degree, knot_vector, span, knot, order)

Computes the derivative of one basis functions for a single parameter.

Implementation of Algorithm A2.5 from The NURBS Book by Piegl & Tiller.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot_vector, U
  • span (int) – knot span, i
  • knot (float) – knot or parameter, u
  • order (int) – order of the derivative
Returns:

basis function derivatives

Return type:

list

geomdl.helpers.basis_function_one(degree, knot_vector, span, knot)

Computes the value of a basis function for a single parameter.

Implementation of Algorithm 2.4 from The NURBS Book by Piegl & Tiller.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector
  • span (int) – knot span, i
  • knot (float) – knot or parameter, u
Returns:

basis function, N_{i,p}

Return type:

float

geomdl.helpers.basis_functions(degree, knot_vector, spans, knots)

Computes the non-vanishing basis functions for a list of parameters.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • spans (list, tuple) – list of knot spans
  • knots (list, tuple) – list of knots or parameters
Returns:

basis functions

Return type:

list

geomdl.helpers.basis_functions_ders(degree, knot_vector, spans, knots, order)

Computes derivatives of the basis functions for a list of parameters.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • spans (list, tuple) – list of knot spans
  • knots (list, tuple) – list of knots or parameters
  • order (int) – order of the derivative
Returns:

derivatives of the basis functions

Return type:

list

geomdl.helpers.find_multiplicity(knot, knot_vector, **kwargs)

Finds knot multiplicity over the knot vector.

Parameters:
  • knot (float) – knot or parameter, u
  • knot_vector (list, tuple) – knot vector, U
Returns:

knot multiplicity, s

Return type:

int

geomdl.helpers.find_span_binsearch(degree, knot_vector, num_ctrlpts, knot, **kwargs)

Finds the span of the knot over the input knot vector using binary search.

Implementation of Algorithm A2.1 from The NURBS Book by Piegl & Tiller.

The NURBS Book states that the knot span index always starts from zero, i.e. for a knot vector [0, 0, 1, 1]; if FindSpan returns 1, then the knot is between the interval [0, 1).

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • num_ctrlpts (int) – number of control points, n + 1
  • knot (float) – knot or parameter, u
Returns:

knot span

Return type:

int

geomdl.helpers.find_span_linear(degree, knot_vector, num_ctrlpts, knot, **kwargs)

Finds the span of a single knot over the knot vector using linear search.

Alternative implementation for the Algorithm A2.1 from The NURBS Book by Piegl & Tiller.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • num_ctrlpts (int) – number of control points, n + 1
  • knot (float) – knot or parameter, u
Returns:

knot span

Return type:

int

geomdl.helpers.find_spans(degree, knot_vector, num_ctrlpts, knots, func=<function find_span_linear>)

Finds spans of a list of knots over the knot vector.

Parameters:
  • degree (int) – degree, p
  • knot_vector (list, tuple) – knot vector, U
  • num_ctrlpts (int) – number of control points, n + 1
  • knots (list, tuple) – list of knots or parameters
  • func – function for span finding, e.g. linear or binary search
Returns:

list of spans

Return type:

list

Linear Algebra

The linalg module contains some basic functions for point, vector and matrix operations.

Although most of the functions are designed for internal usage, the users can still use some of the functions for their advantage, especially the point and vector manipulation and generation functions. Functions related to point manipulation have point_ prefix and the ones related to vectors have vector_ prefix.

geomdl.linalg.backward_substitution(matrix_u, matrix_y)

Backward substitution method for the solution of linear systems.

Solves the equation Ux = y using backward substitution method where U is a upper triangular matrix and y is a column matrix.

Parameters:
  • matrix_u (list, tuple) – U, upper triangular matrix
  • matrix_y (list, tuple) – y, column matrix
Returns:

x, column matrix

Return type:

list

geomdl.linalg.binomial_coefficient(k, i)

Computes the binomial coefficient (denoted by k choose i).

Please see the following website for details: http://mathworld.wolfram.com/BinomialCoefficient.html

Parameters:
  • k (int) – size of the set of distinct elements
  • i (int) – size of the subsets
Returns:

combination of k and i

Return type:

float

geomdl.linalg.forward_substitution(matrix_l, matrix_b)

Forward substitution method for the solution of linear systems.

Solves the equation Ly = b using forward substitution method where L is a lower triangular matrix and b is a column matrix.

Parameters:
  • matrix_l (list, tuple) – L, lower triangular matrix
  • matrix_b (list, tuple) – b, column matrix
Returns:

y, column matrix

Return type:

list

geomdl.linalg.frange(start, stop, step=1.0)

Implementation of Python’s range() function which works with floats.

Reference to this implementation: https://stackoverflow.com/a/36091634

Parameters:
  • start (float) – start value
  • stop (float) – end value
  • step (float) – increment
Returns:

float

Return type:

generator

geomdl.linalg.linspace(start, stop, num, decimals=18)

Returns a list of evenly spaced numbers over a specified interval.

Inspired from Numpy’s linspace function: https://github.com/numpy/numpy/blob/master/numpy/core/function_base.py

Parameters:
  • start (float) – starting value
  • stop (float) – end value
  • num (int) – number of samples to generate
  • decimals (int) – number of significands
Returns:

a list of equally spaced numbers

Return type:

list

geomdl.linalg.lu_decomposition(matrix_a)

LU-Factorization method using Doolittle’s Method for solution of linear systems.

Decomposes the matrix A such that A = LU.

The input matrix is represented by a list or a tuple. The input matrix is 2-dimensional, i.e. list of lists of integers and/or floats.

Parameters:matrix_a (list, tuple) – Input matrix (must be a square matrix)
Returns:a tuple containing matrices L and U
Return type:tuple
geomdl.linalg.matrix_multiply(m1, m2)

Matrix multiplication (iterative algorithm).

The running time of the iterative matrix multiplication algorithm is O(n^{3}).

Parameters:
  • m1 (list, tuple) – 1st matrix with dimensions (n \times p)
  • m2 (list, tuple) – 2nd matrix with dimensions (p \times m)
Returns:

resultant matrix with dimensions (n \times m)

Return type:

list

geomdl.linalg.matrix_transpose(m)

Transposes the input matrix.

The input matrix m is a 2-dimensional array.

Parameters:m (list, tuple) – input matrix with dimensions (n \times m)
Returns:transpose matrix with dimensions (m \times n)
Return type:list
geomdl.linalg.point_distance(pt1, pt2)

Computes distance between two points.

Parameters:
  • pt1 (list, tuple) – point 1
  • pt2 (list, tuple) – point 2
Returns:

distance between input points

Return type:

float

geomdl.linalg.point_mid(pt1, pt2)

Computes the midpoint of the input points.

Parameters:
  • pt1 (list, tuple) – point 1
  • pt2 (list, tuple) – point 2
Returns:

midpoint

Return type:

list

geomdl.linalg.point_translate(point_in, vector_in)

Translates the input points using the input vector.

Parameters:
  • point_in (list, tuple) – input point
  • vector_in (list, tuple) – input vector
Returns:

translated point

Return type:

list

geomdl.linalg.vector_angle_between(vector1, vector2, **kwargs)

Computes the angle between the two input vectors.

If the keyword argument degrees is set to True, then the angle will be in degrees. Otherwise, it will be in radians. By default, degrees is set to True.

Parameters:
  • vector1 (list, tuple) – vector
  • vector2 (list, tuple) – vector
Returns:

angle between the vectors

Return type:

float

geomdl.linalg.vector_cross(vector1, vector2)

Computes the cross-product of the input vectors.

Parameters:
  • vector1 (list, tuple) – input vector 1
  • vector2 (list, tuple) – input vector 2
Returns:

result of the cross product

Return type:

tuple

geomdl.linalg.vector_dot(vector1, vector2)

Computes the dot-product of the input vectors.

Parameters:
  • vector1 (list, tuple) – input vector 1
  • vector2 (list, tuple) – input vector 2
Returns:

result of the dot product

Return type:

float

geomdl.linalg.vector_generate(start_pt, end_pt, normalize=False)

Generates a vector from 2 input points.

Parameters:
  • start_pt (list, tuple) – start point of the vector
  • end_pt (list, tuple) – end point of the vector
  • normalize (bool) – if True, the generated vector is normalized
Returns:

a vector from start_pt to end_pt

Return type:

list

geomdl.linalg.vector_is_zero(vector_in, tol=1e-07)

Checks if the input vector is a zero vector.

Parameters:
  • vector_in (list, tuple) – input vector
  • tol (float) – tolerance value
Returns:

True if the input vector is zero, False otherwise

Return type:

bool

geomdl.linalg.vector_magnitude(vector_in)

Computes the magnitude of the input vector.

Parameters:vector_in (list, tuple) – input vector
Returns:magnitude of the vector
Return type:float
geomdl.linalg.vector_mean(*args)

Computes the mean (average) of a list of vectors.

The function computes the arithmetic mean of a list of vectors, which are also organized as a list of integers or floating point numbers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Import geomdl.utilities module
from geomdl import utilities

# Create a list of vectors as an example
vector_list = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

# Compute mean vector
mean_vector = utilities.vector_mean(*vector_list)

# Alternative usage example (same as above):
mean_vector = utilities.vector_mean([1, 2, 3], [4, 5, 6], [7, 8, 9])
Parameters:args (list, tuple) – list of vectors
Returns:mean vector
Return type:list
geomdl.linalg.vector_multiply(vector_in, scalar)

Multiplies the vector with a scalar value.

This operation is also called vector scaling.

Parameters:
  • vector_in (list, tuple) – vector
  • scalar (int, float) – scalar value
Returns:

updated vector

Return type:

tuple

geomdl.linalg.vector_normalize(vector_in, decimals=18)

Generates a unit vector from the input.

Parameters:
  • vector_in (list, tuple) – vector to be normalized
  • decimals (int) – number of significands
Returns:

the normalized vector (i.e. the unit vector)

Return type:

list

geomdl.linalg.vector_sum(vector1, vector2, coeff=1.0)

Sums the vectors.

This function computes the result of the vector operation \overline{v}_{1} + c * \overline{v}_{2}, where \overline{v}_{1} is vector1, \overline{v}_{2} is vector2 and c is coeff.

Parameters:
  • vector1 (list, tuple) – vector 1
  • vector2 (list, tuple) – vector 2
  • coeff (float) – multiplier for vector 2
Returns:

updated vector

Return type:

list