Detailed Description

A cluster represents a set of components on a Geometry.

For example, the polygons of the left arm of a human model might be grouped together by creating a cluster.

A cluster has a type (see SIObject::GetType) which corresponds to the component type that it contains, (pnt, knot, poly). A geometry can have multiple clusters, including clusters of different types. Any particular component might be included in multiple clusters. The ::ClusterTypes that are supported on a geometry depend on the type of object. For example only NurbsSurface or NurbsCurve can have a siKnotCluster.

Clusters can be created on the geometry of a ParticleCloud. These clusters are of type siVertexCluster but they contain Particles.

A cluster that includes all the components of a particular type is said to be always complete, which you can verify with Cluster::IsAlwaysComplete. An always-complete cluster always covers all components of the geometry, even when components are added by a modeling operation; however, notice that a cluster which covers all components of a geometry is not necessarily always-complete. Other clusters may contain a subset of components. In all cases the indices of the components in the cluster do not directly match the indices of the component on the geometry. The mapping between cluster indices and geometry indices is available through Cluster::GetElements and Cluster::FindIndices.

Clusters are useful for storing per-component data with a ClusterProperty or UserDataMap. Clusters can also have their own CustomProperty objects. All these properties can be created with SceneItem::AddProperty and enumerated with SceneItem::GetLocalProperties. Notice that some types of ClusterProperty require the cluster to be always complete.

Warning:: Operations that change the geometry, for example adding an edge to a mesh, can result in the cluster growing or shrinking.

Note:: As of v5.0, the base property SIObject::GetParent called on a Cluster object returns a Primitive instead of an X3DObject.

See also:: Geometry, CClusterElementArray

Example:

        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        X3DObject myGrid;
        root.AddGeometry( L"Grid", L"MeshSurface", L"", myGrid );

        Cluster myCls;
        CLongArray indices(9);
        indices[0] = 8; indices[1] = 16; indices[2] = 24; indices[3] = 32;
        indices[4] = 40; indices[5] = 48; indices[6] = 56; indices[7] = 64;
        indices[8] = 72;

        myGrid.GetActivePrimitive().GetGeometry().AddCluster(siVertexCluster, L"",
            indices, myCls );

        app.LogMessage( L"Cluster type: " + myCls.GetClassIDName() );

#include <xsi_cluster.h>

Inheritance diagram for Cluster:

[legend]

List of all members.

Public Member Functions
	Cluster ()
	~Cluster ()
	Cluster (const CRef &in_ref)
	Cluster (const Cluster &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Cluster &	operator= (const Cluster &in_obj)
Cluster &	operator= (const CRef &in_ref)
CClusterElementArray	GetElements () const
X3DObject	GetCenterReference () const
CStatus	PutCenterReference (const X3DObject &in_centerObj)
bool	HasStaticKinematicState () const
CRefArray	GetStaticKinematicStates () const
SubComponent	CreateSubComponent ()
CStatus	FindIndex (LONG in_geometryIndex, LONG &out_clusterIndex) const
CStatus	FindIndices (const CLongArray &in_geometryIndices, CLongArray &out_clusterIndices) const
bool	IsAlwaysComplete () const
CStatus	GetGeometryElementFlags (CBitArray &out_flags) const

Constructor & Destructor Documentation

Cluster ( )

Default constructor.

~Cluster ( )

Default destructor.

Cluster ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Cluster ( const Cluster & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from SceneItem.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:: The class type.

Reimplemented from SceneItem.

Cluster& operator= ( const Cluster & in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj constant class object.

Returns:: The new Cluster object.

Cluster& operator= ( const CRef & in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: The new Cluster object.

Reimplemented from SceneItem.

CClusterElementArray GetElements ( ) const

Returns an array of geometry indices represented by the cluster.

Returns:: The new CClusterElementArray object.

X3DObject GetCenterReference ( ) const

Returns the cluster center reference.

Returns:: The cluster reference object.

CStatus PutCenterReference ( const X3DObject & in_centerObj )

Sets the cluster center reference. If the reference is empty, the ClusterCenter operator is deleted.

Parameters:

in_centerObj Object to be used as the center reference.

Returns:: CStatus::OK success; CStatus::Fail failure

bool HasStaticKinematicState ( ) const

Returns true if the cluster has a base pose. The base pose is represented by a StaticKinematicState property.

Returns:: True if the cluster has a base pose, false otherwise.

CRefArray GetStaticKinematicStates ( ) const

Returns an array containing all StaticKinematicState properties on the cluster.

Returns:: Array of references to StaticKinematicState properties.

SubComponent CreateSubComponent ( )

Creates a SubComponent from the cluster type.

Returns:: A SubComponent object.

CStatus FindIndex	(	LONG	in_geometryIndex,
		LONG &	out_clusterIndex
	)		const

Returns the cluster index corresponding to the specified geometry component index.

Parameters:

in_geometryIndex Geometry component index.

Return values:

out_clusterIndex Cluster index corresponding to the geometry index or -1 if the geometry index is not part of the cluster.

Returns:: CStatus::OK success; CStatus::Fail failure

CStatus FindIndices	(	const CLongArray &	in_geometryIndices,
		CLongArray &	out_clusterIndices
	)		const

Returns the cluster indices corresponding to the specified geometry component indices.

Parameters:

in_geometryIndices Array of geometry component indices.

Return values:

out_clusterIndices Array of cluster indices corresponding to the geometry indices or -1 if the geometry index is not part of the cluster.

Returns:: CStatus::OK success; CStatus::Fail failure

Example:

        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        X3DObject myGrid;
        root.AddGeometry( L"Grid", L"MeshSurface", L"", myGrid );

        CLongArray indices(3);
        indices[0] = 0; indices[1] = 3; indices[2] = 22;

        Geometry myMesh(myGrid.GetActivePrimitive().GetGeometry());
        Cluster myCls;
        myMesh.AddCluster(siVertexCluster, L"", indices, myCls );

        Facet myFacet(myMesh.GetFacets().GetItem(0));
        CLongArray aPointIndices = myFacet.GetPoints().GetIndexArray();

        CLongArray aClusterIndices;
        myCls.FindIndices(aPointIndices, aClusterIndices);

        for (LONG i=0; i<(LONG)aClusterIndices.GetCount(); ++i)
        {
            if ( aClusterIndices[i] == -1 )
                app.LogMessage( L"The point index " +
                                CValue(aPointIndices[i]).GetAsText() +
                                L" is not part of the cluster.");
            else
                app.LogMessage(L"Cluster index for point index " +
                    CValue(aPointIndices[i]).GetAsText() + L"= " +
                    CValue(aClusterIndices[i]).GetAsText());
        }

bool IsAlwaysComplete ( ) const

Returns true if the cluster is maintained as always complete. If so, the cluster will always cover all geometry's components even under modeling operations.

Returns:: True if the cluster is always complete, false otherwise.

Since:: 5.0

CStatus GetGeometryElementFlags ( CBitArray & out_flags ) const

Returns an array of flags containing the geometry elements set on this cluster. The array size matches the number of elements on the geometry for this cluster type. A true flag indicates a cluster element, the position of the flag in the array corresponds to the cluster element.

If the cluster was generated by an instance of CGeometryAccessor initialized with a subdivision level > 0, the array matches the number of subdivided elements on the underlying geometry.

Note:: This function will only work for clusters defined on a polygon mesh geometry.

Return values:

out_flags The element flags for this cluster

Returns:: CStatus::OK success; CStatus::False No elements defined on the cluster; CStatus::Fail Error

See also:: CGeometryAccessor, CClusterPropertyBuilder

Since:: 5.0

Example:

        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        X3DObject myCone;
        root.AddGeometry( L"Cone", L"MeshSurface", L"", myCone );

        PolygonMesh myMesh(myCone.GetActivePrimitive().GetGeometry());

        CClusterPropertyBuilder cpBuilder = myMesh.GetClusterPropertyBuilder();

        // add a vertex color property on the geometry, this creates a complete node
        // cluster on the geometry
        ClusterProperty color = cpBuilder.AddVertexColor();

        // add a weight map property on the geometry, this creates an empty vertex
        // cluster
        ClusterProperty wmap = cpBuilder.AddWeightMap(false);

        // set the color vertex values
        LONG indices[] = {0, 3, 22};

        float colors[] =
        {
            1.0f, 0.0f, 0.0f,
            0.0f, 1.0f, 0.0f,
            0.0f, 0.0f, 1.0f
        };

        color.SetValues( indices, colors, 3 );

        // set the weight map values
        float weights[] = { 1.0f, 0.5f, 0.75f };

        wmap.SetValues( indices, weights, 3 );

        // get a geometry accessor initialized with a subdivision level of 1
        CGeometryAccessor ga = myMesh.GetGeometryAccessor(siConstructionModeModeling, siCatmullClark, 1);

        // get the node and vertex clusters created with CClusterPropertyBuilder
        CRefArray clusters = ga.GetAllClusters();

        // log the clusters element ids
        for (LONG i=0; i<clusters.GetCount(); i++)
        {
            Cluster cls = clusters[i];

            CBitArray flags;
            CStatus st = cls.GetGeometryElementFlags( flags );
            st.AssertSucceeded();

            app.LogMessage( L"Cluster name: " + cls.GetName() );
            app.LogMessage( L"Nb geometry elements: " + CString(flags.GetCount()) );
            app.LogMessage( L"Nb cluster elements: " + CString(flags.GetTrueCount()) );

            LONG idx = flags.GetIterator();
            while( flags.GetNextTrueBit( idx ) )
            {
                app.LogMessage( CString(idx) + L":" + CString( flags[idx] ) );
            }
        }

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

xsi_cluster.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation