Detailed Description

NURBS surface function set.

This is the function set for NURBS (Non-Uniform Rational B-spline) surfaces.

The shape of a NURBS surface is defined by an array of CVs (control vertices), an array of knot values in the U direction and an array of knot values in the V direction, a degree in U and in V, and a form in U and in V.

The U and V knot vectors for NURBS surfaces are of size (spansInU + 2*degreeInU -1) and (spansInV + 2*degreeInV -1). Note: spans = numCVs - degree.

There are 3 possible "forms" for the surface in the U and V directions: open, closed and periodic. These forms are described below. Note that the descriptions below apply to both the U and V directions.

The open and closed forms are quite similar, and in fact a closed surface will become and open surface if either the first or last CV is moved so that they are no longer coincident. To create an open or closed surface, of degree N, with M spans, you must provide M+N CVs. This implies that for a degree N surface, you must specify at least N+1 CVs to get a surface with a single span.

The number of knots required for the surface is M + 2N - 1. If you want the surface to start exactly at the first CV and end exactly at the last CV, then the knot vector must be structured to have degree N "multiplicity" at the beginning and end. This means that the first N knots must be identical, and the last N knots must be identical.

A periodic surface is a special case of a closed surface. Instead of having just the first and last CVs coincident, the last N CVs in the surface, where N is equal to the degree, overlap the first N CVs. This results in a surface with no tangent break where the ends meet. The last N CVs in a periodic surface are permanently bound to the first N CVs, and Maya will not allow those last N CVs to be repositioned. If one or more of the first N CVs of the surface are repositioned, the overlapping CV's will remain bound, and will also be moved.

In order to create a periodic surface, you must specify at least 2N+1 CVs, so that that last N can overlap the first N and you still have 1 non-overlapping CV left. The number of CVs required to create a periodic surface is still N+M (with a lower limit of 2N+1), but you must ensure that the positions of the last N CVs are identical to the positions of the first N.

You still need M + 2N - 1 knots for a periodic surface, but the knot values required are more restrictive than for open or closed surfaces because of the overlap of the last N CVs. The first N knots should be specified at the beginning of the knot array as values { -(N-1), -(N-2), ... 0 } in order to implement the overlap. Additionally there can be no knot multiplicity at the end of the surface, because that would compromise the tangent continuity property.

Managing different knot representations in external applications

Note that some third party applications use a different format for knots, where the number of knots required for a surface is M+2N+1 rather than M+2N-1 as used in Maya. Both knot representations are equivalent mathematically. To convert from one of these external representations into the Maya representation, simply omit the first and last knots from the external representation when creating the Maya representation. To convert from the Maya representation into the external representation, add two new knots at the beginning and end of the Maya knot sequence. The value of these new knots depends on the existing knot sequence. For a knot sequence with multiple end knots, simply duplicate the existing first and last knots once more, for example:

Maya representation: {0,0,0,...,N,N,N} External representation: {0,0,0,0,...,N,N,N,N}

For a knot sequence with uniform end knots, create the new knots offset at an interval equal to the existing first and last knot intervals, for example:

Maya representation: {0,1,2,...,N,N+1,N+2} External representation: {-1,0,1,2,...,N,N+1,N+2,N+3}

Examples:: closestPointOnNurbsSurfaceCmd.cpp, cvColorNode.cpp, fullLoftNode.cpp, intersectOnNurbsSurfaceCmd.cpp, scanDagCmd.cpp, scanDagSyntax.cpp, simpleLoftNode.cpp, surfaceBumpManip.cpp, surfaceCreate.cpp, and surfaceCreateCmd.cpp.

#include <MFnNurbsSurface.h>

Inheritance diagram for MFnNurbsSurface:

[legend]

List of all members.

Public Types
enum	Form { kInvalid = 0, kOpen, kClosed, kPeriodic, kLast }
	Forms that a surface may take in a given parametric direction. More...
enum	BoundaryType { kInvalidBoundary = 0, kOuter, kInner, kSegment, kClosedSegment }
	Boundary types for trimmed surfaces. More...
Public Member Functions
virtual MFn::Type	type () const
	Function set type.
virtual	~MFnNurbsSurface ()
	Destructor.
	MFnNurbsSurface ()
	Default constructor.
	MFnNurbsSurface (MObject &object, MStatus *ReturnStatus=NULL)
	Constructor.
	MFnNurbsSurface (const MDagPath &object, MStatus *ret=NULL)
	Constructor.
MObject	create (const MPointArray &controlVertices, const MDoubleArray &uKnotSequences, const MDoubleArray &vKnotSequences, unsigned int degreeInU, unsigned int degreeInV, Form formU, Form formV, bool createRational, MObject parentOrOwner=MObject::kNullObj, MStatus *ReturnStatus=NULL)
	Creates a nurbs surface from the specified data and sets this function set to operate on the new surface.
MObject	copy (const MObject &source, MObject parentOrOwner=MObject::kNullObj, MStatus *ReturnStatus=NULL)
	This method creates a copy of a nurbs surface.
MObject	cv (unsigned int indexU, unsigned int indexV, MStatus *ReturnStatus=NULL)
	Returns a component for the specified CV.
MObject	cvsInU (unsigned int startIndex, unsigned int endIndex, unsigned int rowIndex, MStatus *ReturnStatus=NULL)
	Returns a component for the specified CVs.
MObject	cvsInV (unsigned int startIndex, unsigned int endIndex, unsigned int rowIndex, MStatus *ReturnStatus=NULL)
	Returns a component for the specified CVs on the given V direction.
MStatus	getCVs (MPointArray &array, MSpace::Space space=MSpace::kObject) const
	Get the positions of the CVs on this surface.
MStatus	setCVs (const MPointArray &array, MSpace::Space space=MSpace::kObject)
	Set the CVs for this surface to the given points.
MStatus	getCV (unsigned int indexU, unsigned int indexV, MPoint &pnt, MSpace::Space space=MSpace::kObject) const
	Get the location of the specified CV.
MStatus	setCV (unsigned int indexU, unsigned int indexV, MPoint &pnt, MSpace::Space space=MSpace::kObject) const
	Set the location of the specified CV.
Form	formInU (MStatus *ReturnStatus=NULL) const
	Return the form of this surface in U.
Form	formInV (MStatus *ReturnStatus=NULL) const
	Return the form of this surface in V.
bool	isBezier (MStatus *ReturnStatus=NULL) const
	Determine if the knot spacing gives us Bezier surface.
bool	isUniform (MStatus *ReturnStatus=NULL) const
	Determine if the knot spacing is uniform.
bool	isKnotU (double param, MStatus *ReturnStatus=NULL) const
	Check if the specified parameter value is a knot value.
bool	isKnotV (double param, MStatus *ReturnStatus=NULL) const
	Check if the specified parameter value is a knot value.
bool	isParamOnSurface (double paramU, double paramV, MStatus *ReturnStatus=NULL) const
	Check if the specified parameter is on this surface.
MStatus	getKnotDomain (double &startU, double &endU, double &startV, double &endV) const
	Returns the maximum and minimum U and V paramter values for this surface.
int	degreeU (MStatus *ReturnStatus=NULL) const
	Returns the degree of the surface in U (1 - 3).
int	degreeV (MStatus *ReturnStatus=NULL) const
	Returns the degree of the surface in V (1 - 3).
int	numSpansInU (MStatus *ReturnStatus=NULL) const
	Returns the number of spans in the u direction.
int	numSpansInV (MStatus *ReturnStatus=NULL) const
	Returns the number of spans in the v direction.
int	numNonZeroSpansInU (MStatus *ReturnStatus=NULL) const
	Returns the number of non-zero spans in the U direction.
int	numNonZeroSpansInV (MStatus *ReturnStatus=NULL) const
	Returns the number of non-zero spans in the V direction.
int	numCVsInU (MStatus *ReturnStatus=NULL) const
	Returns the number of CVs in the U direction (degree + spans).
int	numCVsInV (MStatus *ReturnStatus=NULL) const
	Returns the number of CVs in the V direction (degree + spans).
int	numKnotsInU (MStatus *ReturnStatus=NULL) const
	Returns the number of knots in U including multiple end knots (spans + 2 * degree - 1).
int	numKnotsInV (MStatus *ReturnStatus=NULL) const
	Returns the number of knots in V including multiple end knots (spans + 2 * degree - 1).
MStatus	getKnotsInU (MDoubleArray &array) const
	Get the knots along the U direction for this surface.
MStatus	getKnotsInV (MDoubleArray &array) const
	Get the knots along the V direction for this surface.
MStatus	setKnotsInU (const MDoubleArray &array, unsigned int startIndex, unsigned int endIndex)
	Set the specified U knot values for this surface.
MStatus	setKnotsInV (const MDoubleArray &array, unsigned int startIndex, unsigned int endIndex)
	Set the specified V knot values for this surface.
double	knotInU (unsigned int index, MStatus *ReturnStatus=NULL) const
	Retrieve the given knot value from this surface at the specified U index.
double	knotInV (unsigned int index, MStatus *ReturnStatus=NULL) const
	Retrieve the given knot value from this surface at the specified V index.
MStatus	setKnotInU (unsigned int index, double param)
	Set the value of the given existing knot at the specified U index.
MStatus	setKnotInV (unsigned int index, double param)
	Set the value of the given existing knot at the specified V index.
MStatus	removeKnotInU (double atThisParam, bool removeAll=false)
	Remove the U knot(s) at the specified parameter value from this surface.
MStatus	removeKnotInV (double atThisParam, bool removeAll=false)
	Remove the V knot(s) at the specified parameter value from this surface.
MStatus	removeOneKnotInU (double atThisParam)
	Remove one U knot at the specified parameter value from this surface.
MStatus	removeOneKnotInV (double atThisParam)
	Remove one V knot at the specified parameter value from this surface.
MVector	normal (double paramInU, double paramInV, MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
	Retrieve the normal at the given parameter value on the surface.
MStatus	getTangents (double paramInU, double paramInV, MVector &vectorInU, MVector &vectorInV, MSpace::Space space=MSpace::kObject) const
	Retrieve the tangents in the U and V directions at the given parameter value on the surface.
MStatus	getDerivativesAtParm (double paramInU, double paramInV, MPoint &pos, MVector &dU, MVector &dV, MSpace::Space space, MVector dUU=NULL, MVector dVV=NULL, MVector *dUV=NULL) const
	Evaluate the surface at the given (u,v) coordinate returning position, first derivatives and optionally second derivative information.
bool	isFoldedOnBispan () const
	Evaluate the surface to determine if it contains any folds or creases.
double	area (double tolerance=kMFnNurbsEpsilon, MStatus *ReturnStatus=NULL) const
	Calculates the surface area of this nurbs surface.
double	area (MSpace::Space space, double tolerance=kMFnNurbsEpsilon, MStatus *ReturnStatus=NULL) const
	Calculates the surface area of this nurbs surface in world or local space.
MPoint	closestPoint (const MPoint &toThisPoint, double paramU=NULL, double paramV=NULL, bool ignoreTrimBoundaries=false, double tolerance=kMFnNurbsEpsilon, MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
	Return the closest point on this surface to the given point.
MPoint	closestPoint (const MPoint &toThisPoint, bool paramAsStart, double paramU, double paramV, bool ignoreTrimBoundaries=false, double tolerance=kMFnNurbsEpsilon, MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
	Return the closest point on this surface to the given point.
bool	isPointOnSurface (const MPoint &point, double tolerance=kMFnNurbsEpsilon, MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
	Check if the given point is on this surface.
MStatus	getParamAtPoint (const MPoint &atThisPoint, double &paramU, double &paramV, MSpace::Space space=MSpace::kObject) const
	This method is obsolete.
MStatus	getParamAtPoint (const MPoint &atThisPoint, double &paramU, double &paramV, bool ignoreTrimBoundaries, MSpace::Space space=MSpace::kObject, double tolerance=kMFnNurbsEpsilon) const
	Get the parameter value corresponding to the given point on the surface (or underlying surface).
MStatus	getPointAtParam (double paramU, double paramV, MPoint &point, MSpace::Space space=MSpace::kObject) const
	Finds the point corresponding to the given parameter value on the surface.
double	distanceToPoint (const MPoint &pt, MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
	Returns the distance from the given point to the closest point on the surface.
MObject	tesselate (MTesselationParams &parms=MTesselationParams::fsDefaultTesselationParams, MObject parentOrOwner=MObject::kNullObj, MStatus *ReturnStatus=NULL)
	Performs tesselation on this surface and create a new mesh in the DAG.
bool	intersect (const MPoint &rayStartingPoint, const MVector &alongThisDirection, double &u, double &v, MPoint &intersectionData, double tolerance=kMFnNurbsEpsilon, MSpace::Space space=MSpace::kObject, bool calculateDistance=false, double distance=NULL, bool calculateExactHit=false, bool wasExactHit=NULL, MStatus *ReturnStatus=NULL) const
	This function determines the closest point of intersection of this spline surface with a ray (a vector at a point).
bool	intersect (const MPoint &rayStartingPoint, const MVector &alongThisDirection, MDoubleArray &u, MDoubleArray &v, MPointArray &intersectionData, double tolerance=kMFnNurbsEpsilon, MSpace::Space space=MSpace::kObject, bool calculateDistance=false, MDoubleArray distances=NULL, bool calculateExactHit=false, bool wasExactHit=NULL, MStatus *ReturnStatus=NULL) const
	This function determines all the points of intersection of this spline surface with a ray (a vector at a point).
bool	hasHistoryOnCreate (MStatus *ReturnStatus=NULL)
	This method determines if the shape was created with history.
MStatus	updateSurface ()
	This method signals that this surface has changed and needs to be recalculated.
bool	isTrimmedSurface (MStatus *ReturnStatus=NULL)
	This method determines if this surface is a trimmed surface.
unsigned int	numRegions (MStatus *ReturnStatus=NULL)
	Returns the number of trimmed regions for this surface or 0 if the surface is not a trimmed surface.
bool	isFlipNorm (unsigned int region, MStatus *ReturnStatus=NULL)
	Determines whether the normal for the specified region is flipped.
unsigned int	numBoundaries (unsigned int region, MStatus *ReturnStatus=NULL)
	Returns the number of boudaries for the specified region.
BoundaryType	boundaryType (unsigned int region, unsigned int boundary, MStatus *ReturnStatus=NULL)
	Returns the type of the specified boundary.
unsigned int	numEdges (unsigned int region, unsigned int boundary, MStatus *ReturnStatus=NULL)
	Return the number of edges for the specified trim boundary.
MObjectArray	edge (unsigned int region, unsigned int boundary, unsigned int edge, bool paramEdge=false, MStatus *ReturnStatus=NULL)
	Return the specified edge of a trim boundary.
bool	isPointInTrimmedRegion (double u, double v, MStatus *ReturnStatus=NULL)
	Returns true if the given point is in a trimmed away region of a trimmed surface.
MStatus	getTrimBoundaries (MTrimBoundaryArray &result, unsigned int region, bool paramEdge=true)
	Returns all trim boundaries of a region on this surface.
MStatus	trimWithBoundaries (const MTrimBoundaryArray &mBoundaries, bool flipNormal=false, double e_tol=1e-3, double pe_tol=1e-5)
	This function trims this surface with given trim boundaries.
MStatus	projectCurve (MDagPath &curve, MVector *direction=NULL, bool constructionHistory=false)
	Project the given curve onto this surface creating a curve on surface.
MStatus	trim (MDoubleArray &locatorU, MDoubleArray &locatorV, bool constructionHistory=false)
	Trim this surface to its curves on surface.
unsigned int	numPatches (MStatus *ReturnStatus=NULL) const
	Returns the number of non-zero patches in this surface.
unsigned int	numPatchesInU (MStatus *ReturnStatus=NULL) const
	Returns the number of non-zero patches along u, in this surface.
unsigned int	numPatchesInV (MStatus *ReturnStatus=NULL) const
	Returns the number of non-zero patches along v, in this surface.
int	numUVs (MStatus *ReturnStatus=NULL) const
	Returns the number of texture (uv) coordinates for this surface.
MStatus	setUVs (const MFloatArray &uArray, const MFloatArray &vArray)
	Sets all of the texture coordinates (uvs) for this surface.
MStatus	getUVs (MFloatArray &uArray, MFloatArray &vArray) const
	This method copies the texture coordinate list for this surface into the given uv arrays.
MStatus	setUV (int uvId, float u, float v)
	Sets the specified texture coordinate.
MStatus	getUV (int uvId, float &u, float &v) const
	Get the value of the specified texture coordinate from this surface's uv list.
MStatus	getPatchUV (int patchId, int cornerIndex, float &u, float &v) const
	Get the value of the specified texture coordinate for a patch corner in a patch.
MStatus	getPatchUVs (int patchId, MFloatArray &uArray, MFloatArray &vArray) const
	Get the values of the texture coordinate on a specified patch.
MStatus	getPatchUVid (int patchId, int cornerIndex, int &uvId) const
	Get the id of the specified texture coordinate for a corner in a patch.
MStatus	assignUV (int patchId, int cornerIndex, int uvId)
	Maps a texture coordinate to a the specified corner of a patch.
MStatus	assignUVs (const MIntArray &uvCounts, const MIntArray &uvIds)
	This method maps all texture coordinates for the surface.
MStatus	clearUVs ()
	This method clears out all texture coordinates for the nurbsSurface, and leaves behind an empty UVset.
MStatus	getAssignedUVs (MIntArray &uvCounts, MIntArray &uvIds) const
	Get assigned UVs.
MObject	tesselate (MTesselationParams &parms, MStatus *ReturnStatus)
	This method is obsolete.
MObject	getDataObject () const
	Returns an MObject if the class has been constructed with an MFn::kNurbsSurfaceData entity, otherwise MObject::kNullObj is returned.
	MFnNurbsSurface (const MObject &object, MStatus *ret=NULL)
	Constructor.
Protected Member Functions
virtual const char *	className () const
	Class name.

Member Enumeration Documentation

enum Form

kInvalid	Search for all occurrences
kOpen	Edges are independent. Search for all occurrences
kClosed	Edges are coincident. Search for all occurrences
kPeriodic	Edges overlap such that there is no break in tangency. Search for all occurrences
kLast	Search for all occurrences

kInvalidBoundary	Search for all occurrences
kOuter	Outer boundary, counter clockwise. Search for all occurrences
kInner	Inner boundary, clockwise. Search for all occurrences
kSegment	Curve on a face. Search for all occurrences
kClosedSegment	Closed curve on a face. Search for all occurrences

MFnNurbsSurface	(	MObject &	object,
		MStatus *	ReturnStatus = `NULL`
	)

[in]	object	The MObject to attach the function set to
[out]	ReturnStatus	the return status

MFnNurbsSurface	(	const MDagPath &	object,
		MStatus *	ReturnStatus = `NULL`
	)

[in]	object	The const MDagPath to attach the function set to
[out]	ReturnStatus	The return status

MFnNurbsSurface	(	const MObject &	object,
		MStatus *	ReturnStatus = `NULL`
	)

MObject create	(	const MPointArray &	controlVertices,
		const MDoubleArray &	uKnotSequences,
		const MDoubleArray &	vKnotSequences,
		unsigned int	degreeInU,
		unsigned int	degreeInV,
		MFnNurbsSurface::Form	formU,
		MFnNurbsSurface::Form	formV,
		bool	createRational,
		MObject	parentOrOwner = `MObject::kNullObj`,
		MStatus *	ReturnStatus = `NULL`
	)

[in]	controlVertices	an array of control vertices
[in]	uKnotSequences	an array of U knot values
[in]	vKnotSequences	an array of V knot values
[in]	degreeInU	degree of first set of basis functions
[in]	degreeInV	degree of second set of basis functions
[in]	formU	open, closed, periodic in U
[in]	formV	open, closed, periodic in V
[in]	createRational	create as rational (true) or non-rational (false) surface
[in]	parentOrOwner	specifies what to do with the surface. If a DAG object or NULL is given then a transform will be created for the new surface and placed under the specified (optional)parent. If kNurbsSurfaceData is given then the surface will become its data.
[out]	ReturnStatus	Status code

MObject copy	(	const MObject &	source,
		MObject	parentOrOwner = `MObject::kNullObj`,
		MStatus *	ReturnStatus = `NULL`
	)

[in]	source	the surface to be copied
[in]	parentOrOwner	the DAG parent or kNurbsSurfaceData the new surface will belong to
[out]	ReturnStatus	Status code

MObject cv	(	unsigned int	indexU,
		unsigned int	indexV,
		MStatus *	ReturnStatus = `NULL`
	)

[in]	indexU	U index of CV
[in]	indexV	V index of CV
[out]	ReturnStatus	Status code

MObject cvsInU	(	unsigned int	startIndex,
		unsigned int	endIndex,
		unsigned int	rowIndex,
		MStatus *	ReturnStatus = `NULL`
	)

[in]	startIndex	start CV index in U
[in]	endIndex	end CV index in U
[in]	rowIndex	row index
[out]	ReturnStatus	Status code

MObject cvsInV	(	unsigned int	startIndex,
		unsigned int	endIndex,
		unsigned int	rowIndex,
		MStatus *	ReturnStatus = `NULL`
	)

[in]	startIndex	start CV index in V
[in]	endIndex	end CV index in V
[in]	rowIndex	row index
[out]	ReturnStatus	Status code

MStatus getCVs	(	MPointArray &	array,
		MSpace::Space	space = `MSpace::kObject`
	)		const

[out]	array	the array of point values for the CVs
[in]	space	specifies the coordinate system for this operation

MStatus setCVs	(	const MPointArray &	array,
		MSpace::Space	space = `MSpace::kObject`
	)

MFnNurbsSurface Class Reference

OpenMaya - API module for common classes | FunctionSet classes

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

[in]	array	The array of point values of the CVs
[in]	space	specifies the coordinate system for this operation

MStatus getCV	(	unsigned int	indexU,
		unsigned int	indexV,
		MPoint &	pnt,
		MSpace::Space	space = `MSpace::kObject`
	)		const

MStatus setCV	(	unsigned int	indexU,
		unsigned int	indexV,
		MPoint &	pt,
		MSpace::Space	space = `MSpace::kObject`
	)		const

bool isKnotU	(	double	param,
		MStatus *	ReturnStatus = `NULL`
	)		const

[in]	param	parameter value to test
[out]	ReturnStatus	Status code

bool isKnotV	(	double	param,
		MStatus *	ReturnStatus = `NULL`
	)		const

bool isParamOnSurface	(	double	paramU,
		double	paramV,
		MStatus *	ReturnStatus = `NULL`
	)		const

[in]	paramU	U parameter value
[in]	paramV	V parameter value
[out]	ReturnStatus	Status code

MStatus getKnotDomain	(	double &	startU,
		double &	endU,
		double &	startV,
		double &	endV
	)		const

[out]	startU	Start U parameter value
[out]	endU	End U parameter value
[out]	startV	Start V parameter value
[out]	endV	End V parameter value