AlCurve

Synopsis

#include <AlCurve.h>
class AlCurve : public AlObject
AlCurve();
virtual	~AlCurve();
virtual statusCode	deleteObject();
virtual AlObject*	copyWrapper() const;
statusCode	create( int, curveFormType, int, const double[], int, const double[][4], const int[]);
statusCode	create( int, curveFormType, const double[], int, const double[][4]);
statusCode	createLine( const double[3], const double[3] );
statusCode	createArc( const double[3], const double[3], const double[3], boolean );
statusCode createArc( double *, double *, double *, double,double, double, int=3, boolean=TRUE );
statusCode	createConic( double, double, double, double, double, double, const double[3], const double[3] );
statusCode	createParabola( const double[3], const double[3], const double[3], const double[3] );
statusCode	createEllipse( const double[3], const double[3], const double[3], const double[3], const double[3] );
statusCode	createHyperbola( const double[3], const double[3], const double[3], const double[3], const double[3] );
statusCode	createPoint( const double[3] );
virtual AlObjectType	type() const;
AlCurveNode* 	curveNode() const;
curveFormType	form() const;
int	degree() const;
int	numberOfSpans() const;
int	numberOfCVs() const;
AlCurveCV*	firstCV() const;
AlCurveCV*	getCV( int ) const;
AlAttributes*	firstAttribute() const;
statusCode	CVsWorldPosition( double[][4], int[] ) const;
statusCode	CVsAffectedPosition( const AlTM&, double[][4], int[] ) const;
statusCode	CVsUnaffectedPosition( double[][4], int[] ) const;
statusCode	setCVsUnaffectedPosition( const double[][4] );
statusCode	length( double& len, boolean worldCoords = TRUE, double tolerance=0.001 );
statusCode	eval(double, boolean, double P[3] = NULL, double dP[3] = NULL ) const;
statusCode	eval( double dist, double P[3], double &t, boolean worldCoordinates = TRUE, double tolerance = 0.001) const;
int	numberOfKnots() const;
statusCode	knotVector( double[] ) const;
statusCode	setKnotVector( const double[] );
int	numberOfCVsInclMultiples() const;
statusCode	CVsWorldPositionInclMultiples( double[][4] )const;
statusCode	CVsAffectedPositionInclMultiples( const AlTM&, double[][4] ) const;
statusCode	CVsUnaffectedPositionInclMultiples( double[][4] ) const;
statusCode	setCVsUnaffectedPositionInclMultiples( const double[][4] );
int	realNumberOfKnots() const;
statusCode	realKnotVector( double[] ) const;
statusCode	setRealKnotVector( const double[] );
boolean	isDisplayModeSet( AlDisplayModeType ) const;
statusCode	setDisplayMode( AlDisplayModeType, boolean );
statusCode	applyIteratorToCVs( AlIterator*, int& );
statusCode	doUpdates( boolean newState = TRUE );
statusCode	periodicToNonPeriodic() const;
statusCode	normal(double [3]) const;
statusCode	insert( double param );
statusCode	append( double pos[4], AlPointType type );
statusCode	reverseCurve();
statusCode	extendCurve( double , double [4] );
statusCode	incrementDegree();
statusCode	adjustEndSpan( double );
statusCode	trimCurve( double, double );

Description

AlCurve is the interface to the geometric data of Alias’ NURBS curve objects. To create a curve, first instantiate and create an AlCurve and then instantiate and create an AlCurveNode.

For more information on how to create the curve geometry, see the description for the create() method.

A curve form can be one of three types: periodic, closed or open. If a curve is "kPeriodic", it is tangent continuous at all points on the curve and its endpoints are coincident. If a curve is "kClosed", it is not periodic but its endpoints are coincident. If the curve is neither closed nor periodic, it is considered to be "kOpen".

There are two ways to delete an AlCurve. If the AlCurve destructor is called, the attached AlCurveNode is deleted. If the AlCurveNode destructor is called, the attached AlCurve is deleted.

You should always create a curve node for a curve. If you create a curve with no curve node, the curve is not added to the universe. If you should lose the pointer to the curve, it will become lost memory.

There is one limitation to this class: you cannot add or remove individual curve control points (except by changing multiplicity).

Curves are made of curve control points (or CVs) which you can traverse as a list by using AlCurve::firstCV() plus the AlCurveCV methods. You can also pack the curve information into an array using methods in this class.

What is multiplicity?

An AlCurveCV object can actually represent multiple CVs, depending on the AlCurveCVs multiplicity and periodicity. Notice that in this class there are two sets of methods - some "InclMultiples" and some not (namely "numberOfCVs", "CVsWorldPosition", "CVsUnaffectedPosition", etc). The set of methods without multiplicity lets you get all curve CV’s where a curve CV can have multiplicity of 1, 2 or 3. The set of methods "InclMultiples" lets you get ALL curve CVs including multiples due to a multiplicity > 1 and due to periodicity.

Example 1

If you create a curve in the interactive Alias package with 4 CVs and change the multiplicity of the second CV to 2 (using the "multiplicity" menu item in the Curve Tools menu), then:

numberOfCVs() will return 4.
CVsWorldPosition must be passed a 4x4 CVs matrix, and a multiplicity vector of length 4.
CVsUnaffectedPosition() must be passed the same as item 2.
setCVsUnaffectedPosition() must be passed the same as item 2.
numberOfCVsInclMultiples() will return 5.
CVsWorldPositionInclMultiples() must be passed a 5x4 CVs matrix. You will notice that the 2nd and 3rd points in this matrix are the same.
CVsUnaffectedPositionInclMultiples() must be passed the same as item 6. You will notice that the 2nd and 3rd points in this matrix are the same.
setCVsUnaffectedPositionInclMultiples() must be passed the same as item 6. The matrix you pass in should have the 2nd and 3rd points the same. What really happens in this method is that the 3rd point is given the same value as the 2nd point. (What you give as the 3rd point is ignored.)

Example 2

If you create a curve in the interactive Alias package with 4 CVs and "close" the curve (using the "close" menu item in the Object Tools menu), you create a periodic curve. Then:

numberOfCVs() will return 4.
CVsWorldPosition must be passed a 4x4 CVs matrix, and a multiplicity vector of length 4.
CVsUnaffectedPosition() must be passed the same as item 2.
setCVsUnaffectedPosition() must be passed the same as item 2.
numberOfCVsInclMultiples() will return 7.
CVsWorldPositionInclMultiples() must be passed a 7x4 CVs matrix. You will notice that in this matrix the 5th, 6th and 7th points are the same as the 1st, 2nd and 3rd points respectively.
CVsUnaffectedPositionInclMultiples() must be passed the same as item 6. You will notice that in this matrix the 5th, 6th and 7th points are the same as the 1st, 2nd and 3rd points respectively.
setCVsUnaffectedPositionInclMultiples() must be passed the same as item 6. The matrix you pass in should have the 5th, 6th and 7th points the same as the 1st, 2nd and 3rd points respectively. What really happens in this method is that the 5th, 6th and 7th points are assigned the same values as the 1st, 2nd and 3rd points respectively. (What you give for the 5th, 6th and 7th points are ignored.)

AlCurve::AlCurve()

Description

Constructs an AlCurve wrapper object.

AlCurve::~AlCurve()

Description

Deletes an AlCurve wrapper object.

AlObject *AlCurve::copyWrapper() const

Description

Returns an exact copy of the AlCurve wrapper.

statusCode AlCurve::deleteObject()

Description

Deletes the AlCurve.

Return Codes

sSuccess - the curve was deleted

sInvalidObject - the curve was invalid

sInsufficientMemory - ran out of memory

AlObjectType AlCurve::type() const

Description

Returns the class identifier kCurveType.

AlCurveNode* AlCurve::curveNode() const

Description

Returns the curve node associated with this curve. Returns NULL if there is no attached curve node.

curveFormType AlCurve::form() const

Description

When a curve is periodic it means that its endpoints are coincident and that the curve is tangent continuous at the point where its endpoints touch. "kPeriodic" is returned in this case. "kClosed" is returned if the curve is not periodic, but if its endpoints are coincident. If a curve is neither "kPeriodic" nor "kClosed" then "kOpen" is returned. (Note: If you use the "close" menu item in the interactive Alias package, you actually make a curve periodic.)

int AlCurve::degree() const

Description

Returns the degree of the curve. -1 is returned if the curve is not valid.

int AlCurve::numberOfSpans() const

Description

Returns the number of spans in the curve. -1 is returned if the curve is not valid.

int AlCurve::numberOfCVs() const

Description

Returns the number of CVs. -1 is returned if the curve is not valid.

AlCurveCV* AlCurve::firstCV() const

Description

Returns a pointer to the first CV in the curve.

AlCurveCV* AlCurve::getCV( int index ) const

Description

Returns a pointer to the CV of the given index. Returns NULL if the CV could not be found or the index was negative. The index of the first CV is 0.

AlAttributes* AlCurve::firstAttribute() const

Description

Returns the first attribute on this curve if any, otherwise NULL is returned. Note that if CV positions are modified through any of the AlCurve, AlCurveCV, AlCluster, AlSet, and so on, then the attributes are removed from the curve.

statusCode AlCurve::CVsWorldPosition( double CVList[][4], int multiplicity[] ) const

Description

Returns the CVs in the given CV array and the multiplicity of each CV in the multiplicity vector. The first dimension of the CV array must be numberOfCVs(). The length of the multiplicity vector must also be numberOfCVs(). The multiplicity vector returned by this function is the same as the one returned by CVsUnaffectedPosition().

Arguments

> CVList - returned CV positions

> multiplicity - the multiplicity of each CV

Return Codes

sSuccess - the curve CVs positions were returned

sInvalidObject - the curve was not valid

sFailure - an error occurred

sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::CVsAffectedPosition( const AlTM& tm, double CVList[][4], int multiplicity[] ) const

Description

Returns the CVs in the given CV array and the multiplicity of each CV in the multiplicity vector. The first dimension of the CV array must be numberOfCVs(). The length of the multiplicity vector must also be numberOfCVs(). The multiplicity vector returned by this function is the same as the one returned by CVsUnaffectedPosition().

Arguments

< tm - the transformation matrix built by transversing the DAG

> CVList - returned CV positions

> multiplicity - the multiplicity of each CV

Return Codes

sSuccess - the curve CVs positions were returned

sInvalidObject - the curve was not valid

sFailure - an error occurred

sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::CVsUnaffectedPosition( double CVList[][4],int multiplicity[] ) const

Description

Returns the CVs in the given CV array and the multiplicity of each CV in the multiplicity vector. The first dimension of the CV array must be numberOfCVs(). The length of the multiplicity vector must also be numberOfCVs(). The multiplicity vector returned by this function is the same as the one returned by CVsWorldPosition().

Arguments

> CVList - returned CV positions

> multiplicity - the multiplicity of each CV

Return Codes

sSuccess - the curve CVs positions were returned

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied

sFailure - an error occurred

statusCode AlCurve::doUpdates( boolean newState )

Description

See AlDagNode for information.

statusCode AlCurve::setCVsUnaffectedPosition( const double CVList[][4] )

Description

Sets the CVs of this curve to the values in the given CV array. The first dimension of the CV array must be numberOfCVs().

Arguments

< CVList - CV positions

Return Codes

sSuccess - the curve CVs positions were set

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied

sFailure - an error occurred

statusCode AlCurve::eval(double t, boolean worldCoordinates, double P[3], double dP[3] ) const

Description

Determines the 3D coordinate and the derivative of the parameter value on the curve.

Arguments

< t - parameter position on the curve

< worldCoordinates - the evaluation is done in world coordinates

> P - the local position on the curve (if not NULL)

> dP - the derivative of the curve at t (if not NULL)

Return Codes

sSuccess - the coordinate was successfully determined

sFailure - the evaluation failed

sInvalidObject - the curve was invalid

statusCode AlCurve::eval( double dist, double P[3], double &t, boolean worldCoordinates, double tolerance ) const

Description

Determines 3D coordinates of a point at a given distance from the start of a curve. Error tolerance must be greater than zero.

Arguments

< dist - arc length position on the curve

> P - position of the point on the curve

> t - parameter position on the curve

< worldCoordinates - the evaluation is done in world coordinates

< tolerance - the error tolerance

Return Codes

sSuccess - the coordinate was successfully determined

sFailure - the evaluation failed

sInvalidObject - the curve was invalid

sInvalidArgument - tolerance was non-positive

int AlCurve::numberOfKnots() const

Description

Returns the number of knots in this curve. For more information as to what this number means, see the description for the create() method. -1 is returned if the curve is not valid.

statusCode AlCurve::knotVector( double knotVector[]) const

Description

Returns the knot vector in the given vector. This vector must be of length numberOfKnots(). For more information as to what these values mean, see the description for the create() method.

Arguments

> knotVector - returned knot vector

Return Codes

sSuccess - the knot vector was returned

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::setKnotVector( const double knotVector[] )

Description

Sets the knot vector to be the given vector. This vector must be of length numberOfKnots(). For more information as to what these values mean, see the description for the create() method.

Arguments

< knotVector - the knot vector to be the given vector

Return Codes

sSuccess - the knot vector was set

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied or the knots were not in increasing order

int AlCurve::numberOfCVsInclMultiples() const

Description

Returns the number of CVs, including multiples. For more information on what this value means, see the AlCurve class documentation. -1 is returned if the curve is not valid.

statusCode AlCurve::CVsWorldPositionInclMultiples( double CVList[][4] ) const

Description

Returns the world positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples().

Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

Arguments

> CVList - the world positions of all CVs

Return Codes

sSuccess - the CVs positions were returned

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied

sFailure - an error occurred

statusCode AlCurve::CVsAffectedPositionInclMultiples( const AlTM& tm, double CVList[][4] ) const

Description

Returns the world positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples().

Note that the positions returned are [ x y z w ] and not [ w*x w*y w*z w ].

Arguments

< tm - the transformation matrix built by traversing the DAG

> CVList - returned world positions of all CVs

Return Codes

sSuccess - the CVs positions were returned

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::CVsUnaffectedPositionInclMultiples( double CVList[][4] ) const

Description

Returns the unaffected positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples().

Arguments

> CVList - returned unaffected positions of all CVs

Return Codes

sSuccess - the CVs positions were returned

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied

sFailure - an error occurred

statusCode AlCurve::setCVsUnaffectedPositionInclMultiples( const double CVList[][4] )

Description

Sets the unaffected positions of all CVs in this curve, including multiples. The first dimension of the given CVList must be of length numberOfCVsInclMultiples(). You cannot give multiples different values. For example, if you have an open curve where numOfCVs() is 6 and numOfCVsInclMultiples() is 7 because the 2nd point has a multiplicity of 2, then the 2nd and 3rd quadruple in your CVList should be the same. What really happens is that the 3rd point is given the same value as the 2nd point. (What you give as the 3rd point is ignored). For more information see the examples in the class description.

Arguments

< CVList - the unaffected positions of all CVs

Return Codes

sSuccess - the CVs positions were set

sInvalidObject - the curve was not valid

sInvalidArgument - a NULL argument was supplied

sFailure - an error occurred

boolean AlCurve::isDisplayModeSet( AlDisplayModeType mode ) const

Description

Returns TRUE if the specified display mode is toggled on for the curve. Returns FALSE otherwise.

The only valid AlDisplayModeTypes for an AlCurve are:

kDisplayGeomHull

kDisplayGeomEditPoints

kDisplayGeomKeyPoints

kDisplayGeomCVs

Arguments

< mode - display mode of interest

Return Values

FALSE is returned if the curve is not Valid.

statusCode AlCurve::setDisplayMode( AlDisplayModeType mode, boolean on_or_off)

Description

For the given display mode, if the flag on_or_off is TRUE then the display mode for the surface is set, otherwise it is unset.

The only valid AlDisplayModeTypes for an AlCurve are:

kDisplayGeomHull

kDisplayGeomEditPoints

kDisplayGeomKeyPoints

kDisplayGeomCVs

Arguments

< mode - display mode of interest

< on_or_off - boolean deciding if this surface will have the display mode set

Return Codes

sSuccess - operation was successful

sInvalidObject - the curve was invalid sInvalidArgument - invalid display type

statusCode AlCurve::create( int deg, curveFormType form, int numKnots, const double knotVector[], int numControlPts, const double controlPoint[][4], const int multiplicity[])

Description

Creates the geometric data that represents this curve.

Briefly, Alias curves are represented by an array of knots and an array of control points. (For a detailed understanding of NURBs curves, see the book "An Introduction to Splines for use in Computer Graphics and Geometric Modeling" by Bartels, Beatty and Barsky, also known as "The Killer B’s".)

The number of spans in a curve is determined by the degree of the curve and the number of control points: namely, there are ’numControlPts - deg’ spans. Knot values are associated with the ends of each span. Therefore, ’numKnots’ must be equal to ’number of spans + 1’.

The expert will notice that ’numKnots’ = ’number of spans + 1’ does not give us enough knots to specify all the basis functions properly. (The correct number of knots required, according to the Killer B’s are numSpans + 2*degree + 1). However since Alias piles knots up at the extreme ends of an open nurbs curve (in order to force the curve to touch each end control point) this method does not require that the user specify the redundant knot values. For example, if the knot vector for a three span open curve contained the knot values [0 1 2 3], the real knot vector would be [0 0 0 0 1 2 3 3 3 3]. In the case of a periodic curve the values of the knots can be determined implicitly from the knots values provided and again don’t need to be provided explicitly. For example, if the knot vector for a four span periodic curve contained the knot values [-1 1 2 5 10], the real knot vector would be [-10 -9 -6 -1 1 2 5 10 12 13 16].

If this object was previously referencing some other curve, and this call succeeds, this object will reference the new curve.

For more information on multiplicity, see the AlCurve description.

When you create a curve, you must ensure the following:

Open and closed curves must have at least one span.
Periodic curves require that there be at least 3 spans.
’numKnots’ must be equal to ’number of spans + 1’
The knot values must be a non-decreasing sequence of values.
The first and last span must not be vacuous. That is knotVector[0] < knotVector[1] and knotVector[numKnots-2] < knotVector[numKnots-1]
Any knot multiplicity must not exceed the degree of the curve.
Periodic curves also require that the number of spans be greater than or equal to the degree of the curve.
For open/closed curves the number of control points is the number of spans + degree. For example, one span requires four control points.
For periodic curves the number of control points is the same as the number of spans. It isn’t necessary to specify any of the overlapping control points.
All multiplicity values must be 1, 2 or 3. The first and last multiplicity values must be 1.

Arguments

< deg - the degree of the curve

< form - kOpen, kClosed or kPeriodic

< numKnots - the number of knots in the knotVector

< knotVector - the sequence of knot values. Must be of length numKnots.

< numControlPts - the number of points in controlPoint

< controlPoint - the array of control points. Must have size of numControlPts * 4.

< multiplicity - the multiplicity values. Must be of length numControlPts. Assumed to be an array of 1’s if NULL.

Return code

sSuccess - data created

sInsufficientMemory - ran out of memory

sInvalidArgument - there are many ways to fail with this return code

Calling this method from AlFace (which derives from AlCurve) with a form of kOpen
NULL knot or control point arrays
Number of spans <= 0 { for a periodic curve, number of spans = number of control points, for open or closed curves, the number of spans = number of control points - degree
Number of knots not equal to the number of spans + 1
Knot vector is not a non-decreasing sequence of values
Knots that delimit the first and last spans are non -zero, ie. (knotVector[1] - knotVector[0]) and knotVector[numKnots-1] - knotVector[numKnots-2] are not both zero
For a closed curve, the first and last control points are not the same
For a periodic curve, the number of spans is less than 3 { leads to geometrically degenerate curves }
For a periodic curve, the degree is greater than the number of spans { leads to multiple wrapping of control points }

sFailure - data could not be created

statusCode AlCurve::create( int deg, curveFormType form, const double knotVector[], int numControlPts, const double controlPoint[][4] )

Description

Creates the geometric data that represents this curve according to the standard Killer B’s representation.

Note this method’s differences from the other create method. This method assumes that the size of the number of knots passed in the knot vector is always numControlPts + deg + 1 (or numSpans + 2*deg + 1, if you prefer, where numSpans = numControlPts - deg). That is, the redundant end knots must be specified.

This method assumes that if this object was previously referencing some other curve, and this call succeeds, this object will reference the new curve.

For more information on multiplicity, see the AlCurve description.

When you create a curve, you must ensure the following:

Open and closed curves must have at least one span.
Periodic curves require that there be at least 3 spans.
The number of knot values must be equal to ’numControlPts + deg + 1’
The knot values must be a non-decreasing sequence of values.
Any knot multiplicity must not exceed the degree of the curve.
Periodic curves also require that the number of spans be greater than or equal to the degree of the curve.
For open/closed/periodic curves the number of control points is the number of spans + degree. For example, one span requires four control points.
For periodic curves it is necessary to specify the overlapping control points.

Arguments

< deg - the degree of the curve

< form - kOpen, kClosed or kPeriodic

< knotVector - the sequence of knot values. Must be of length numControlPts + deg + 1.

< numControlPts - the number of points in controlPoint

< controlPoint - the array of control points. Must have size of numControlPts * 4.

Return Codes

sSuccess - data created

sInsufficientMemory - ran out of memory

sInvalidArgument - there are many ways we can fail with this return code

Calling this method from AlFace (which derives from AlCurve) with a form of kOpen
NULL knot vector or control point array
Number of spans <= 0 { number of spans = number of control points - degree }
The knot vector is not a non-decreasing sequence of values
For open and closed curves, the knot values bounding the first and last span are different
For periodic curves, the last degree knots are not specified correctly. If the knots are specified correctly, the following will be true:

	For i = 0 to 2*deg-1 (n = numberSpans)
	 T[i+1] -  T[i] = T[i+n+1] - T[i+n]

For a closed curve, the first CV is not the same as the last
For a periodic curve, the number of spans is less than 3
For a periodic curve, the degree is greater than the number of spans
For a periodic curve, the first CV is not the same as the last CV

sFailure - data could not be created

Note: The number of knots = number of control points + degree + 1. The size of the knot vector is not passed into this method so if you don’t specify the array correctly, the method can read past the end of the knot vector.

statusCode AlCurve::createLine( const double start[3], const double end[3] )

Description

Creates a straight line using attributes. This method is simpler than the previous create method, requiring you only to specify the beginning and end of the curve. To modify the curve you should retrieve its attributes with the firstAttribute() method and use AlAttribute methods to modify it. Modifying the CVs directly will cause the attributes to be deleted.

Arguments

< start - the coordinates for the start of the curve

< end - the coordinates for the end of the curve

Return Codes

sSuccess - curve created

sFailure - failed to create the curve

sInvalidArgument - start or end was NULL

sInsufficientMemory - Ran out of memory

statusCode AlCurve::createArc( const double start[3], const double end[3], const double other[3], boolean circle )

Description

Creates a circular arc using attributes. This method is simpler than the previous create method, requiring you only to specify three points on the curve and whether the curve should be closed to form a circle. To modify the curve you should retrieve its attributes with the firstAttribute() method and use AlAttribute methods to modify it. Modifying the CVs directly will cause the attributes to be deleted.

Arguments

< start - the coordinates for the start of the curve

< end - the coordinates for the end of the curve

< other - an additional point defining the arc

< circle - if TRUE then a circle will be generated

Return Codes

sSuccess - curve created

sFailure - failed to create the curve

sInsufficientMemory - ran out of memory

sAlreadyCreated - the AlCurve has already been created

sInvalidArgument - a NULL argument was supplied

statusCode AlCurve::createArc( double *C, double *N, double *P, double r, double a0, double a1, int dim, boolean make_cubic )

Description

Create a circular arc between two angles.

Arguments

C center

N normal to plane of arc (if 3D)

P point with zero angle

r radius

a0, a1 initial and final angles (in radians)

dim dimension 2 or 3

make_cubic if true, raise degree to 3

Note:

If dim = 2, N is ignored.

Point P with zero angle must not be at C.

Returns NULL if arc has no length

3D:

a0 < a1 and a1-a0 <= 2*PI.

Returns a full circle if a1-a0 > 2*PI.

To build a arc in the other direction, reverse N.

2D:

|a1-a0| <= 2*PI.

If a0 < a1 arc is counter clockwise else arc is clockwise.

Returns a full circle if |a1-a0| > 2*PI.

Return Codes

sInvalidArgument - a bad argument was supplied

sFailure - Failed to create the curve.

sSuccess - All ok.

statusCode AlCurve::createConic( double c_a, double c_b, double c_c, double c_d, double c_e, double c_f, const double start[3], const double end[3] )

Description

Creates a conic arc using attributes. This method is simpler than the previous create method, requiring users only to specify the coefficients of the conic and the beginning and end of the curve. The start and end points must lie on the conic.

The conic is described by the equation:

A * X^2 + B * X * Y + C * Y^2 + D * X + E * Y + F = 0

The conic will be created in the XY plane.

It is not possible to modify a conic curve through its attributes.

Arguments

< c_a through c_f - coefficient of the conic

< start - the coordinates for the start of the curve

< end - the coordinates for the end of the curve

Return Codes

sSuccess - curve created

sFailure - failed to create the curve

sInsufficientMemory - ran out of memory

sInvalidArgument - a NULL argument was supplied

sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createParabola( const double vertex[3], const double focus[3], const double start[3], const double end[3] )

Description

Creates a parabolic arc using attributes. This method is simpler than the previous create method, requiring users only to specify the vertex and focus of the parabola and the beginning and end of the curve. The start and end points must lie on the parabola. The parabola will be created in the XY plane. It is not possible to modify a parabolic curve through its attributes.

Arguments

< vertex - the vertex of the parabola

< focus - the focus of the parabola

< start - the coordinates for the start of the curve

< end - the coordinates for the end of the curve

Return Codes

sSuccess - curve created

sFailure - failed to create the curve

sInsufficientMemory - ran out of memory

sInvalidArgument - a NULL argument was supplied

sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createEllipse( const double center[3], const double major_axis[3], const double minor_axis[3], const double start[3], const double end[3] )

Description

Creates an elliptical arc using attributes. This method is simpler than the previous create method, requiring users only to specify the center, major axis, and minor axis of the ellipse and the beginning and end of the curve. The start and end points must lie on the ellipse and be specified in a counterclockwise order to indicate the arc. The axes must be perpendicular to each other. When creating an elliptical arc, the axes MUST be specified in the XY plane. It is not possible to modify an elliptical curve through its attributes. It is not possible to create a closed curve with this method, hence it will always fail for AlFaces.

Arguments

< center - the center of the ellipse

< major_axis - the direction of the major axis

< minor_axis - the direction of the minor axis

< start - the coordinates for the start of the curve

< end - the coordinates for the end of the curve

Return Codes

sSuccess - curve created

sFailure - failed to create the curve

sInsufficientMemory - ran out of memory

sInvalidArgument - a NULL argument was supplied

sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createHyperbola( const double center[3], const double major_axis[3], const double minor_axis[3], const double start[3], const double end[3] )

Description

Creates a hyperbolic arc using attributes. This method is simpler than the previous create method, requiring users only to specify the center, major axis, and minor axis of the hyperbola and the beginning and end of the curve. The start and end points must lie on the ellipse and be specified in a counterclockwise order to indicate the arc. The axes must be perpendicular to each other. The hyperbola will be created in the XY plane. It is not possible to modify a hyperbolic curve through its attributes.

Arguments

< center - the center of the hyperbola

< major_axis - the focus of the hyperbola

< minor_axis - the focus of the hyperbola

< start - the coordinates for the start of the curve

< end - the coordinates for the end of the curve

Return Codes

sSuccess - curve created

sFailure - failed to create the curve

sInsufficientMemory - ran out of memory

sInvalidArgument - a NULL argument was supplied

sAlreadyCreated - the AlCurve has already been created

statusCode AlCurve::createPoint( const double pt[3] )

Description

Create a "degenerate curve" with a single CV. The coordinates for this CV are provided by the argument pt[].

The created "curve" will be:

rational
open
degree 1
span 0
dimension 3
knots {0.0}
cv {pt[0], pt[1], pt[2], 1.0}

Arguments

< pt - position of the point

Return Codes

sSuccess - the method succeeded

sFailure - Failed to create the point.

sInvalidArgument - a NULL argument was supplied.

sAlreadyCreated - the AlCurve has already been created

int AlCurve::realNumberOfKnots() const

Description

Returns the actual number of knots on the curve. That is uNumberOfSpans() + 2*degree() - 1. (Note that two additional knots are required to define a NURBS curve, but they have no effect on the curve so are not included in this count.) This method returns -1 if the curve is not valid.

statusCode AlCurve::realKnotVector( double knotVector[] ) const

Description

Returns realNumberOfKnots() in ’knotVector’ for the curve.

Arguments

> knotVector - array to place the knot vector into

Return Codes

sSuccess - successfully copied the curve’s knot vector into knotVector

sInvalidArgument - knotVector was NULL

sInvalidObject - the curve was invalid

sFailure - an error occurred

statusCode AlCurve::setRealKnotVector( const double knotVector[] )

Description

Sets the knots for this curve. The parameter ’knotVector’ must be of ’realNumberofKnots()’.

Arguments

< knotVector - array of knots

Return Codes

sSuccess - the knots were successfully set

sInvalidArgument - knotVector was NULL

sInvalidObject - the curve is invalid

sFailure - an error occurred

statusCode AlCurve::length(double& len , boolean worldCoordinates, double tolerance )

Description

Determines the length of the curve in either local coordinates or world space coordinates.

Arguments

> len - the returned length

> worldCoordinates - the calculation is to be done in world space

> tolerance - the error tolerance

Return Codes

sSuccess - the length was successfully determined

sFailure - the evaluation failed

sInvalidObject - the curve was invalid

sInvalidArgument - tolerance was zero or negative

statusCode AlCurve::periodicToNonPeriodic( ) const

Description

If a curve is periodic, converts it to a non-periodic curve (closed curve) by giving it multiple end knots.

Note: This method modifies the curve. It will not succeed for an AlCurve that exists in the AlUniverse; that is, it must not have a parent AlCurveNode.

Return Codes

sInvalidObject - the curve was invalid

sFailure - the method did not succeed

sSuccess - the curve was converted to a non-periodic one

statusCode AlCurve::normal( double normal[3] ) const

Description

Tests if bspline is planar and returns normal. This method finds the first three points that are not co-linear, constructs a normal and tests if the bspline lies in the plane. If the bspline is planar and closed the normal is returned with a clockwise orientation looking down on the plane, and the normal pointing towards you. If the bspline is a line or all the points are co-linear, a unique normal can not be defined.

Arguments

> normal - returned normal vector to the bspline

Return Codes

sSuccess - the normal to the curve was found

sFailure - the normal could not be found: the spline is either a point, linear or not planar

statusCode AlCurve::insert( double param )

Description

Inserts an edit point into the curve.

Arguments

< param - parametric value of the new edit point on the curve

Return Codes

sSuccess - the edit point was successfully inserted

sInvalidObject - the given object is not valid

sInvalidArgument - a parameter is out of bounds

sFailure - an error occurred

statusCode AlCurve::append( double pos[4], AlPointType type )

Description

Appends a CV or an edit point to the curve.

Arguments

< pos - position in world space of the new point

< type - either kCV or kEditPoint

Return Codes

sSuccess - new point was successfully appended

sInvalidObject - the given object is not valid

sInvalidArgument - an invalid argument was supplied

sFailure - an error occurred

statusCode AlCurve::applyIteratorToCVs( AlIterator* iter, int &rc )

Description

Applies the given iterator to all the CVs in this class. See the documentation for AlIterator.

Arguments

< iter - the iterator to apply to each CV

> rc - the result of the last application of the iterator

Return Codes

sSuccess - the iterator exited normally

sFailure - the iterator exited abnormally

sInvalidArgument - the iterator ’iter’ was NULL

sInvalidObject - the curve was not valid

statusCode AlCurve::reverseCurve()

Description

Reverses the parameterization of the curve.

Return Codes

sInvalidObject - the curve was not a valid object

sSuccess - the curve reversal worked

sFailure - the curve reversal failed for internal reasons

statusCode AlCurve::extendCurve(double knot , double newPos[4])

Description

Extends the curve by one span. The existing spans remain unchanged. The new span has C(k-1) and interpolates the given point. This curve must have at least 1 span and at least 4 CVs.

Arguments

< knot - the knot spacing for the new span

< newPos - the position of the new CV

Return Codes

sInvalidObject - the curve was an invalid object

sSuccess - extending the spline worked

sFailure - the curve had less than 1 span, curve had less than 4 CVs, or could not extend the spline because of an internal error

statusCode AlCurve::incrementDegree()

Description

Increments the degree of a curve without changing its shape. The curve must have at least 1 span.

Return Codes

sInvalidObject - the curve is not a valid object

sSuccess - raising the degree of the curve worked

sFailure - the number of spans was less than 1, or there was an internal failure

statusCode AlCurve::adjustEndSpan( double newKnotSpan )

Description

Changes the knot spacing of the last span of the curve, leaving the remainder of the curve unchanged. The end point of the last span is preserved.

Arguments

< double newKnotSpan - the knot spacing for the end span

Return Codes

sInvalidObject - the curve is an invalid object

sSuccess - the method worked

sFailure - the curve did not have at least one span. The method failed to adjust the end span.

statusCode AlCurve::trimCurve( double param0, double param1 )

Description

Trims the curve at the specified parameters. param0 and param1 are the min and max points. This routine fails if param0 and param1 are the same or if param0 is greater than param1.

Arguments

< param0 - the minimum position along the curve where the curve is to be trimmed

< param1 - the maximum position along the curve where the curve is to be trimmed

Return Codes

sInvalidObject - the curve was not a valid object

sSuccess - the method worked

sFailure - the routine failed. Either param0 equals param1, param0 > param1, or there was an internal failure.