HM_ExtAPI::CurveNURBSGetData()

Returns parameters that define NURBS curves.

Syntax

bool CurveNURBSGetData(
const HM_EntityGeometryCurve& curve,
int& degree,
bool& rational,
int& num_knots,
int& num_poles,
double** knots,
HM_Point** poles,
double** weights
);

Type

HyperMesh Ext API Function

Description

The function expects that the type of curve object is HM_ExtAPI::NURBS_CURVE(). Application should call the function HM_ExtAPI::GeomCurveGetType() to verify the type before calling CurveNURBSGetData function.

To free arrays allocated for poles, weights and knots during the function call use the function HM_ExtAPI::MemoryFree().

The NURBS curve is defined by its degree D, the set of poles (also known as control points) {Pα} with index α taking values in the range 0 … N-1 where N is the total number of poles, and the set of parametric "knot" values {τβ} with index β taking values in the range 0 … M-1. In case the curve is rational then also a set of "weights" {wα} corresponding to each pole is required for the NURBS curve definition.

Parametric equation for the NURBS curve is given by

C(t) = ∑wα Pα NαD(t) / ∑ wα NαD(t)

where summation sign ∑ indicates the sum over all values of index α in the range 0 … N-1, and NαD(t) are the B-spline functions of the degree D defined by the knots vector {τβ}.

In the case of non-rational curve (rational is false) all pole weights are equal and the parametric equation simplifies to

C(t) = ∑ Pα NαD(t)

Parameters of the NURBS curve returned by the function CurveNURBSGetData satisfy "open end" boundary conditions. This means that first D +1 knots and last D + 1 knots in the knots vector have the same value:

τo = τ1 = … = τD

τM -1 = τM -2 = … = τM -1 - D

The total number of knots M and the total number of poles N satisfy the relation

M = N + D + 1

The following table clarifies correspondence between parameters used in the equations above and parameter values returned by the function CurveNURBSGetData.
Parameters used by CurveNURBSGetData NURBS curve parameters
degree D
rational If false then wα=1 implied for all α
num_knots M
num_poles N
knots {τβ}
poles {Pα}
weights {wα}

If the function succeeds, the return value is true. If the function fails, the return value is false. To get extended value information, call HM_ExtAPI::GetLastErrorCode().

Requires including hm_extapi.h.

Inputs

curve
[in] - Handle to curve object that was returned by previous calls to API functions.
degree
[out] - NURBS point.
rational
[out] - Returns true if curve NURBS is rational. Returns false if curve is non-rational B-spline.
num_knots
[out] - Number of knots.
num_poles
[out] - Number of poles.
knots
[out] - If not NULL on input then returns pointer to array of knot values. The number of values in the array is num_knots.
poles
[out] - If not NULL on input then returns pointer to array of NURBS poles. The number of values in the array is num_poles.
weights
[out] - If not NULL on input and rational is true then returns pointer to array of NURBS weights. The number of values in the array in this case is num_poles.

Errors

None.