ClusterElementColle ction

Related C++ Class: CClusterElementArray

Introduced

1.0

Description

A collection of cluster elements in a Cluster object or ClusterProperty object.

The purpose of the data stored in this object depends whether it is on a Cluster or a ClusterProperty.

The ClusterElementCollection returned by Cluster.Elements (and Envelope.Elements) provides the mapping between an index of a component in a cluster with the index of the component on the Geometry. For example index 10 on a polygon Cluster might refer to Polygon 45 on the geometry, in which case ClusterElementCollection.Item(10) has the value 45. This data is read-only.

When trying to find if a particular geometry component is part of a cluster it would be possible to search through this array. However a more convenient and efficient method is to use Cluster.FindIndex.

On the other hand, the ClusterElementCollection returned by ClusterProperty.Elements (and Envelope.Weights) provides read/write access to the actual data of the ClusterProperty. For example in the case of a Vertex Color property this provides access to the RGB values stored for each component. In this case the first dimension has size 3, corresponding to the RGB values and the second dimension corresponds to the index of the component. The values are always represented as Doubles.

Methods

FindIndex

Properties

Array | ClusterElementCollection.Count | ClusterElementCollection.Item | ItemsByIndex

Examples

1. VBScript Example

    '
    ' This example demonstrates how to read and write the values on
    ' a weight map, using the ClusterElementCollection object.

    ' It also demonstrates how the indices on the cluster property
    ' correspond to the indices of the cluster, but that these indices do
    ' not directly correspond to the indices on the geometry.

    NewScene ,false

    set oSphere = ActiveSceneRoot.AddGeometry("Sphere","NurbsSurface")

    ' Create a weight map on a cluster that includes only a subset of the points
    set oCluster = oSphere.ActivePrimitive.Geometry.AddCluster( _
       siVertexCluster, "MyFrontPoints", Array( 18,19,20,25,26,27) )

    CreateWeightMap , oCluster.FullName, "MyWeightMap"

    set oWM = oCluster.LocalProperties( "MyWeightMap" )

    ' Use the ClusterElementCollection.Array to access all the weights in a
    ' single 2-dimensional array

    ElArray = oWM.Elements.Array

    ' Set the weight on second item in the cluster, (which is point 19), to 100
    ElArray(0,1) = 100

    ' Set the weight on point 25 to 99
    ElArray(0,3) = 99

    ' Copy our altered array of values back onto the weight map
    oWM.Elements.Array = ElArray

    ' Use ClusterElementCollection.Item to set an individual weight on the
    ' Weight Map.  Notice how it is still using an array

    'Create a 1 Dimensional array with 1 element
       dim myWeight(0)
    myWeight(0) = 10

    'Assign the value
       oWM.Elements.Item( 2 ) = myWeight

    'Print out the contents
       set oCluster = oWM.Parent

    for i = 0 to oWM.Elements.Count - 1
       indexOnGeometry = oCluster.Elements.Item(i)
       logmessage "Weight at " & i & " (pnt" & indexOnGeometry  & _
           ") is " & oWM.Elements.Item(i)(0)
    next

    'Output of running this script is:
       'INFO : "Weight at 0 (pnt18) is 1"
    'INFO : "Weight at 1 (pnt19) is 100"
    'INFO : "Weight at 2 (pnt20) is 10"
    'INFO : "Weight at 3 (pnt25) is 99"
    'INFO : "Weight at 4 (pnt26) is 1"
    'INFO : "Weight at 5 (pnt27) is 1"

2. PerlScript Example

    #
    #  This example demonstrates how to work with UVs and safearrays in Perl
    #

    my $root = $Application->ActiveSceneRoot;
    my $object = $root->AddGeometry( "Cube", "MeshSurface" );

    # Create a UV Cluster property on the cube
    $Application->BlendInPresets( "Image", $object, 1, false );
    $Application->CreateTextureSupport( $object, $siTxtUV, siTxtDefaultSpherical, "Texture_Support" );
    $Application->SetInstanceDataValue( $object, "cube.Scene_Material.UV", "Texture_Support");

    # Get the UVW property from the texture support
    my $uvw_prop = $object->Material->CurrentUV;

    # The ClusterElementCollection.Array property returns a 2-dimensional array...
    my @rtn = $uvw_prop->Elements->Array;

    # The returned array contains 1 element only, a reference to another array, so dereference
    # that element to get the nested array (an array of references to other arrays)
    my @nested_array = @{$rtn[0]};
    my $nbr_of_dimensions = 0;

    # Info for logging
    my $vals  = "------------\nCluster Property Values: \n------------\n";
    my $stats = "------------\nNested Array Information:\n------------\n";

    # Loop through the array of references to other arrays
    for my $array_ref (@nested_array) {
       # Counter to keep track of # of values found for this dimension
       my $nbr_of_elements = 0;

       # Since each element of @nested_array is a reference to another array (3 in total
       # for the U, V, and W values), you need to dereference each element to get the
       # actual U, V, or W value for a given cluster.
       for my $value_for_u_v_or_w (@{$array_ref}) {
           # Increment the # of elements found
           $nbr_of_elements++;
       }

       # Save info for logging
       if ($nbr_of_dimensions>1) {$_ = "[W] ="} elsif ($nbr_of_dimensions>0) {$_ = "[V] ="} else {$_ = "[U] ="}
       $vals .= "$_ @{$array_ref}\n";

       $stats .= "Number of elements in dimension $nbr_of_dimensions: $nbr_of_elements (Clusters)\n";
       $nbr_of_dimensions++;
    }

    # Finish compiling and log messages
    $stats .= "\nNumber of dimensions in this array: $nbr_of_dimensions (U,V,W)";
    $Application->LogMessage( "\n$vals \n$stats" );

    # Expected result:
    #INFO :
    #------------
    #Cluster Property Values:
    #------------
    #[U] = 0 0 1 1 0 1 1 0 0 0 0 0 1 1 1 1 0 0 1 1 0 1 1 0
    #[V] = 0 1 1 0 0 0 0 0 0 0 1 1 0 1 1 0 1 1 1 1 0 0 1 1
    #[W] = 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
    #
    #------------
    #Nested Array Information:
    #------------
    #Number of elements in dimension 0: 24 (Clusters)
    #Number of elements in dimension 1: 24 (Clusters)
    #Number of elements in dimension 2: 24 (Clusters)
    #
    #Number of dimensions in this array: 3 (U,V,W)

See Also

Cluster.Elements | ClusterProperty.Elements | Envelope.Weights

Autodesk Softimage v7.5