Iterator class for geometry data. More...

#include <MItGeometry.h>

Public Member Functions
	MItGeometry ()
	Constructor. More...

	MItGeometry (const MDagPath &dagPath, MStatus *ReturnStatus=NULL)
	Constructor. More...

	MItGeometry (const MDagPath &dagPath, MObject &component, MStatus *ReturnStatus=NULL)
	Constructor. More...

	MItGeometry (MObject &dagObject, MStatus *ReturnStatus=NULL)
	Constructor. More...

	MItGeometry (MDataHandle &dataHandle, unsigned int groupId, bool readOnly=true, MStatus *ReturnStatus=NULL)
	Constructor. More...

	MItGeometry (MDataHandle &dataHandle, bool readOnly=true, MStatus *ReturnStatus=NULL)
	Constructor. More...

	MItGeometry (MDataHandle &dataHandle, MObject &component, bool readOnly=true, MStatus *ReturnStatus=NULL)
	Constructor. More...

	MItGeometry (MDataHandle &dataHandle, const MString &componentTagExpression, bool readOnly=true, MStatus *ReturnStatus=NULL)
	Constructor. More...

virtual	~MItGeometry ()
	Class destructor. More...

bool	isDone (MStatus *ReturnStatus=NULL) const
	Returns true if the iteration is finished, i.e. More...

MStatus	next ()
	Advance to the next component in the iteration. More...

MPoint	position (MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
	Return the position of the current point/CV/vertex component. More...

MVector	normal (MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
	Return the normal of the current point/CV/vertex component. More...

MStatus	setPosition (const MPoint &point, MSpace::Space space=MSpace::kObject)
	Set the position of the current point/CV/vertex. More...

MWeight	weight (MStatus *ReturnStatus=NULL) const
	Return the weight of the current point/CV/vertex component. More...

int	index (MStatus *ReturnStatus=NULL) const
	This method returns the index of the current point/CV/vertex component in the iteration. More...

int	positionIndex (MStatus *ReturnStatus=NULL) const
	This method returns the position index of the current point/CV/vertex component in the iteration. More...

MObject	component (MStatus *ReturnStatus=NULL) const
	This method is obsolete. More...

MObject	currentItem (MStatus *ReturnStatus=NULL) const
	This method returns the current component in the iteration. More...

int	count (MStatus *ReturnStatus=NULL) const
	Return the number of items in this iteration. More...

int	exactCount (MStatus *ReturnStatus=NULL)
	Return the exact number of items in this iteration. More...

MStatus	reset ()
	Reset the iterator to the first component. More...

MStatus	allPositions (MPointArray &points, MSpace::Space space=MSpace::kObject) const
	Return the position of all the points/CVs/vertices. More...

MStatus	setAllPositions (const MPointArray &points, MSpace::Space space=MSpace::kObject)
	Set the position of all the points/CVs/vertices at once. More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...

Detailed Description

Iterator class for geometry data.

This class is the iterator class for geometry data, and can be used to loop over the CVs of NURBS, the points of subds & lattices, and the vertices of polygonal meshes.

Examples:: Simple traversal.

MItGeometry iter( dagPath );
for ( ; !iter.isDone(); iter.next() )
{
    MPoint pt = iter.position();
    // do something with it
}

Traversal of a geometry group within a compute() method.

MStatus
exampleIterator::compute(const MPlug& plug, MDataBlock& dataBlock)
{
    MStatus status;
    if (plug.attribute() == oOutputGeometry) {
        // get the input geometry and input groupId
        MDataHandle hInputGeom = dataBlock.inputValue(inputGeomAttr);
        MDataHandle hGroupId = dataBlock.inputValue(inputGroupIdAttr);
        unsigned int groupId = hGroup.asLong();
        MDataHandle hOutput = dataBlock.outputValue(plug);
        hOutput.copy(hInputGeom);
        // do an iteration where we get each point and set it to a new value
        MItGeometry iter(hOutput,groupId,false);
        for ( ; !iter.isDone(); iter.next()) {
            MPoint pt = iter.position();
            // do something here to modify the point ...
            iter.setPosition(pt);
        }
    } else {
        status = MStatus::kUnknownParameter;
    }        
    return status;
}

Examples:: basicBlendShape/basicBlendShape.cpp, basicBlendShapeDeformer/basicBlendShapeDeformer.cpp, basicMorphNode/basicMorphNode.cpp, basicSkinCluster/basicSkinCluster.cpp, clusterWeightFunction/clusterWeightFunction.cpp, exportJointClusterDataCmd/exportJointClusterDataCmd.cpp, exportSkinClusterDataCmd/exportSkinClusterDataCmd.cpp, identityGeomFilter/identityGeomFilter.cpp, identityNode/identityNode.cpp, offsetNode/offsetNode.cpp, richMoveCmd/richMoveCmd.cpp, splatDeformer/splatDeformer.cpp, and yTwistNode/yTwistNode.cpp.

Constructor & Destructor Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MItGeometry ( )

Constructor.

This constructor initialize an empty iterator not associated with any geometry.

MItGeometry	(	const MDagPath &	dagPath,
		MStatus *	ReturnStatus = `NULL`
	)

Constructor.

This constructor is used to iterate over all of the points/CV/vertices of a dag object given a particular dag path.

Parameters

[in]	dagPath	The dag path to the object.
[out]	ReturnStatus	Status code

Status Codes:

MS::kSuccess The iterator was constructed successfully.
MS::kInsufficientMemory No memory available.
MS::kInvalidParameter An invalid object was given.

MItGeometry	(	const MDagPath &	dagPath,
		MObject &	component,
		MStatus *	ReturnStatus = `NULL`
	)

Constructor.

This constructor is used to iterate over the points/CVs/vertices of a dag object given a particular dag path. The iteration will be over the points/CVs/Vertices specified by the component argument. If the component is null then the iteration will be over the entire object.

Parameters

[in]	dagPath	The dag path to the object.
[in]	component	The components of the object to iterate over. If this is null then the iteration will be over all components of the object.
[out]	ReturnStatus	Status code

Status Codes:

MS::kSuccess The iterator was constructed successfully.
MS::kInsufficientMemory No memory available.
MS::kInvalidParameter An invalid object was given.

MItGeometry	(	MObject &	dagObject,
		MStatus *	ReturnStatus = `NULL`
	)

Constructor.

This constructor is used to iterate over all of the points/CV/vertices of the given dag object. Since there is no path information passed into this constructor world space operations will not be possible.

Parameters

[in]	dagObject	The DAG object to iterate.
[out]	ReturnStatus	Status code

Status Codes:

MS::kSuccess The iterator was constructed successfully.
MS::kInsufficientMemory No memory available.
MS::kInvalidParameter An invalid object was given.

MItGeometry	(	MDataHandle &	dataHandle,
		unsigned int	groupId,
		bool	readOnly = `true`,
		MStatus *	ReturnStatus = `NULL`
	)

Constructor.

This constructor is used when iterating from within the compute() method of a node. The point/CV/vertex components of the specified group within the geometry data that is pointed to by the dataHandle will be iterated. If readOnly mode is set to false, the setPosition method can be utilized.

If the groupId does not exist on the shape it will return an empty iterator. (Note: this is a change in behavior introduced in Maya 2021. Before this a non-existing groupId would return an iterator over the entire geometry.)

A groupId with value 0 is the standard definition of a non-existing group and therefore this will always return an empty iterator. A groupId of -1 can be used to denote we want an iterator over the entire geometry.

Parameters

[in]	dataHandle	The dataHandle pointing to the geometry data.
[in]	groupId	The id of the group whose components will be iterated.
[in]	readOnly	If false you will be allowed to modify the geometry position data during the iteration.
[out]	ReturnStatus	Status code

Status Codes:

MS::kSuccess The iterator was constructed successfully.
MS::kInsufficientMemory No memory available.
MS::kInvalidParameter An invalid object was given.

MItGeometry	(	MDataHandle &	dataHandle,
		bool	readOnly = `true`,
		MStatus *	ReturnStatus = `NULL`
	)

Constructor.

This constructor is used when iterating from within the compute() method of a node. The point/CV/vertex components of the geometry data pointed to by the dataHandle will be iterated. If readOnly mode is set to false, the setPosition method can be utilized.

Parameters

[in]	dataHandle	The dataHandle pointing to the geometry data.
[in]	readOnly	If false you will be allowed to modify the geometry position data during the iteration.
[out]	ReturnStatus	Status code

Status Codes:

MS::kSuccess The iterator was constructed successfully.
MS::kInsufficientMemory No memory available.
MS::kInvalidParameter An invalid object was given.

MItGeometry	(	MDataHandle &	dataHandle,
		MObject &	component,
		bool	readOnly = `true`,
		MStatus *	ReturnStatus = `NULL`
	)

Constructor.

This constructor is used when iterating from within the compute() method of a node. The point/CV/vertex components of the specified component within the geometry data that is pointed to by the dataHandle will be iterated. If readOnly mode is set to false, the setPosition method can be utilized.

Parameters

[in]	dataHandle	The dataHandle pointing to the geometry data.
[in]	component	The components to be iterated.
[in]	readOnly	If false you will be allowed to modify the geometry position data during the iteration.
[out]	ReturnStatus	Status code

Status Codes:

MS::kSuccess The iterator was constructed successfully.
MS::kInsufficientMemory No memory available.
MS::kInvalidParameter An invalid object was given.

MItGeometry	(	MDataHandle &	dataHandle,
		const MString &	componentTagExpression,
		bool	readOnly = `true`,
		MStatus *	ReturnStatus = `NULL`
	)

Constructor.

This constructor is used when iterating over a subset of the geometry specified by a componentTagExpression. If readOnly mode is set to false, the setPosition method can be utilized.

Parameters

[in]	dataHandle	The dataHandle pointing to the geometry data.
[in]	componentTagExpression	The component tag expression to be iterated.
[in]	readOnly	If false you will be allowed to modify the geometry position data during the iteration.
[out]	ReturnStatus	Status code

Status Codes:

MS::kSuccess The iterator was constructed successfully.
MS::kInsufficientMemory No memory available.
MS::kInvalidParameter An invalid object was given.

~MItGeometry ( )

virtual

Class destructor.

Deallocates memory used by this iterator.

Member Function Documentation

bool isDone ( MStatus * ReturnStatus = NULL ) const

Returns true if the iteration is finished, i.e.

there are no more components to iterate on.

Parameters

[out] ReturnStatus Status code

Returns: Bool true if There are no more components to iterate on, false otherwise.

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

Examples:: basicBlendShapeDeformer/basicBlendShapeDeformer.cpp, basicMorphNode/basicMorphNode.cpp, basicSkinCluster/basicSkinCluster.cpp, identityGeomFilter/identityGeomFilter.cpp, identityNode/identityNode.cpp, offsetNode/offsetNode.cpp, richMoveCmd/richMoveCmd.cpp, and yTwistNode/yTwistNode.cpp.

MStatus next ( )

Advance to the next component in the iteration.

If the iterator is already at the last component then this method has no effect. Use isDone to determine if the iterator is at the last component.

Returns: Status code

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

Examples:: basicBlendShapeDeformer/basicBlendShapeDeformer.cpp, basicMorphNode/basicMorphNode.cpp, basicSkinCluster/basicSkinCluster.cpp, identityGeomFilter/identityGeomFilter.cpp, identityNode/identityNode.cpp, offsetNode/offsetNode.cpp, and yTwistNode/yTwistNode.cpp.

MPoint position	(	MSpace::Space	space = `MSpace::kObject`,
		MStatus *	ReturnStatus = `NULL`
	)		const

Return the position of the current point/CV/vertex component.

Parameters

[in]	space	The transformation space in which the operation is done
[out]	ReturnStatus	Status code

Returns: The current component's position

Status Codes:

MS::kSuccess The position of the current component was returned.
MS::kInvalidParameter Cannot do world space transform.
MS::kFailure An Object error has occurred.

Examples:: basicBlendShapeDeformer/basicBlendShapeDeformer.cpp, basicMorphNode/basicMorphNode.cpp, basicSkinCluster/basicSkinCluster.cpp, identityGeomFilter/identityGeomFilter.cpp, identityNode/identityNode.cpp, offsetNode/offsetNode.cpp, and yTwistNode/yTwistNode.cpp.

MVector normal	(	MSpace::Space	space = `MSpace::kObject`,
		MStatus *	ReturnStatus = `NULL`
	)		const

Return the normal of the current point/CV/vertex component.

Parameters

[in]	space	The transformation space in which the operation is done
[out]	ReturnStatus	Status code

Returns: The current component's normal

Status Codes:

MS::kSuccess The normal of the current component was returned.
MS::kInvalidParameter Cannot do world space transform.
MS::kFailure An Object error has occurred.

MStatus setPosition	(	const MPoint &	pt,
		MSpace::Space	space = `MSpace::kObject`
	)

Set the position of the current point/CV/vertex.

Parameters

[in]	pt	New position.
[in]	space	The transformation space in which the operation is done.

Returns: Status code

Status Codes:

MS::kSuccess The transformation was successful.
MS::kInvalidParameter Cannot do world space transform.
MS::kFailure The transformation was not successful because the data was read only.

Examples:: basicBlendShapeDeformer/basicBlendShapeDeformer.cpp, basicMorphNode/basicMorphNode.cpp, basicSkinCluster/basicSkinCluster.cpp, identityGeomFilter/identityGeomFilter.cpp, identityNode/identityNode.cpp, offsetNode/offsetNode.cpp, and yTwistNode/yTwistNode.cpp.

MWeight weight ( MStatus * ReturnStatus = NULL ) const

Return the weight of the current point/CV/vertex component.

Parameters

[out] ReturnStatus Status code

Returns: The current component's weight

int index ( MStatus * ReturnStatus = NULL ) const

This method returns the index of the current point/CV/vertex component in the iteration.

The index matches the index of the point into the array returned from the geometry, for example by using MFnMesh::getPoints() or MFnNurbsSurface::getCVs()

Parameters

[out] ReturnStatus Status code

Returns: The index of the current point/CV/vertex.

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

Examples:: basicBlendShapeDeformer/basicBlendShapeDeformer.cpp, basicMorphNode/basicMorphNode.cpp, and offsetNode/offsetNode.cpp.

int positionIndex ( MStatus * ReturnStatus = NULL ) const

This method returns the position index of the current point/CV/vertex component in the iteration.

The positionIndex matches the index of the point into the array that would be returned from an iterator over the entire geometry.

Note that this can be different from index(). For most geometry types (like a Mesh) they will be the same, but for surfaces that wrap around and double up points like a NurbsSurface they can be different.

Parameters

[out] ReturnStatus Status code

Returns: The index of the current point/CV/vertex.

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

MObject component ( MStatus * ReturnStatus = NULL ) const

This method is obsolete.

This method returns the current component in the iteration.

[as of Maya 2019]

Deprecated:: Use MItGeometry::currentItem instead.

Parameters

[out] ReturnStatus Status code

Returns: The current component in the iteration.

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

MObject currentItem ( MStatus * ReturnStatus = NULL ) const

This method returns the current component in the iteration.

Parameters

[out] ReturnStatus Status code

Returns: The current component in the iteration.

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

int count ( MStatus * ReturnStatus = NULL ) const

Return the number of items in this iteration.

This number will always be at least as large as the number of items, however in some cases it may be larger. It is useful if allocating space in an array to hold the results, since it will always be of sufficient size. If the exact number of items is required, use the exactCount method instead. The exactCount method is however significantly slower than this method.

Parameters

[out] ReturnStatus Status code

Returns: The number of items that will be iterated

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

int exactCount ( MStatus * ReturnStatus = NULL )

Return the exact number of items in this iteration.

This method is significantly slower than the count() method, so use if only if the precise number is required.

Parameters

[out] ReturnStatus Status code

Returns: The number of items that will be iterated

Status Codes:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

MStatus reset ( )

Reset the iterator to the first component.

Returns: Status code

Status Codes:

MS::kSuccess The iterator was successfully reset
MS::kFailure Error resetting iterator

MStatus allPositions	(	MPointArray &	points,
		MSpace::Space	space = `MSpace::kObject`
	)		const

Return the position of all the points/CVs/vertices.

This operation is faster than using the iterator to get values one by one, but uses more memory as it requires an array to hold all the values to be returned.

Parameters

[out]	points	Storage for positions
[in]	space	The transformation space in which the operation is done

Returns: Status code

Status Codes:

MS::kSuccess The position of the current component was returned.
MS::kInvalidParameter Cannot do world space transform.
MS::kFailure An Object error has occurred.

MStatus setAllPositions	(	const MPointArray &	pt,
		MSpace::Space	space = `MSpace::kObject`
	)

Set the position of all the points/CVs/vertices at once.

This operation is faster than using the iterator to set values one by one, but uses more memory as it requires an array to hold all the values to be set.

Parameters

[in]	pt	An array containing all the positions to be set
[in]	space	The transformation space in which the operation is done

Returns: Status code

Status Codes:

MS::kSuccess The transformation was successful.
MS::kInvalidParameter Cannot do world space transform.
MS::kFailure The transformation was not successful because the data was read only.

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

The documentation for this class was generated from the following files:

MItGeometry.h
MItGeometry.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation