bezier¶

bezier.curve module¶

Helper for Bézier Curves.

See Curve-Curve Intersection for examples using the Curve class to find intersections.

class bezier.curve.Curve(nodes, degree, start=0.0, end=1.0, root=None, _copy=True)¶

Bases: bezier._base.Base

Represents a Bézier curve.

We take the traditional definition: a Bézier curve is a mapping from \(s \in \left[0, 1\right]\) to convex combinations of points \(v_0, v_1, \ldots, v_n\) in some vector space:

\[B(s) = \sum_{j = 0}^n \binom{n}{j} s^j (1 - s)^{n - j} \cdot v_j\]

>>> import bezier
>>> nodes = np.array([
...     [0.0  , 0.0],
...     [0.625, 0.5],
...     [1.0  , 0.5],
... ])
>>> curve = bezier.Curve.from_nodes(nodes)
>>> curve
<Curve (degree=2, dimension=2)>

Parameters:

nodes (numpy.ndarray) – The nodes in the curve. The rows represent each node while the columns are the dimension of the ambient space. degree (int) – The degree of the curve. This is assumed to correctly correspond to the number of nodes. Use from_nodes() if the degree has not yet been computed. start (Optional [ float ]) – The beginning of the sub-interval that this curve represents. end (Optional [ float ]) – The end of the sub-interval that this curve represents. root (Optional [ Curve ]) – The root curve that contains this current curve. _copy (bool) – Flag indicating if the nodes should be copied before being stored. Defaults to True since callers may freely mutate nodes after passing in.

classmethod from_nodes(nodes, start=0.0, end=1.0, root=None, _copy=True)¶

Create a Curve from nodes.

Computes the degree based on the shape of nodes.

Parameters:	nodes (numpy.ndarray) – The nodes in the curve. The rows represent each node while the columns are the dimension of the ambient space. start (Optional [ float ]) – The beginning of the sub-interval that this curve represents. end (Optional [ float ]) – The end of the sub-interval that this curve represents. root (Optional [ Curve ]) – The root curve that contains this current curve. _copy (bool) – Flag indicating if the nodes should be copied before being stored. Defaults to True since callers may freely mutate nodes after passing in.
Returns:	The constructed curve.
Return type:	Curve

__repr__()¶

Representation of current object.

Returns:	Object representation.
Return type:	str

length¶

float: The length of the current curve.

start¶

float: Start of sub-interval this curve represents.

This value is used to track the current curve in the re-parameterization / subdivision process. The curve is still defined on the unit interval, but this value illustrates how this curve relates to a “parent” curve. For example:

>>> nodes = np.array([
...     [0.0, 0.0],
...     [1.0, 2.0],
... ])
>>> curve = bezier.Curve(nodes, 1)
>>> curve
<Curve (degree=1, dimension=2)>
>>> left, right = curve.subdivide()
>>> left
<Curve (degree=1, dimension=2, start=0, end=0.5)>
>>> right
<Curve (degree=1, dimension=2, start=0.5, end=1)>
>>> _, mid_right = left.subdivide()
>>> mid_right
<Curve (degree=1, dimension=2, start=0.25, end=0.5)>
>>> mid_right.nodes
array([[ 0.25, 0.5 ],
       [ 0.5 , 1.  ]])

end¶

float: End of sub-interval this curve represents.

See start for more information.

root¶

Curve: The “root” curve that contains the current curve.

This indicates that the current curve is a section of the “root” curve. For example:

>>> _, right = curve.subdivide()
>>> right
<Curve (degree=2, dimension=2, start=0.5, end=1)>
>>> right.root is curve
True
>>> right.evaluate(0.0) == curve.evaluate(0.5)
array([[ True, True]], dtype=bool)
>>>
>>> mid_left, _ = right.subdivide()
>>> mid_left
<Curve (degree=2, dimension=2, start=0.5, end=0.75)>
>>> mid_left.root is curve
True
>>> mid_left.evaluate(1.0) == curve.evaluate(0.75)
array([[ True, True]], dtype=bool)

edge_index¶

Optional [ int ] : The index of the edge among a group of edges.

>>> curve.edge_index
1
>>> curve.previous_edge
<Curve (degree=1, dimension=2)>
>>> curve.previous_edge.edge_index
0
>>> curve.next_edge
<Curve (degree=1, dimension=2)>
>>> curve.next_edge.edge_index
2

This is intended to be used when a Curve is created as part of a larger structure like a Surface or CurvedPolygon.

next_edge¶

Optional [ Curve ] : An edge that comes after the current one.

This is intended to be used when a Curve is created as part of a larger structure like a Surface or CurvedPolygon.

previous_edge¶

Optional [ Curve ] : An edge that comes before the current one.

This is intended to be used when a Curve is created as part of a larger structure like a Surface or CurvedPolygon.

evaluate(s)¶

Evaluate \(B(s)\) along the curve.

See evaluate_multi() for more details.

>>> nodes = np.array([
...     [0.0  , 0.0],
...     [0.625, 0.5],
...     [1.0  , 0.5],
... ])
>>> curve = bezier.Curve(nodes, 2)
>>> curve.evaluate(0.75)
array([[ 0.796875, 0.46875 ]])

Parameters:	s (float) – Parameter along the curve.
Returns:	The point on the curve (as a two dimensional NumPy array with a single row).
Return type:	numpy.ndarray

evaluate_multi(s_vals)¶

Evaluate \(B(s)\) for multiple points along the curve.

This is done by first evaluating each member of the Bernstein basis at each value in s_vals and then applying those to the control points for the current curve.

This is done instead of using de Casteljau’s algorithm. Implementing de Casteljau is problematic because it requires a choice between one of two methods:

• vectorize operations of the form \((1 - s)v + s w\), which requires a copy of the curve’s control points for each value in s_vals
• avoid vectorization and compute each point in serial

Instead, we can use vectorized operations to build up the Bernstein basis values.

>>> nodes = np.array([
...     [0.0, 0.0, 0.0],
...     [1.0, 2.0, 3.0],
... ])
>>> curve = bezier.Curve(nodes, 1)
>>> curve
<Curve (degree=1, dimension=3)>
>>> s_vals = np.linspace(0.0, 1.0, 5)
>>> curve.evaluate_multi(s_vals)
array([[ 0.  , 0.  , 0.  ],
       [ 0.25, 0.5 , 0.75],
       [ 0.5 , 1.  , 1.5 ],
       [ 0.75, 1.5 , 2.25],
       [ 1.  , 2.  , 3.  ]])

Parameters:	s_vals (numpy.ndarray) – Parameters along the curve (as a 1D array).
Returns:	The points on the curve. As a two dimensional NumPy array, with the rows corresponding to each s value and the columns to the dimension.
Return type:	numpy.ndarray

plot(num_pts, ax=None, show=False)¶

Plot the current curve.

Parameters:	num_pts (int) – Number of points to plot. ax (Optional [ matplotlib.artist.Artist ]) – matplotlib axis object to add plot to. show (Optional [ bool ]) – Flag indicating if the plot should be shown.
Returns:	The axis containing the plot. This may be a newly created axis.
Return type:	matplotlib.artist.Artist
Raises:	NotImplementedError – If the curve’s dimension is not 2.

subdivide()¶

Split the curve \(B(s)\) into a left and right half.

Takes the interval \(\left[0, 1\right]\) and splits the curve into \(B_1 = B\left(\left[0, \frac{1}{2}\right]\right)\) and \(B_2 = B\left(\left[\frac{1}{2}, 1\right]\right)\). In order to do this, also reparameterizes the curve, hence the resulting left and right halves have new nodes.

>>> nodes = np.array([
...     [0.0 , 0.0],
...     [1.25, 3.0],
...     [2.0 , 1.0],
... ])
>>> curve = bezier.Curve(nodes, 2)
>>> left, right = curve.subdivide()
>>> left
<Curve (degree=2, dimension=2, start=0, end=0.5)>
>>> left.nodes
array([[ 0.   , 0.   ],
       [ 0.625, 1.5  ],
       [ 1.125, 1.75 ]])
>>> right
<Curve (degree=2, dimension=2, start=0.5, end=1)>
>>> right.nodes
array([[ 1.125, 1.75 ],
       [ 1.625, 2.   ],
       [ 2.   , 1.   ]])

Returns:	The left and right sub-curves.
Return type:	Tuple [ Curve, Curve ]

intersect(other)¶

Find the points of intersection with another curve.

See Curve-Curve Intersection for more details.

>>> nodes1 = np.array([
...     [0.0  , 0.0  ],
...     [0.375, 0.75 ],
...     [0.75 , 0.375],
... ])
>>> curve1 = bezier.Curve(nodes1, 2)
>>> nodes2 = np.array([
...     [0.5, 0.0 ],
...     [0.5, 0.75],
... ])
>>> curve2 = bezier.Curve(nodes2, 1)
>>> intersections = curve1.intersect(curve2)
>>> intersections
array([[ 0.5, 0.5]])

Parameters:	other (Curve) – Other curve to intersect with.
Returns:	Array of intersection points (possibly empty).
Return type:	numpy.ndarray
Raises:	TypeError – If other is not a curve. NotImplementedError – If both curves aren’t two-dimensional.

elevate()¶

Return a degree-elevated version of the current curve.

Does this by converting the current nodes \(v_0, \ldots, v_n\) to new nodes \(w_0, \ldots, w_{n + 1}\) where

\[\begin{split}\begin{align*} w_0 &= v_0 \\ w_j &= \frac{j}{n + 1} v_{j - 1} + \frac{n + 1 - j}{n + 1} v_j \\ w_{n + 1} &= v_n \end{align*}\end{split}\]

Returns:	The degree-elevated curve.
Return type:	Curve

specialize(start, end)¶

Specialize the curve to a given sub-interval.

>>> curve = bezier.Curve.from_nodes(np.array([
...     [0.0, 0.0],
...     [0.5, 1.0],
...     [1.0, 0.0],
... ]))
>>> new_curve = curve.specialize(-0.25, 0.75)
>>> new_curve
<Curve (degree=2, dimension=2, start=-0.25, end=0.75)>
>>> new_curve.nodes
array([[-0.25 , -0.625],
       [ 0.25 ,  0.875],
       [ 0.75 ,  0.375]])

This is generalized version of subdivide(), and can even match the output of that method:

>>> left, right = curve.subdivide()
>>> also_left = curve.specialize(0.0, 0.5)
>>> np.all(also_left.nodes == left.nodes)
True
>>> also_right = curve.specialize(0.5, 1.0)
>>> np.all(also_right.nodes == right.nodes)
True

Parameters:	start (float) – The start point of the interval we are specializing to. end (float) – The end point of the interval we are specializing to.
Returns:	The newly-specialized curve.
Return type:	Curve

degree¶

int: The degree of the current shape.

dimension¶

int: The dimension that the shape lives in.

For example, if the shape lives in \(\mathbf{R}^3\), then the dimension is 3.

locate(point)¶

Find a point on the current curve.

Solves for \(s\) in \(B(s) = p\).

Note

A unique solution is only guaranteed if the current curve has no self-intersections. This code assumes, but doesn’t check, that this is true.

>>> curve = bezier.Curve.from_nodes(np.array([
...     [0.0, 0.0],
...     [1.0, 2.0],
...     [3.0, 1.0],
...     [4.0, 0.0],
... ]))
>>> point1 = np.array([[3.09375, 0.703125]])
>>> s = curve.locate(point1)
>>> s
0.75
>>> point2 = np.array([[2.0, 0.5]])
>>> curve.locate(point2) is None
True

Parameters:	point (numpy.ndarray) – A (1xD) point on the curve, where \(D\) is the dimension of the curve.
Returns:	The parameter value (\(s\)) corresponding to point or None if the point is not on the curve.
Return type:	Optional [ float ]
Raises:	ValueError – If the dimension of the point doesn’t match the dimension of the current curve.

nodes¶

numpy.ndarray: The nodes that define the current shape.

bezier.curved_polygon module¶

Curved polygon and associated helpers.

A curved polygon (in \(\mathbf{R}^2\)) is defined by the collection of Bézier curves that determine the boundary.

class bezier.curved_polygon.CurvedPolygon(*edges, **kwargs)¶

Bases: object

Represents an object defined by its curved boundary.

The boundary is a piecewise defined collection of Bézier curves.

Note

The direction of the nodes in each Curve on the boundary is important. When verifying, we check that one curve begins where the last one ended.

>>> import bezier
>>> edge0 = bezier.Curve.from_nodes(np.array([
...     [0.0,  0.0],
...     [1.0, -1.0],
...     [2.0,  0.0],
... ]))
>>> edge1 = bezier.Curve.from_nodes(np.array([
...     [2.0, 0.0],
...     [2.0, 1.0],
... ]))
>>> edge2 = bezier.Curve.from_nodes(np.array([
...     [2.0, 1.0],
...     [1.0, 2.0],
...     [0.0, 1.0],
... ]))
>>> edge3 = bezier.Curve.from_nodes(np.array([
...     [0.0, 1.0],
...     [0.0, 0.0],
... ]))
>>> curved_poly = bezier.CurvedPolygon(
...     edge0, edge1, edge2, edge3)
>>> curved_poly
<CurvedPolygon (num_sides=4)>

Though the endpoints of each pair of edges are verified to match, the curved polygon as a whole is not verified, so creating a curved polygon with self-intersections is possible:

>>> edge0 = bezier.Curve.from_nodes(np.array([
...     [0.0, 0.0],
...     [1.0, 0.0],
... ]))
>>> edge1 = bezier.Curve.from_nodes(np.array([
...     [1.0 , 0.0],
...     [1.25, 0.5],
...     [1.0 , 1.0],
... ]))
>>> edge2 = bezier.Curve.from_nodes(np.array([
...     [1.0, 1.0],
...     [2.0, 1.0],
... ]))
>>> edge3 = bezier.Curve.from_nodes(np.array([
...     [2.0, 1.0 ],
...     [1.0, 0.75],
...     [0.0, 0.0 ],
... ]))
>>> curved_poly = bezier.CurvedPolygon(
...     edge0, edge1, edge2, edge3)
>>> curved_poly
<CurvedPolygon (num_sides=4)>

Parameters:	edges (Tuple [ Curve, ... ]) – The boundary edges of the curved polygon. kwargs – The only keyword argument accepted is _verify, which is a bool indicating if the edges should be verified as having shared endpoints. It defaults to True.

num_sides¶

int: The number of sides in the current polygon.

__repr__()¶

Representation of current object.

Returns:	Object representation.
Return type:	str

plot(pts_per_edge, color=None, ax=None, show=False)¶

Plot the current curved polygon.

Parameters:	pts_per_edge (int) – Number of points to plot per curved edge. color (Optional [ Tuple [ float, float, float ] ]) – Color as RGB profile. ax (Optional [ matplotlib.artist.Artist ]) – matplotlib axis object to add plot to. show (Optional [ bool ]) – Flag indicating if the plot should be shown.
Returns:	The axis containing the plot. This may be a newly created axis.
Return type:	matplotlib.artist.Artist

bezier.surface module¶

Helper for Bézier Surfaces / Triangles.

class bezier.surface.Surface(nodes, degree, base_x=0.0, base_y=0.0, width=1.0, _copy=True)¶

Bases: bezier._base.Base

Represents a Bézier surface.

We define a Bézier triangle as a mapping from the unit simplex in 2D (i.e. the unit triangle) onto a surface in an arbitrary dimension. We use barycentric coordinates

\[\lambda_1 = 1 - s - t, \lambda_2 = s, \lambda_3 = t\]

for points in

\[\left\{(s, t) \mid 0 \leq s, t, s + t \leq 1\right\}.\]

As with curves, using these weights we get convex combinations of points \(v_{i, j, k}\) in some vector space:

\[B\left(\lambda_1, \lambda_2, \lambda_3\right) = \sum_{i + j + k = d} \binom{d}{i \, j \, k} \lambda_1^i \lambda_2^j \lambda_3^k \cdot v_{i, j, k}\]

Note

We assume the nodes are ordered from left-to-right and from bottom-to-top. So for example, the linear triangle:

(0,0,1)

(1,0,0)  (0,1,0)

is ordered as

\[\begin{split}\left[\begin{array}{c c c} v_{1,0,0} & v_{0,1,0} & v_{0,0,1} \end{array}\right]^T\end{split}\]

the quadratic triangle:

(0,0,2)

(1,0,1)  (0,1,1)

(2,0,0)  (1,1,0)  (0,2,0)

is ordered as

\[\begin{split}\left[\begin{array}{c c c c c c} v_{2,0,0} & v_{1,1,0} & v_{0,2,0} & v_{1,0,1} & v_{0,1,1} & v_{0,0,2} \end{array}\right]^T\end{split}\]

the cubic triangle:

(0,0,3)

(1,0,2)  (0,1,2)

(2,0,1)  (1,1,1)  (0,2,1)

(3,0,0)  (2,1,0)  (1,2,0)  (0,3,0)

is ordered as

\[\begin{split}\left[\begin{array}{c c c c c c c c c c} v_{3,0,0} & v_{2,1,0} & v_{1,2,0} & v_{0,3,0} & v_{2,0,1} & v_{1,1,1} & v_{0,2,1} & v_{1,0,2} & v_{0,1,2} & v_{0,0,3} \end{array}\right]^T\end{split}\]

and so on.

>>> import bezier
>>> nodes = np.array([
...     [0.0  , 0.0  ],
...     [0.5  , 0.0  ],
...     [1.0  , 0.25 ],
...     [0.125, 0.5  ],
...     [0.375, 0.375],
...     [0.25 , 1.0  ],
... ])
>>> surface = bezier.Surface(nodes, degree=2)
>>> surface
<Surface (degree=2, dimension=2)>

Parameters:

nodes (numpy.ndarray) – The nodes in the surface. The rows represent each node while the columns are the dimension of the ambient space. degree (int) – The degree of the surface. This is assumed to correctly correspond to the number of nodes. Use from_nodes() if the degree has not yet been computed. base_x (Optional [ float ]) – The \(x\)-coordinate of the base vertex of the sub-triangle that this surface represents. base_y (Optional [ float ]) – The \(y\)-coordinate of the base vertex of the sub-triangle that this surface represents. width (Optional [ float ]) – The width of the sub-triangle that this surface represents. _copy (bool) – Flag indicating if the nodes should be copied before being stored. Defaults to True since callers may freely mutate nodes after passing in.

classmethod from_nodes(nodes, base_x=0.0, base_y=0.0, width=1.0, _copy=True)¶

Create a Surface from nodes.

Computes the degree based on the shape of nodes.

Parameters:	nodes (numpy.ndarray) – The nodes in the surface. The rows represent each node while the columns are the dimension of the ambient space. base_x (Optional [ float ]) – The \(x\)-coordinate of the base vertex of the sub-triangle that this surface represents. base_y (Optional [ float ]) – The \(y\)-coordinate of the base vertex of the sub-triangle that this surface represents. width (Optional [ float ]) – The width of the sub-triangle that this surface represents. _copy (bool) – Flag indicating if the nodes should be copied before being stored. Defaults to True since callers may freely mutate nodes after passing in.
Returns:	The constructed surface.
Return type:	Surface

__repr__()¶

Representation of current object.

Returns:	Object representation.
Return type:	str

area¶

float: The area of the current surface.

Raises:	NotImplementedError – If the area isn’t already cached.

width¶

float: The “width” of the parameterized triangle.

When re-parameterizing (e.g. via subdivide()) we specialize the surface from the unit triangle to some sub-triangle. After doing this, we re-parameterize so that that sub-triangle is treated like the unit triangle.

To track which sub-triangle we are in during the subdivision process, we use the coordinates of the base vertex as well as the “width” of each leg.

>>> surface.base_x, surface.base_y
(0.0, 0.0)
>>> surface.width
1.0

Upon subdivision, the width halves (and potentially changes sign) and the vertex moves to one of four points:

>>> _, sub_surface_b, sub_surface_c, _ = surface.subdivide()
>>> sub_surface_b.base_x, sub_surface_b.base_y
(0.5, 0.5)
>>> sub_surface_b.width
-0.5
>>> sub_surface_c.base_x, sub_surface_c.base_y
(0.5, 0.0)
>>> sub_surface_c.width
0.5

base_x¶

float: The x-coordinate of the base vertex.

See width() for more detail.

base_y¶

float: The y-coordinate of the base vertex.

See width() for more detail.

edges¶

tuple: The edges of the surface.

>>> nodes = np.array([
...     [0.0   ,  0.0   ],
...     [0.5   , -0.1875],
...     [1.0   ,  0.0   ],
...     [0.1875,  0.5   ],
...     [0.625 ,  0.625 ],
...     [0.0   ,  1.0   ],
... ])
>>> surface = bezier.Surface(nodes, 2)
>>> edge1, _, _ = surface.edges
>>> edge1
<Curve (degree=2, dimension=2)>
>>> edge1.nodes
array([[ 0.  ,  0.    ],
       [ 0.5 , -0.1875],
       [ 1.  ,  0.    ]])

Returns:	The edges of the surface.
Return type:	Tuple [ Curve, Curve, Curve ]

evaluate_barycentric(lambda1, lambda2, lambda3, _verify=True)¶

Compute a point on the surface.

Evaluates \(B\left(\lambda_1, \lambda_2, \lambda_3\right)\).

>>> nodes = np.array([
...     [0.0  , 0.0  ],
...     [0.5  , 0.0  ],
...     [1.0  , 0.25 ],
...     [0.125, 0.5  ],
...     [0.375, 0.375],
...     [0.25 , 1.0  ],
... ])
>>> surface = bezier.Surface(nodes, 2)
>>> point = surface.evaluate_barycentric(0.125, 0.125, 0.75)
>>> point
array([[ 0.265625 , 0.73046875]])

However, this can’t be used for points outside the reference triangle:

>>> surface.evaluate_barycentric(-0.25, 0.75, 0.5)
Traceback (most recent call last):
  ...
ValueError: ('Parameters must be positive', -0.25, 0.75, 0.5)

or for non-Barycentric coordinates;

>>> surface.evaluate_barycentric(0.25, 0.25, 0.25)
Traceback (most recent call last):
  ...
ValueError: ('Values do not sum to 1', 0.25, 0.25, 0.25)

However, these “invalid” inputs can be used if _verify is False.

>>> surface.evaluate_barycentric(-0.25, 0.75, 0.5, _verify=False)
array([[ 0.6875 , 0.546875]])
>>> surface.evaluate_barycentric(0.25, 0.25, 0.25, _verify=False)
array([[ 0.203125, 0.1875 ]])

Parameters:	lambda1 (float) – Parameter along the reference triangle. lambda2 (float) – Parameter along the reference triangle. lambda3 (float) – Parameter along the reference triangle. _verify (Optional [ bool ]) – Indicates if the barycentric coordinates should be verified as summing to one and all non-negative (i.e. verified as barycentric). Can either be used to evaluate at points outside the domain, or to save time when the caller already knows the input is verified. Defaults to True.
Returns:	The point on the surface (as a two dimensional NumPy array with a single row).
Return type:	numpy.ndarray
Raises:	ValueError – If the weights are not valid barycentric coordinates, i.e. they don’t sum to 1. (Won’t raise if _verify=False.) ValueError – If some weights are negative. (Won’t raise if _verify=False.)

evaluate_cartesian(s, t, _verify=True)¶

Compute a point on the surface.

Evaluates \(B\left(1 - s - t, s, t\right)\) by calling evaluate_barycentric():

>>> nodes = np.array([
...     [0.0 , 0.0  ],
...     [0.5 , 0.5  ],
...     [1.0 , 0.625],
...     [0.0 , 0.5  ],
...     [0.5 , 0.5  ],
...     [0.25, 1.0  ],
... ])
>>> surface = bezier.Surface(nodes, 2)
>>> point = surface.evaluate_cartesian(0.125, 0.375)
>>> point
array([[ 0.16015625, 0.44726562]])
>>> surface.evaluate_barycentric(0.5, 0.125, 0.375)
array([[ 0.16015625, 0.44726562]])

Parameters:	s (float) – Parameter along the reference triangle. t (float) – Parameter along the reference triangle. _verify (Optional [ bool ]) – Indicates if the coordinates should be verified. See evaluate_barycentric(). Defaults to True.
Returns:	The point on the surface (as a two dimensional NumPy array).
Return type:	numpy.ndarray

evaluate_multi(param_vals, _verify=True)¶

Compute multiple points on the surface.

If param_vals has two columns, this method treats them as Cartesian:

>>> nodes = np.array([
...     [ 0.0, 0.0],
...     [ 2.0, 1.0],
...     [-3.0, 2.0],
... ])
>>> surface = bezier.Surface(nodes, 1)
>>> surface
<Surface (degree=1, dimension=2)>
>>> param_vals = np.array([
...     [0.0  , 0.0  ],
...     [0.125, 0.625],
...     [0.5  , 0.5  ],
... ])
>>> points = surface.evaluate_multi(param_vals)
>>> points
array([[ 0.   , 0.   ],
       [-1.625, 1.375],
       [-0.5  , 1.5  ]])

and if param_vals has three columns, treats them as Barycentric:

>>> nodes = np.array([
...     [ 0. , 0.  ],
...     [ 1. , 0.75],
...     [ 2. , 1.  ],
...     [-1.5, 1.  ],
...     [-0.5, 1.5 ],
...     [-3. , 2.  ],
... ])
>>> surface = bezier.Surface(nodes, 2)
>>> surface
<Surface (degree=2, dimension=2)>
>>> param_vals = np.array([
...     [0.   , 0.25, 0.75 ],
...     [1.   , 0.  , 0.   ],
...     [0.25 , 0.5 , 0.25 ],
...     [0.375, 0.25, 0.375],
... ])
>>> points = surface.evaluate_multi(param_vals)
>>> points
array([[-1.75  , 1.75    ],
       [ 0.    , 0.      ],
       [ 0.25  , 1.0625  ],
       [-0.625 , 1.046875]])

Note

This currently just uses evaluate_cartesian() and evaluate_barycentric() so is less performant than it could be.

Parameters:	param_vals (numpy.ndarray) – Array of parameter values (as a 2D array). _verify (Optional [ bool ]) – Indicates if the coordinates should be verified. See evaluate_barycentric(). Defaults to True.
Returns:	The point on the surface.
Return type:	numpy.ndarray
Raises:	ValueError – If param_vals is not a 2D array. ValueError – If param_vals doesn’t have 2 or 3 columns.

plot(pts_per_edge, color=None, ax=None, with_nodes=False, show=False)¶

Plot the current surface.

Parameters:	pts_per_edge (int) – Number of points to plot per edge. color (Optional [ Tuple [ float, float, float ] ]) – Color as RGB profile. ax (Optional [ matplotlib.artist.Artist ]) – matplotlib axis object to add plot to. with_nodes (Optional [ bool ]) – Determines if the control points should be added to the plot. Off by default. show (Optional [ bool ]) – Flag indicating if the plot should be shown.
Returns:	The axis containing the plot. This may be a newly created axis.
Return type:	matplotlib.artist.Artist
Raises:	NotImplementedError – If the surface’s dimension is not 2.

subdivide()¶

Split the surface into four sub-surfaces.

Does so by taking the unit triangle (i.e. the domain of the surface) and splitting it into four sub-triangles

Then the surface is re-parameterized via the map to/from the given sub-triangles and the unit triangle.

For example, when a degree two surface is subdivided:

>>> nodes = np.array([
...     [-1.0 , 0.0 ],
...     [ 0.5 , 0.5 ],
...     [ 2.0 , 0.0 ],
...     [ 0.25, 1.75],
...     [ 2.0 , 3.0 ],
...     [ 0.0 , 4.0 ],
... ])
>>> surface = bezier.Surface(nodes, 2)
>>> _, sub_surface_b, _, _ = surface.subdivide()
>>> sub_surface_b
<Surface (degree=2, dimension=2, base=(0.5, 0.5), width=-0.5)>
>>> sub_surface_b.nodes
array([[ 1.5   , 2.5   ],
       [ 0.6875, 2.3125],
       [-0.125 , 1.875 ],
       [ 1.1875, 1.3125],
       [ 0.4375, 1.3125],
       [ 0.5   , 0.25  ]])

Returns:	The lower left, central, lower right and upper left sub-surfaces (in that order).
Return type:	Tuple [ Surface, Surface, Surface, Surface ]

is_valid¶

bool: Flag indicating if the surface is “valid”.

Here, “valid” means there are no self-intersections or singularities.

This checks if the Jacobian of the map from the reference triangle is nonzero. For example, a linear “surface” with collinear points is invalid:

>>> nodes = np.array([
...     [0.0, 0.0],
...     [1.0, 1.0],
...     [2.0, 2.0],
... ])
>>> surface = bezier.Surface(nodes, 1)
>>> surface.is_valid
False

while a quadratic surface with one straight side:

>>> nodes = np.array([
...     [ 0.0  , 0.0  ],
...     [ 0.5  , 0.125],
...     [ 1.0  , 0.0  ],
...     [-0.125, 0.5  ],
...     [ 0.5  , 0.5  ],
...     [ 0.0  , 1.0  ],
... ])
>>> surface = bezier.Surface(nodes, 2)
>>> surface.is_valid
True

though not all higher degree surfaces are valid:

>>> nodes = np.array([
...     [1.0, 0.0],
...     [0.0, 0.0],
...     [1.0, 1.0],
...     [0.0, 0.0],
...     [0.0, 0.0],
...     [0.0, 1.0],
... ])
>>> surface = bezier.Surface(nodes, 2)
>>> surface.is_valid
False

locate(point)¶

Find a point on the current surface.

Solves for \(s\) and \(t\) in \(B(s, t) = p\).

Note

A unique solution is only guaranteed if the current surface is valid. This code assumes a valid surface, but doesn’t check.

>>> surface = bezier.Surface.from_nodes(np.array([
...     [0.0 ,  0.0 ],
...     [0.5 , -0.25],
...     [1.0 ,  0.0 ],
...     [0.25,  0.5 ],
...     [0.75,  0.75],
...     [0.0 ,  1.0 ],
... ]))
>>> point = np.array([[0.59375, 0.25]])
>>> s, t = surface.locate(point)
>>> s
0.5
>>> t
0.25

Parameters:	point (numpy.ndarray) – A (1xD) point on the surface, where \(D\) is the dimension of the surface.
Returns:	The \(s\) and \(t\) values corresponding to x_val and y_val or None if the point is not on the surface.
Return type:	Optional [ Tuple [ float, float ] ]
Raises:	NotImplementedError – If the surface isn’t in \(\mathbf{R}^2\). ValueError – If the dimension of the point doesn’t match the dimension of the current surface.

intersect(other, _verify=True)¶

Find the common intersection with another surface.

Parameters:	other (Surface) – Other surface to intersect with. _verify (Optional [ bool ]) – Indicates if extra caution should be used to verify assumptions about the algorithm as it proceeds. Can be disabled to speed up execution time. Defaults to True.
Returns:	List of intersections (possibly empty).
Return type:	List [ CurvedPolygon ]
Raises:	TypeError – If other is not a surface. NotImplementedError – If at least one of the surfaces isn’t two-dimensional.

elevate()¶

Return a degree-elevated version of the current surface.

Does this by converting the current nodes \(\left\{v_{i, j, k}\right\}_{i + j + k = d}\) to new nodes \(\left\{w_{i, j, k}\right\}_{i + j + k = d + 1}\). Does so by re-writing

\[E\left(\lambda_1, \lambda_2, \lambda_3\right) = \left(\lambda_1 + \lambda_2 + \lambda_3\right) B\left(\lambda_1, \lambda_2, \lambda_3\right) = \sum_{i + j + k = d + 1} \binom{d + 1}{i \, j \, k} \lambda_1^i \lambda_2^j \lambda_3^k \cdot w_{i, j, k}\]

In this form, we must have

\[\begin{split}\begin{align*} \binom{d + 1}{i \, j \, k} \cdot w_{i, j, k} &= \binom{d}{i - 1 \, j \, k} \cdot v_{i - 1, j, k} + \binom{d}{i \, j - 1 \, k} \cdot v_{i, j - 1, k} + \binom{d}{i \, j \, k - 1} \cdot v_{i, j, k - 1} \\ \Longleftrightarrow (d + 1) \cdot w_{i, j, k} &= i \cdot v_{i - 1, j, k} + j \cdot v_{i, j - 1, k} + k \cdot v_{i, j, k - 1} \end{align*}\end{split}\]

where we assume that, for example, \(v_{i, j, k - 1}\) is \(0\) (or any other unused value) if \(k = 0\).

>>> surface = bezier.Surface.from_nodes(np.array([
...     [0.0, 0.0],
...     [1.0, 0.0],
...     [0.0, 1.0],
... ]))
>>> surface
<Surface (degree=1, dimension=2)>
>>> new_surface = surface.elevate()
>>> new_surface
<Surface (degree=2, dimension=2)>
>>> new_surface.nodes
array([[ 0. , 0. ],
       [ 0.5, 0. ],
       [ 1. , 0. ],
       [ 0. , 0.5],
       [ 0.5, 0.5],
       [ 0. , 1. ]])

Returns:	The degree-elevated surface.
Return type:	Surface

degree¶

int: The degree of the current shape.

dimension¶

int: The dimension that the shape lives in.

For example, if the shape lives in \(\mathbf{R}^3\), then the dimension is 3.

nodes¶

numpy.ndarray: The nodes that define the current shape.