NURBS Geometry

NURBS module provides data storage and evaluation functions for rational spline geometries.

Inheritance Diagram

Inheritance diagram of geomdl.NURBS

NURBS Curve

class geomdl.NURBS.Curve(**kwargs)

Bases: geomdl.BSpline.Curve

Data storage and evaluation class for n-variate NURBS (rational) curves.

The rational shapes have some minor differences between the non-rational ones. This class is designed to operate with weighted control points (Pw) as described in The NURBS Book by Piegl and Tiller. Therefore, it provides a different set of properties (i.e. getters and setters):

  • ctrlptsw: 1-dimensional array of weighted control points
  • ctrlpts: 1-dimensional array of control points
  • weights: 1-dimensional array of weights

You may also use set_ctrlpts() function which is designed to work with all types of control points.

This class provides the following properties:

The following code segment illustrates the usage of Curve class:

from geomdl import NURBS

# Create a 3-dimensional B-spline Curve
curve = NURBS.Curve()

# Set degree
curve.degree = 3

# Set control points (weights vector will be 1 by default)
# Use curve.ctrlptsw is if you are using homogeneous points as Pw
curve.ctrlpts = [[10, 5, 10], [10, 20, -30], [40, 10, 25], [-10, 5, 0]]

# Set knot vector
curve.knotvector = [0, 0, 0, 0, 1, 1, 1, 1]

# Set evaluation delta (controls the number of curve points)
curve.delta = 0.05

# Get curve points (the curve will be automatically evaluated)
curve_points = curve.evalpts

Keyword Arguments:

  • precision: number of decimal places to round to. Default: 18
  • normalize_kv: activates knot vector normalization. Default: True
  • find_span_func: sets knot span search implementation. Default: helpers.find_span_linear()
  • insert_knot_func: sets knot insertion implementation. Default: operations.insert_knot()
  • remove_knot_func: sets knot removal implementation. Default: operations.remove_knot()

Please refer to the abstract.Curve() documentation for more details.

bbox

Bounding box.

Evaluates the bounding box and returns the minimum and maximum coordinates.

Please refer to the wiki for details on using this class member.

Getter:Gets the bounding box
Type:tuple
binormal(parpos, **kwargs)

Evaluates the binormal vector of the curve at the given parametric position(s).

The param argument can be

  • a float value for evaluation at a single parametric position
  • a list of float values for evaluation at the multiple parametric positions

The return value will be in the order of the input parametric position list.

This method accepts the following keyword arguments:

  • normalize: normalizes the output vector. Default value is True.
Parameters:parpos (float, list or tuple) – parametric position(s) where the evaluation will be executed
Returns:an array containing “point” and “vector” pairs
Return type:tuple
ctrlpts

Control points (P).

Please refer to the wiki for details on using this class member.

Getter:Gets unweighted control points. Use weights to get weights vector.
Setter:Sets unweighted control points
Type:list
ctrlpts_size

Total number of control points.

Getter:Gets the total number of control points
Type:int
ctrlptsw

Weighted control points (Pw).

Weighted control points are in (x*w, y*w, z*w, w) format; where x,y,z are the coordinates and w is the weight.

Please refer to the wiki for details on using this class member.

Getter:Gets the weighted control points
Setter:Sets the weighted control points
data

Returns a dictionary containing all shape data.

Please refer to the wiki for details on using this class member.

degree

Degree.

Please refer to the wiki for details on using this class member.

Getter:Gets the degree
Setter:Sets the degree
Type:int
delta

Evaluation delta.

Evaluation delta corresponds to the step size while evaluate function iterates on the knot vector to generate curve points. Decreasing step size results in generation of more curve points. Therefore; smaller the delta value, smoother the curve.

The following figure illustrates the working principles of the delta property:

\left[{{u_{start}},{u_{start}} + \delta ,({u_{start}} + \delta ) + \delta , \ldots ,{u_{end}}} \right]

Please refer to the wiki for details on using this class member.

Getter:Gets the delta value
Setter:Sets the delta value
Type:float
derivatives(u, order=0, **kwargs)

Evaluates n-th order curve derivatives at the given parameter value.

Parameters:
  • u (float) – parameter value
  • order (int) – derivative order
Returns:

a list containing up to {order}-th derivative of the curve

Return type:

list

dimension

Spatial dimension.

Spatial dimension will be automatically estimated from the first element of the control points array.

Please refer to the wiki for details on using this class member.

Getter:Gets the spatial dimension, e.g. 2D, 3D, etc.
Type:int
domain

Domain.

Domain is determined using the knot vector(s).

Getter:Gets the domain
evalpts

Evaluated points.

Please refer to the wiki for details on using this class member.

Getter:Gets the coordinates of the evaluated points
Type:list
evaluate(**kwargs)

Evaluates the curve.

The evaluated points are stored in evalpts property.

Keyword arguments:
  • start: start parameter
  • stop: stop parameter

The start and stop parameters allow evaluation of a curve segment in the range [start, stop], i.e. the curve will also be evaluated at the stop parameter value.

The following examples illustrate the usage of the keyword arguments.

# Start evaluating from u=0.2 to u=1.0
curve.evaluate(start=0.2)

# Start evaluating from u=0.0 to u=0.7
curve.evaluate(stop=0.7)

# Start evaluating from u=0.1 to u=0.5
curve.evaluate(start=0.1, stop=0.5)

# Get the evaluated points
curve_points = curve.evalpts
evaluate_list(param_list)

Evaluates the curve for an input range of parameters.

Parameters:param_list (list, tuple) – list of parameters
Returns:evaluated surface points at the input parameters
Return type:list
evaluate_single(param)

Evaluates the curve at the input parameter.

Parameters:param (float) – parameter
Returns:evaluated surface point at the given parameter
Return type:list
evaluator

Evaluator instance.

Evaluators allow users to use different algorithms for B-Spline and NURBS evaluations. Please see the documentation on Evaluator classes.

Please refer to the wiki for details on using this class member.

Getter:Gets the current Evaluator instance
Setter:Sets the Evaluator instance
Type:evaluators.AbstractEvaluator
id

Object ID (as an integer).

Please refer to the wiki for details on using this class member.

Getter:Gets the object ID
Setter:Sets the object ID
Type:int
insert_knot(param, **kwargs)

Inserts the knot and updates the control points array and the knot vector.

Keyword Arguments:
  • num: Number of knot insertions. Default: 1
Parameters:param (float) – knot to be inserted
knotvector

Knot vector.

The knot vector will be normalized to [0, 1] domain if the class is initialized with normalize_kv=True argument.

Please refer to the wiki for details on using this class member.

Getter:Gets the knot vector
Setter:Sets the knot vector
Type:list
load(file_name)

Loads the curve from a pickled file.

Parameters:file_name (str) – name of the file to be loaded
Raises:IOError – an error occurred reading the file
name

Object name (as a string)

Please refer to the wiki for details on using this class member.

Getter:Gets the object name
Setter:Sets the object name
Type:str
normal(parpos, **kwargs)

Evaluates the normal vector of the curve at the given parametric position(s).

The param argument can be

  • a float value for evaluation at a single parametric position
  • a list of float values for evaluation at the multiple parametric positions

The return value will be in the order of the input parametric position list.

This method accepts the following keyword arguments:

  • normalize: normalizes the output vector. Default value is True.
Parameters:parpos (float, list or tuple) – parametric position(s) where the evaluation will be executed
Returns:an array containing “point” and “vector” pairs
Return type:tuple
opt

Dictionary for storing custom data in the current geometry object.

opt is a wrapper to a dict in key => value format, where key is string, value is any Python object. You can use opt property to store custom data inside the geometry object. For instance:

geom.opt = ["face_id", 4]  # creates "face_id" key and sets its value to an integer
geom.opt = ["contents", "data values"]  # creates "face_id" key and sets its value to a string
print(geom.opt)  # will print: {'face_id': 4, 'contents': 'data values'}

del geom.opt  # deletes the contents of the hash map
print(geom.opt)  # will print: {}

geom.opt = ["body_id", 1]  # creates "body_id" key  and sets its value to 1
geom.opt = ["body_id", 12]  # changes the value of "body_id" to 12
print(geom.opt)  # will print: {'body_id': 12}

geom.opt = ["body_id", None]  # deletes "body_id"
print(geom.opt)  # will print: {}

Please refer to the wiki for details on using this class member.

Getter:Gets the dict
Setter:Adds key and value pair to the dict
Deleter:Deletes the contents of the dict
opt_get(value)

Safely query for the value from the opt property.

Parameters:value (str) – a key in the opt property
Returns:the corresponding value, if the key exists. None, otherwise.
order

Order.

Defined as order = degree + 1

Please refer to the wiki for details on using this class member.

Getter:Gets the order
Setter:Sets the order
Type:int
pdimension

Parametric dimension.

Please refer to the wiki for details on using this class member.

Getter:Gets the parametric dimension
Type:int
range

Domain range.

Getter:Gets the range
rational

Defines the rational and non-rational B-spline shapes.

Rational shapes use homogeneous coordinates which includes a weight alongside with the Cartesian coordinates. Rational B-splines are also named as NURBS (Non-uniform rational basis spline) and non-rational B-splines are sometimes named as NUBS (Non-uniform basis spline) or directly as B-splines.

Please refer to the wiki for details on using this class member.

Getter:Returns True is the B-spline object is rational (NURBS)
Type:bool
remove_knot(param, **kwargs)

Removes the knot and updates the control points array and the knot vector.

Keyword Arguments:
  • num: Number of knot removals. Default: 1
Parameters:param (float) – knot to be removed
render(**kwargs)

Renders the curve using the visualization component

The visualization component must be set using vis property before calling this method.

Keyword Arguments:
  • cpcolor: sets the color of the control points polygon
  • evalcolor: sets the color of the curve
  • bboxcolor: sets the color of the bounding box
  • filename: saves the plot with the input name
  • plot: controls plot window visibility. Default: True
  • animate: activates animation (if supported). Default: False
  • extras: adds line plots to the figure. Default: None

plot argument is useful when you would like to work on the command line without any window context. If plot flag is False, this method saves the plot as an image file (.png file where possible) and disables plot window popping out. If you don’t provide a file name, the name of the image file will be pulled from the configuration class.

extras argument can be used to add extra line plots to the figure. This argument expects a list of dicts in the format described below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
    dict(  # line plot 1
        points=[[1, 2, 3], [4, 5, 6]],  # list of points
        name="My line Plot 1",  # name displayed on the legend
        color="red",   # color of the line plot
        size=6.5  # size of the line plot
    ),
    dict(  # line plot 2
        points=[[7, 8, 9], [10, 11, 12]],  # list of points
        name="My line Plot 2",  # name displayed on the legend
        color="navy",   # color of the line plot
        size=12.5  # size of the line plot
    )
]
reset(**kwargs)

Resets control points and/or evaluated points.

Keyword Arguments:

  • evalpts: if True, then resets evaluated points
  • ctrlpts if True, then resets control points
reverse()

Reverses the curve

sample_size

Sample size.

Sample size defines the number of evaluated points to generate. It also sets the delta property.

The following figure illustrates the working principles of sample size property:

\underbrace {\left[ {{u_{start}}, \ldots ,{u_{end}}} \right]}_{{n_{sample}}}

Please refer to the wiki for details on using this class member.

Getter:Gets sample size
Setter:Sets sample size
Type:int
save(file_name)

Saves the curve as a pickled file.

Parameters:file_name (str) – name of the file to be saved
Raises:IOError – an error occurred writing the file
set_ctrlpts(ctrlpts, *args, **kwargs)

Sets control points and checks if the data is consistent.

This method is designed to provide a consistent way to set control points whether they are weighted or not. It directly sets the control points member of the class, and therefore it doesn’t return any values. The input will be an array of coordinates. If you are working in the 3-dimensional space, then your coordinates will be an array of 3 elements representing (x, y, z) coordinates.

Parameters:ctrlpts (list) – input control points as a list of coordinates
tangent(param, **kwargs)

Evaluates the tangent vector of the curve at the given parametric position(s).

The param argument can be

  • a float value for evaluation at a single parametric position
  • a list of float values for evaluation at the multiple parametric positions

The return value will be in the order of the input parametric position list.

This method accepts the following keyword arguments:

  • normalize: normalizes the output vector. Default value is True.
Parameters:param (float, list or tuple) – parametric position(s) where the evaluation will be executed
Returns:an array containing “point” and “vector” pairs
Return type:tuple
type

Geometry type

Please refer to the wiki for details on using this class member.

Getter:Gets the geometry type
Type:str
vis

Visualization component.

Please refer to the wiki for details on using this class member.

Getter:Gets the visualization component
Setter:Sets the visualization component
Type:vis.VisAbstract
weights

Weights vector.

Please refer to the wiki for details on using this class member.

Getter:Gets the weights vector
Setter:Sets the weights vector
Type:list

NURBS Surface

class geomdl.NURBS.Surface(**kwargs)

Bases: geomdl.BSpline.Surface

Data storage and evaluation class for NURBS (rational) surfaces.

The rational shapes have some minor differences between the non-rational ones. This class is designed to operate with weighted control points (Pw) as described in The NURBS Book by Piegl and Tiller. Therefore, it provides a different set of properties (i.e. getters and setters):

  • ctrlptsw: 1-dimensional array of weighted control points
  • ctrlpts2d: 2-dimensional array of weighted control points
  • ctrlpts: 1-dimensional array of control points
  • weights: 1-dimensional array of weights

You may also use set_ctrlpts() function which is designed to work with all types of control points.

This class provides the following properties:

The following code segment illustrates the usage of Surface class:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from geomdl import NURBS

# Create a NURBS surface instance
surf = NURBS.Surface()

# Set degrees
surf.degree_u = 3
surf.degree_v = 2

# Set control points (weights vector will be 1 by default)
# Use curve.ctrlptsw is if you are using homogeneous points as Pw
control_points = [[0, 0, 0], [0, 4, 0], [0, 8, -3],
                  [2, 0, 6], [2, 4, 0], [2, 8, 0],
                  [4, 0, 0], [4, 4, 0], [4, 8, 3],
                  [6, 0, 0], [6, 4, -3], [6, 8, 0]]
surf.set_ctrlpts(control_points, 4, 3)

# Set knot vectors
surf.knotvector_u = [0, 0, 0, 0, 1, 1, 1, 1]
surf.knotvector_v = [0, 0, 0, 1, 1, 1]

# Set evaluation delta (control the number of surface points)
surf.delta = 0.05

# Get surface points (the surface will be automatically evaluated)
surface_points = surf.evalpts

Keyword Arguments:

  • precision: number of decimal places to round to. Default: 18
  • normalize_kv: activates knot vector normalization. Default: True
  • find_span_func: sets knot span search implementation. Default: helpers.find_span_linear()
  • insert_knot_func: sets knot insertion implementation. Default: operations.insert_knot()
  • remove_knot_func: sets knot removal implementation. Default: operations.remove_knot()

Please refer to the abstract.Surface() documentation for more details.

bbox

Bounding box.

Evaluates the bounding box and returns the minimum and maximum coordinates.

Please refer to the wiki for details on using this class member.

Getter:Gets the bounding box
Type:tuple
ctrlpts

1-dimensional array of control points (P).

This property sets and gets the control points in 1-D.

Getter:Gets unweighted control points. Use weights to get weights vector.
Setter:Sets unweighted control points.
Type:list
ctrlpts2d

2-dimensional array of control points.

The getter returns a tuple of 2D control points (weighted control points + weights if NURBS) in [u][v] format. The rows of the returned tuple correspond to v-direction and the columns correspond to u-direction.

The following example can be used to traverse 2D control points:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# Create a BSpline surface
surf_bs = BSpline.Surface()

# Do degree, control points and knot vector assignments here

# Each u includes a row of v values
for u in surf_bs.ctrlpts2d:
    # Each row contains the coordinates of the control points
    for v in u:
        print(str(v))  # will be something like (1.0, 2.0, 3.0)

# Create a NURBS surface
surf_nb = NURBS.Surface()

# Do degree, weighted control points and knot vector assignments here

# Each u includes a row of v values
for u in surf_nb.ctrlpts2d:
    # Each row contains the coordinates of the weighted control points
    for v in u:
        print(str(v))  # will be something like (0.5, 1.0, 1.5, 0.5)

When using NURBS.Surface class, the output of ctrlpts2d property could be confusing since, ctrlpts always returns the unweighted control points, i.e. ctrlpts property returns 3D control points all divided by the weights and you can use weights property to access the weights vector, but ctrlpts2d returns the weighted ones plus weights as the last element. This difference is intentionally added for compatibility and interoperability purposes.

To explain this situation in a simple way;

  • If you need the weighted control points directly, use ctrlpts2d
  • If you need the control points and the weights separately, use ctrlpts and weights

Note

Please note that the setter doesn’t check for inconsistencies and using the setter is not recommended. Instead of the setter property, please use set_ctrlpts() function.

Please refer to the wiki for details on using this class member.

Getter:Gets the control points as a 2-dimensional array in [u][v] format
Setter:Sets the control points as a 2-dimensional array in [u][v] format
Type:list
ctrlpts_size

Total number of control points.

Getter:Gets the total number of control points
Type:int
ctrlpts_size_u

Number of control points for the u-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets number of control points for the u-direction
Setter:Sets number of control points for the u-direction
ctrlpts_size_v

Number of control points for the v-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets number of control points on the v-direction
Setter:Sets number of control points on the v-direction
ctrlptsw

1-dimensional array of weighted control points (Pw).

Weighted control points are in (x*w, y*w, z*w, w) format; where x,y,z are the coordinates and w is the weight.

This property sets and gets the control points in 1-D.

Getter:Gets weighted control points
Setter:Sets weighted control points
data

Returns a dictionary containing all shape data.

Please refer to the wiki for details on using this class member.

degree

Degree for u- and v-directions

Getter:Gets the degree
Setter:Sets the degree
Type:list
degree_u

Degree for the u-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets degree for the u-direction
Setter:Sets degree for the u-direction
Type:int
degree_v

Degree for the v-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets degree for the v-direction
Setter:Sets degree for the v-direction
Type:int
delta

Evaluation delta for both u- and v-directions.

Evaluation delta corresponds to the step size while evaluate() function iterates on the knot vector to generate surface points. Decreasing step size results in generation of more surface points. Therefore; smaller the delta value, smoother the surface.

Please note that delta and sample_size properties correspond to the same variable with different descriptions. Therefore, setting delta will also set sample_size.

The following figure illustrates the working principles of the delta property:

\left[{{u_{0}},{u_{start}} + \delta ,({u_{start}} + \delta ) + \delta , \ldots ,{u_{end}}} \right]

Please refer to the wiki for details on using this class member.

Getter:Gets evaluation delta as a tuple of values corresponding to u- and v-directions
Setter:Sets evaluation delta for both u- and v-directions
Type:float
delta_u

Evaluation delta for the u-direction.

Evaluation delta corresponds to the step size while evaluate() function iterates on the knot vector to generate surface points. Decreasing step size results in generation of more surface points. Therefore; smaller the delta value, smoother the surface.

Please note that delta_u and sample_size_u properties correspond to the same variable with different descriptions. Therefore, setting delta_u will also set sample_size_u.

Please refer to the wiki for details on using this class member.

Getter:Gets evaluation delta for the u-direction
Setter:Sets evaluation delta for the u-direction
Type:float
delta_v

Evaluation delta for the v-direction.

Evaluation delta corresponds to the step size while evaluate() function iterates on the knot vector to generate surface points. Decreasing step size results in generation of more surface points. Therefore; smaller the delta value, smoother the surface.

Please note that delta_v and sample_size_v properties correspond to the same variable with different descriptions. Therefore, setting delta_v will also set sample_size_v.

Please refer to the wiki for details on using this class member.

Getter:Gets evaluation delta for the v-direction
Setter:Sets evaluation delta for the v-direction
Type:float
derivatives(u, v, order=0, **kwargs)

Evaluates n-th order surface derivatives at the given (u, v) parameter pair.

  • SKL[0][0] will be the surface point itself
  • SKL[0][1] will be the 1st derivative w.r.t. v
  • SKL[2][1] will be the 2nd derivative w.r.t. u and 1st derivative w.r.t. v
Parameters:
  • u (float) – parameter on the u-direction
  • v (float) – parameter on the v-direction
  • order (integer) – derivative order
Returns:

A list SKL, where SKL[k][l] is the derivative of the surface S(u,v) w.r.t. u k times and v l times

Return type:

list

dimension

Spatial dimension.

Spatial dimension will be automatically estimated from the first element of the control points array.

Please refer to the wiki for details on using this class member.

Getter:Gets the spatial dimension, e.g. 2D, 3D, etc.
Type:int
domain

Domain.

Domain is determined using the knot vector(s).

Getter:Gets the domain
evalpts

Evaluated points.

Please refer to the wiki for details on using this class member.

Getter:Gets the coordinates of the evaluated points
Type:list
evaluate(**kwargs)

Evaluates the surface.

The evaluated points are stored in evalpts property.

Keyword arguments:
  • start_u: start parameter on the u-direction
  • stop_u: stop parameter on the u-direction
  • start_v: start parameter on the v-direction
  • stop_v: stop parameter on the v-direction

The start_u, start_v and stop_u and stop_v parameters allow evaluation of a surface segment in the range [start_u, stop_u][start_v, stop_v] i.e. the surface will also be evaluated at the stop_u and stop_v parameter values.

The following examples illustrate the usage of the keyword arguments.

1
2
3
4
5
6
7
8
# Start evaluating in range u=[0, 0.7] and v=[0.1, 1]
surf.evaluate(stop_u=0.7, start_v=0.1)

# Start evaluating in range u=[0, 1] and v=[0.1, 0.3]
surf.evaluate(start_v=0.1, stop_v=0.3)

# Get the evaluated points
surface_points = surf.evalpts
evaluate_list(param_list)

Evaluates the surface for a given list of (u, v) parameters.

Parameters:param_list (list, tuple) – list of parameter pairs (u, v)
Returns:evaluated surface point at the input parameter pairs
Return type:tuple
evaluate_single(param)

Evaluates the surface at the input (u, v) parameter pair.

Parameters:param (list, tuple) – parameter pair (u, v)
Returns:evaluated surface point at the given parameter pair
Return type:list
evaluator

Evaluator instance.

Evaluators allow users to use different algorithms for B-Spline and NURBS evaluations. Please see the documentation on Evaluator classes.

Please refer to the wiki for details on using this class member.

Getter:Gets the current Evaluator instance
Setter:Sets the Evaluator instance
Type:evaluators.AbstractEvaluator
faces

Faces (triangles, quads, etc.) generated by the tessellation operation.

If the tessellation component is set to None, the result will be an empty list.

Getter:Gets the faces
id

Object ID (as an integer).

Please refer to the wiki for details on using this class member.

Getter:Gets the object ID
Setter:Sets the object ID
Type:int
insert_knot(u=None, v=None, **kwargs)

Inserts knot(s) on the u- or v-directions

Keyword Arguments:
  • num_u: Number of knot insertions on the u-direction. Default: 1
  • num_v: Number of knot insertions on the v-direction. Default: 1
Parameters:
  • u (float) – knot to be inserted on the u-direction
  • v (float) – knot to be inserted on the v-direction
knotvector

Knot vector for u- and v-directions

Getter:Gets the knot vector
Setter:Sets the knot vector
Type:list
knotvector_u

Knot vector for the u-direction.

The knot vector will be normalized to [0, 1] domain if the class is initialized with normalize_kv=True argument.

Please refer to the wiki for details on using this class member.

Getter:Gets knot vector for the u-direction
Setter:Sets knot vector for the u-direction
Type:list
knotvector_v

Knot vector for the v-direction.

The knot vector will be normalized to [0, 1] domain if the class is initialized with normalize_kv=True argument.

Please refer to the wiki for details on using this class member.

Getter:Gets knot vector for the v-direction
Setter:Sets knot vector for the v-direction
Type:list
load(file_name)

Loads the surface from a pickled file.

Parameters:file_name (str) – name of the file to be loaded
Raises:IOError – an error occurred reading the file
name

Object name (as a string)

Please refer to the wiki for details on using this class member.

Getter:Gets the object name
Setter:Sets the object name
Type:str
normal(parpos, **kwargs)

Evaluates the normal vector of the surface at the given parametric position(s).

The param argument can be

  • a float value for evaluation at a single parametric position
  • a list of float values for evaluation at the multiple parametric positions

The parametric positions should be a pair of (u,v) values. The return value will be in the order of the input parametric position list.

This method accepts the following keyword arguments:

  • normalize: normalizes the output vector. Default value is True.
Parameters:parpos (list or tuple) – parametric position(s) where the evaluation will be executed
Returns:an array containing “point” and “vector” pairs
Return type:tuple
opt

Dictionary for storing custom data in the current geometry object.

opt is a wrapper to a dict in key => value format, where key is string, value is any Python object. You can use opt property to store custom data inside the geometry object. For instance:

geom.opt = ["face_id", 4]  # creates "face_id" key and sets its value to an integer
geom.opt = ["contents", "data values"]  # creates "face_id" key and sets its value to a string
print(geom.opt)  # will print: {'face_id': 4, 'contents': 'data values'}

del geom.opt  # deletes the contents of the hash map
print(geom.opt)  # will print: {}

geom.opt = ["body_id", 1]  # creates "body_id" key  and sets its value to 1
geom.opt = ["body_id", 12]  # changes the value of "body_id" to 12
print(geom.opt)  # will print: {'body_id': 12}

geom.opt = ["body_id", None]  # deletes "body_id"
print(geom.opt)  # will print: {}

Please refer to the wiki for details on using this class member.

Getter:Gets the dict
Setter:Adds key and value pair to the dict
Deleter:Deletes the contents of the dict
opt_get(value)

Safely query for the value from the opt property.

Parameters:value (str) – a key in the opt property
Returns:the corresponding value, if the key exists. None, otherwise.
order_u

Order for the u-direction.

Defined as order = degree + 1

Please refer to the wiki for details on using this class member.

Getter:Gets order for the u-direction
Setter:Sets order for the u-direction
Type:int
order_v

Order for the v-direction.

Defined as order = degree + 1

Please refer to the wiki for details on using this class member.

Getter:Gets surface order for the v-direction
Setter:Sets surface order for the v-direction
Type:int
pdimension

Parametric dimension.

Please refer to the wiki for details on using this class member.

Getter:Gets the parametric dimension
Type:int
range

Domain range.

Getter:Gets the range
rational

Defines the rational and non-rational B-spline shapes.

Rational shapes use homogeneous coordinates which includes a weight alongside with the Cartesian coordinates. Rational B-splines are also named as NURBS (Non-uniform rational basis spline) and non-rational B-splines are sometimes named as NUBS (Non-uniform basis spline) or directly as B-splines.

Please refer to the wiki for details on using this class member.

Getter:Returns True is the B-spline object is rational (NURBS)
Type:bool
remove_knot(u=None, v=None, **kwargs)

Inserts knot(s) on the u- or v-directions

Keyword Arguments:
  • num_u: Number of knot removals on the u-direction. Default: 1
  • num_v: Number of knot removals on the v-direction. Default: 1
Parameters:
  • u (float) – knot to be removed on the u-direction
  • v (float) – knot to be removed on the v-direction
render(**kwargs)

Renders the surface using the visualization component.

The visualization component must be set using vis property before calling this method.

Keyword Arguments:
  • cpcolor: sets the color of the control points grid
  • evalcolor: sets the color of the surface
  • trimcolor: sets the color of the trim curves
  • filename: saves the plot with the input name
  • plot: controls plot window visibility. Default: True
  • animate: activates animation (if supported). Default: False
  • extras: adds line plots to the figure. Default: None
  • colormap: sets the colormap of the surface

The plot argument is useful when you would like to work on the command line without any window context. If plot flag is False, this method saves the plot as an image file (.png file where possible) and disables plot window popping out. If you don’t provide a file name, the name of the image file will be pulled from the configuration class.

extras argument can be used to add extra line plots to the figure. This argument expects a list of dicts in the format described below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
    dict(  # line plot 1
        points=[[1, 2, 3], [4, 5, 6]],  # list of points
        name="My line Plot 1",  # name displayed on the legend
        color="red",   # color of the line plot
        size=6.5  # size of the line plot
    ),
    dict(  # line plot 2
        points=[[7, 8, 9], [10, 11, 12]],  # list of points
        name="My line Plot 2",  # name displayed on the legend
        color="navy",   # color of the line plot
        size=12.5  # size of the line plot
    )
]

Please note that colormap argument can only work with visualization classes that support colormaps. As an example, please see VisMPL.VisSurfTriangle() class documentation. This method expects a single colormap input.

reset(**kwargs)

Resets control points and/or evaluated points.

Keyword Arguments:

  • evalpts: if True, then resets evaluated points
  • ctrlpts if True, then resets control points
sample_size

Sample size for both u- and v-directions.

Sample size defines the number of surface points to generate. It also sets the delta property.

The following figure illustrates the working principles of sample size property:

\underbrace {\left[ {{u_{start}}, \ldots ,{u_{end}}} \right]}_{{n_{sample}}}

Please refer to the wiki for details on using this class member.

Getter:Gets sample size as a tuple of values corresponding to u- and v-directions
Setter:Sets sample size for both u- and v-directions
Type:int
sample_size_u

Sample size for the u-direction.

Sample size defines the number of surface points to generate. It also sets the delta_u property.

Please refer to the wiki for details on using this class member.

Getter:Gets sample size for the u-direction
Setter:Sets sample size for the u-direction
Type:int
sample_size_v

Sample size for the v-direction.

Sample size defines the number of surface points to generate. It also sets the delta_v property.

Please refer to the wiki for details on using this class member.

Getter:Gets sample size for the v-direction
Setter:Sets sample size for the v-direction
Type:int
save(file_name)

Saves the surface as a pickled file.

Parameters:file_name (str) – name of the file to be saved
Raises:IOError – an error occurred writing the file
set_ctrlpts(ctrlpts, *args, **kwargs)

Sets the control points and checks if the data is consistent.

This method is designed to provide a consistent way to set control points whether they are weighted or not. It directly sets the control points member of the class, and therefore it doesn’t return any values. The input will be an array of coordinates. If you are working in the 3-dimensional space, then your coordinates will be an array of 3 elements representing (x, y, z) coordinates.

This method also generates 2D control points in [u][v] format which can be accessed via ctrlpts2d.

Note

The v index varies first. That is, a row of v control points for the first u value is found first. Then, the row of v control points for the next u value.

Parameters:ctrlpts (list) – input control points as a list of coordinates
tangent(parpos, **kwargs)

Evaluates the tangent vectors of the surface at the given parametric position(s).

The param argument can be

  • a float value for evaluation at a single parametric position
  • a list of float values for evaluation at the multiple parametric positions

The parametric positions should be a pair of (u,v) values. The return value will be in the order of the input parametric position list.

This method accepts the following keyword arguments:

  • normalize: normalizes the output vector. Default value is True.
Parameters:parpos (list or tuple) – parametric position(s) where the evaluation will be executed
Returns:an array containing “point” and “vector”s on u- and v-directions, respectively
Return type:tuple
tessellate(**kwargs)

Tessellates the surface.

Keyword arguments are directly passed to the tessellation component.

tessellator

Tessellation component.

Please refer to the wiki for details on using this class member.

Getter:Gets the tessellation component
Setter:Sets the tessellation component
transpose()

Transposes the surface by swapping u and v parametric directions.

trims

Trim curves.

Trim curves are introduced to the surfaces on the parametric space. They should be contained as a list or tuple. Using tessellate.TrimTessellate tessellator class, trimmed regions of the surfaces can be visualized. In addition, using trims initialization argument of the visualization classes, trim curves can be visualized directly.

Please refer to the wiki for details on using this class member.

Getter:Gets the array of trim curves
Setter:Sets the array of trim curves
type

Geometry type

Please refer to the wiki for details on using this class member.

Getter:Gets the geometry type
Type:str
vertices

Vertices generated by the tessellation operation.

If the tessellation component is set to None, the result will be an empty list.

Getter:Gets the vertices
vis

Visualization component.

Please refer to the wiki for details on using this class member.

Getter:Gets the visualization component
Setter:Sets the visualization component
Type:vis.VisAbstract
weights

Weights vector.

Getter:Gets the weights vector
Setter:Sets the weights vector
Type:list

NURBS Volume

New in version 5.0.

class geomdl.NURBS.Volume(**kwargs)

Bases: geomdl.BSpline.Volume

Data storage and evaluation class for NURBS (rational) volumes.

The rational shapes have some minor differences between the non-rational ones. This class is designed to operate with weighted control points (Pw) as described in The NURBS Book by Piegl and Tiller. Therefore, it provides a different set of properties (i.e. getters and setters):

  • ctrlptsw: 1-dimensional array of weighted control points
  • ctrlpts: 1-dimensional array of control points
  • weights: 1-dimensional array of weights

This class provides the following properties:

Keyword Arguments:

  • precision: number of decimal places to round to. Default: 18
  • normalize_kv: activates knot vector normalization. Default: True
  • find_span_func: sets knot span search implementation. Default: helpers.find_span_linear()
  • insert_knot_func: sets knot insertion implementation. Default: operations.insert_knot()
  • remove_knot_func: sets knot removal implementation. Default: operations.remove_knot()

Please refer to the abstract.Volume() documentation for more details.

bbox

Bounding box.

Evaluates the bounding box and returns the minimum and maximum coordinates.

Please refer to the wiki for details on using this class member.

Getter:Gets the bounding box
Type:tuple
ctrlpts

1-dimensional array of control points (P).

This property sets and gets the control points in 1-D.

Getter:Gets unweighted control points. Use weights to get weights vector.
Setter:Sets unweighted control points.
Type:list
ctrlpts_size

Total number of control points.

Getter:Gets the total number of control points
Type:int
ctrlpts_size_u

Number of control points for the u-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets number of control points for the u-direction
Setter:Sets number of control points for the u-direction
ctrlpts_size_v

Number of control points for the v-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets number of control points for the v-direction
Setter:Sets number of control points for the v-direction
ctrlpts_size_w

Number of control points for the w-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets number of control points for the w-direction
Setter:Sets number of control points for the w-direction
ctrlptsw

1-dimensional array of weighted control points (Pw).

Weighted control points are in (x*w, y*w, z*w, w) format; where x,y,z are the coordinates and w is the weight.

This property sets and gets the control points in 1-D.

Getter:Gets weighted control points
Setter:Sets weighted control points
data

Returns a dictionary containing all shape data.

Please refer to the wiki for details on using this class member.

degree

Degree for u-, v- and w-directions

Getter:Gets the degree
Setter:Sets the degree
Type:list
degree_u

Degree for the u-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets degree for the u-direction
Setter:Sets degree for the u-direction
Type:int
degree_v

Degree for the v-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets degree for the v-direction
Setter:Sets degree for the v-direction
Type:int
degree_w

Degree for the w-direction.

Please refer to the wiki for details on using this class member.

Getter:Gets degree for the w-direction
Setter:Sets degree for the w-direction
Type:int
delta

Evaluation delta for u-, v- and w-directions.

Evaluation delta corresponds to the step size while evaluate() function iterates on the knot vector to generate surface points. Decreasing step size results in generation of more surface points. Therefore; smaller the delta value, smoother the surface.

Please note that delta and sample_size properties correspond to the same variable with different descriptions. Therefore, setting delta will also set sample_size.

The following figure illustrates the working principles of the delta property:

\left[{{u_{0}},{u_{start}} + \delta ,({u_{start}} + \delta ) + \delta , \ldots ,{u_{end}}} \right]

Please refer to the wiki for details on using this class member.

Getter:Gets evaluation delta as a tuple of values corresponding to u-, v- and w-directions
Setter:Sets evaluation delta for u-, v- and w-directions
Type:float
delta_u

Evaluation delta for the u-direction.

Evaluation delta corresponds to the step size while evaluate() function iterates on the knot vector to generate surface points. Decreasing step size results in generation of more surface points. Therefore; smaller the delta value, smoother the surface.

Please note that delta_u and sample_size_u properties correspond to the same variable with different descriptions. Therefore, setting delta_u will also set sample_size_u.

Please refer to the wiki for details on using this class member.

Getter:Gets evaluation delta for the u-direction
Setter:Sets evaluation delta for the u-direction
Type:float
delta_v

Evaluation delta for the v-direction.

Evaluation delta corresponds to the step size while evaluate() function iterates on the knot vector to generate surface points. Decreasing step size results in generation of more surface points. Therefore; smaller the delta value, smoother the surface.

Please note that delta_v and sample_size_v properties correspond to the same variable with different descriptions. Therefore, setting delta_v will also set sample_size_v.

Please refer to the wiki for details on using this class member.

Getter:Gets evaluation delta for the v-direction
Setter:Sets evaluation delta for the v-direction
Type:float
delta_w

Evaluation delta for the w-direction.

Evaluation delta corresponds to the step size while evaluate() function iterates on the knot vector to generate surface points. Decreasing step size results in generation of more surface points. Therefore; smaller the delta value, smoother the surface.

Please note that delta_w and sample_size_w properties correspond to the same variable with different descriptions. Therefore, setting delta_w will also set sample_size_w.

Please refer to the wiki for details on using this class member.

Getter:Gets evaluation delta for the w-direction
Setter:Sets evaluation delta for the w-direction
Type:float
dimension

Spatial dimension.

Spatial dimension will be automatically estimated from the first element of the control points array.

Please refer to the wiki for details on using this class member.

Getter:Gets the spatial dimension, e.g. 2D, 3D, etc.
Type:int
domain

Domain.

Domain is determined using the knot vector(s).

Getter:Gets the domain
evalpts

Evaluated points.

Please refer to the wiki for details on using this class member.

Getter:Gets the coordinates of the evaluated points
Type:list
evaluate(**kwargs)

Evaluates the volume.

The evaluated points are stored in evalpts property.

Keyword arguments:
  • start_u: start parameter on the u-direction
  • stop_u: stop parameter on the u-direction
  • start_v: start parameter on the v-direction
  • stop_v: stop parameter on the v-direction
  • start_w: start parameter on the w-direction
  • stop_w: stop parameter on the w-direction
evaluate_list(param_list)

Evaluates the volume for a given list of (u, v, w) parameters.

Parameters:param_list (list, tuple) – list of parameters in format (u, v, w)
Returns:evaluated surface point at the input parameter pairs
Return type:tuple
evaluate_single(param)

Evaluates the volume at the input (u, v, w) parameter.

Parameters:param (list, tuple) – parameter (u, v, w)
Returns:evaluated surface point at the given parameter pair
Return type:list
evaluator

Evaluator instance.

Evaluators allow users to use different algorithms for B-Spline and NURBS evaluations. Please see the documentation on Evaluator classes.

Please refer to the wiki for details on using this class member.

Getter:Gets the current Evaluator instance
Setter:Sets the Evaluator instance
Type:evaluators.AbstractEvaluator
id

Object ID (as an integer).

Please refer to the wiki for details on using this class member.

Getter:Gets the object ID
Setter:Sets the object ID
Type:int
insert_knot(u=None, v=None, w=None, **kwargs)

Inserts knot(s) on the u-, v- and w-directions

Keyword Arguments:
  • num_u: Number of knot insertions on the u-direction. Default: 1
  • num_v: Number of knot insertions on the v-direction. Default: 1
  • num_w: Number of knot insertions on the w-direction. Default: 1
Parameters:
  • u (float) – knot to be inserted on the u-direction
  • v (float) – knot to be inserted on the v-direction
  • w (float) – knot to be inserted on the w-direction
knotvector

Knot vector for u-, v- and w-directions

Getter:Gets the knot vector
Setter:Sets the knot vector
Type:list
knotvector_u

Knot vector for the u-direction.

The knot vector will be normalized to [0, 1] domain if the class is initialized with normalize_kv=True argument.

Please refer to the wiki for details on using this class member.

Getter:Gets knot vector for the u-direction
Setter:Sets knot vector for the u-direction
Type:list
knotvector_v

Knot vector for the v-direction.

The knot vector will be normalized to [0, 1] domain if the class is initialized with normalize_kv=True argument.

Please refer to the wiki for details on using this class member.

Getter:Gets knot vector for the v-direction
Setter:Sets knot vector for the v-direction
Type:list
knotvector_w

Knot vector for the w-direction.

The knot vector will be normalized to [0, 1] domain if the class is initialized with normalize_kv=True argument.

Please refer to the wiki for details on using this class member.

Getter:Gets knot vector for the w-direction
Setter:Sets knot vector for the w-direction
Type:list
load(file_name)

Loads the volume from a pickled file.

Parameters:file_name (str) – name of the file to be loaded
Raises:IOError – an error occurred reading the file
name

Object name (as a string)

Please refer to the wiki for details on using this class member.

Getter:Gets the object name
Setter:Sets the object name
Type:str
opt

Dictionary for storing custom data in the current geometry object.

opt is a wrapper to a dict in key => value format, where key is string, value is any Python object. You can use opt property to store custom data inside the geometry object. For instance:

geom.opt = ["face_id", 4]  # creates "face_id" key and sets its value to an integer
geom.opt = ["contents", "data values"]  # creates "face_id" key and sets its value to a string
print(geom.opt)  # will print: {'face_id': 4, 'contents': 'data values'}

del geom.opt  # deletes the contents of the hash map
print(geom.opt)  # will print: {}

geom.opt = ["body_id", 1]  # creates "body_id" key  and sets its value to 1
geom.opt = ["body_id", 12]  # changes the value of "body_id" to 12
print(geom.opt)  # will print: {'body_id': 12}

geom.opt = ["body_id", None]  # deletes "body_id"
print(geom.opt)  # will print: {}

Please refer to the wiki for details on using this class member.

Getter:Gets the dict
Setter:Adds key and value pair to the dict
Deleter:Deletes the contents of the dict
opt_get(value)

Safely query for the value from the opt property.

Parameters:value (str) – a key in the opt property
Returns:the corresponding value, if the key exists. None, otherwise.
order_u

Order for the u-direction.

Defined as order = degree + 1

Please refer to the wiki for details on using this class member.

Getter:Gets the surface order for u-direction
Setter:Sets the surface order for u-direction
Type:int
order_v

Order for the v-direction.

Defined as order = degree + 1

Please refer to the wiki for details on using this class member.

Getter:Gets the surface order for v-direction
Setter:Sets the surface order for v-direction
Type:int
order_w

Order for the w-direction.

Defined as order = degree + 1

Please refer to the wiki for details on using this class member.

Getter:Gets the surface order for v-direction
Setter:Sets the surface order for v-direction
Type:int
pdimension

Parametric dimension.

Please refer to the wiki for details on using this class member.

Getter:Gets the parametric dimension
Type:int
range

Domain range.

Getter:Gets the range
rational

Defines the rational and non-rational B-spline shapes.

Rational shapes use homogeneous coordinates which includes a weight alongside with the Cartesian coordinates. Rational B-splines are also named as NURBS (Non-uniform rational basis spline) and non-rational B-splines are sometimes named as NUBS (Non-uniform basis spline) or directly as B-splines.

Please refer to the wiki for details on using this class member.

Getter:Returns True is the B-spline object is rational (NURBS)
Type:bool
remove_knot(u=None, v=None, w=None, **kwargs)

Inserts knot(s) on the u-, v- and w-directions

Keyword Arguments:
  • num_u: Number of knot removals on the u-direction. Default: 1
  • num_v: Number of knot removals on the v-direction. Default: 1
  • num_w: Number of knot removals on the w-direction. Default: 1
Parameters:
  • u (float) – knot to be removed on the u-direction
  • v (float) – knot to be removed on the v-direction
  • w (float) – knot to be removed on the w-direction
render(**kwargs)

Renders the volume using the visualization component.

The visualization component must be set using vis property before calling this method.

Keyword Arguments:
  • cpcolor: sets the color of the control points
  • evalcolor: sets the color of the volume
  • filename: saves the plot with the input name
  • plot: controls plot window visibility. Default: True
  • animate: activates animation (if supported). Default: False
  • grid_size: grid size for voxelization. Default: (8, 8, 8)
  • use_cubes: use cube voxels instead of cuboid ones. Default: False
  • num_procs: number of concurrent processes for voxelization. Default: 1

The plot argument is useful when you would like to work on the command line without any window context. If plot flag is False, this method saves the plot as an image file (.png file where possible) and disables plot window popping out. If you don’t provide a file name, the name of the image file will be pulled from the configuration class.

extras argument can be used to add extra line plots to the figure. This argument expects a list of dicts in the format described below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
    dict(  # line plot 1
        points=[[1, 2, 3], [4, 5, 6]],  # list of points
        name="My line Plot 1",  # name displayed on the legend
        color="red",   # color of the line plot
        size=6.5  # size of the line plot
    ),
    dict(  # line plot 2
        points=[[7, 8, 9], [10, 11, 12]],  # list of points
        name="My line Plot 2",  # name displayed on the legend
        color="navy",   # color of the line plot
        size=12.5  # size of the line plot
    )
]
reset(**kwargs)

Resets control points and/or evaluated points.

Keyword Arguments:

  • evalpts: if True, then resets the evaluated points
  • ctrlpts if True, then resets the control points
sample_size

Sample size for both u- and v-directions.

Sample size defines the number of surface points to generate. It also sets the delta property.

The following figure illustrates the working principles of sample size property:

\underbrace {\left[ {{u_{start}}, \ldots ,{u_{end}}} \right]}_{{n_{sample}}}

Please refer to the wiki for details on using this class member.

Getter:Gets sample size as a tuple of values corresponding to u-, v- and w-directions
Setter:Sets sample size value for both u-, v- and w-directions
Type:int
sample_size_u

Sample size for the u-direction.

Sample size defines the number of evaluated points to generate. It also sets the delta_u property.

Please refer to the wiki for details on using this class member.

Getter:Gets sample size for the u-direction
Setter:Sets sample size for the u-direction
Type:int
sample_size_v

Sample size for the v-direction.

Sample size defines the number of evaluated points to generate. It also sets the delta_v property.

Please refer to the wiki for details on using this class member.

Getter:Gets sample size for the v-direction
Setter:Sets sample size for the v-direction
Type:int
sample_size_w

Sample size for the w-direction.

Sample size defines the number of evaluated points to generate. It also sets the delta_w property.

Please refer to the wiki for details on using this class member.

Getter:Gets sample size for the w-direction
Setter:Sets sample size for the w-direction
Type:int
save(file_name)

Saves the volume as a pickled file.

Parameters:file_name (str) – name of the file to be saved
Raises:IOError – an error occurred writing the file
set_ctrlpts(ctrlpts, *args, **kwargs)

Sets the control points and checks if the data is consistent.

This method is designed to provide a consistent way to set control points whether they are weighted or not. It directly sets the control points member of the class, and therefore it doesn’t return any values. The input will be an array of coordinates. If you are working in the 3-dimensional space, then your coordinates will be an array of 3 elements representing (x, y, z) coordinates.

Parameters:
  • ctrlpts (list) – input control points as a list of coordinates
  • args (tuple[int, int, int]) – number of control points corresponding to each parametric dimension
type

Geometry type

Please refer to the wiki for details on using this class member.

Getter:Gets the geometry type
Type:str
vis

Visualization component.

Please refer to the wiki for details on using this class member.

Getter:Gets the visualization component
Setter:Sets the visualization component
Type:vis.VisAbstract
weights

Weights vector.

Getter:Gets the weights vector
Setter:Sets the weights vector
Type:list