ApplyTopoOp

Introduced

1.5

Description

Applies and returns a topology operator. A topology operator is an operator which modifies existing geometry, such as adding or removing edges. For example, AddEdge, DissolveComponent, and SubdividePolygon are all examples of topology operators.

Tip: You can also use the ApplyOp command to apply a topology operator.

Note: This command uses output arguments. Some scripting languages don't support arguments passed by reference (such as JScript, PerlScript and Python). Normally these languages can use the ISIVTCollection to get the output arguments; however, since this command already returns a value, that particular workaround is not available (see About Output Argument Arrays for more information).

Scripting Syntax

    ApplyTopoOp( PresetObj, [ConnectionSet], [ConnectType], [ImmediateMode], [OutputObjs], [ConstructionMode] )

Parameters

Parameter | Type | Description
PresetObj | String or a preset object (see SIGetPreset) | Topology Operators
ConnectionSet [in/out] | ConnectionSet | Specifies the objects connected to an operator. See Operator Presets for details on the connection set required for this operator. Note: Because this is an in/out parameter, any string (variable or value) you pass into this parameter is automatically converted to a ConnectionSet object. Default Value: Currently selected objects are used as the main group. Warning: An error occurs if the connection set is invalid. Please verify the connection set required for this operator to avoid breaking your scripts.
ConnectType | siBranchFlag | Specifies the type of connection (node or branch). Default Value: siUnspecified
ImmediateMode [in/out] | siOperationMode | Specifies whether or not the operator should be immediately frozen. Default Value: siPersistentOperation
OutputObjs [in/out] | XSICollection | Returns the primitives created by the operator. For now none return an object
ConstructionMode | siConstructionMode | Specifies in which construction mode the 'Delete Edge' operator will be applied. Default Value: Use the current construction mode

Return Value

Returns an XSICollection that contains a list of the created operators.

Note: If you apply the operator in ImmediateMode (which immediately freezes it), you still get a collection of the operators applied, but they are invalid (not connected to anything in the scene).

Examples

1. VBScript Example

    ' Collapse some vertices on a polygon mesh.
    dim obj, op
    set obj = CreatePrim( "Grid", "MeshSurface" )
    set op = ApplyTopoOp( "Collapse" , "grid.pnt[30-32,39-41,48-50]" )

2. JScript Example

    // Example demonstrating how to get use ApplyTopoOp
    // to create an operator and retrieve it from the return value.

    NewScene( null, false );

    // Get a pointer to the internal object database.
    var objdata = XSIUtils.DataRepository;

    // Apply the Collapse operator in ImmediateMode to see what gets returned.
    var obj = CreatePrim( "Grid", "MeshSurface" );
    var ops = ApplyTopoOp( "Collapse" , obj + ".pnt[30-32,39-41,48-50]", null, siPersistentOperation);

    // Because we only apply to a single object we only expect a
    // single item in the XSICollection.  But
    // it is a good habit to use a "for" loop
    // to go through all elements.

    for (var i=0; i<ops.Count; i++) {
       logmessage( "New Operator: " + ops(i).Name +
            ", Type: " + ops(i).Type +
    ", ClassName: " + ClassName( ops(i) ) ) ;
    }

    // Output of above script:
    //INFO : New Operator: Collapse Op ,Type: collapseop, ClassName: Operator

3. JScript Example

    /*
       This example demonstrates what gets returned when you apply and freeze a TopoOp with the
       ApplyTopoOp command in siImmediateOperation mode.

       The command still returns a pointer to the operator, but, unlike the
       example above, it no longer exists in the scene, so you can't do anything with it.

       The tricky part is testing the returned object to see whether it is valid or not. Normally you can
       test the class or type to determine its validity; however, these operators will tell you
       that they are Operator objects (Application.ClassName). The Type property
       returns an empty string, which you can also use to test for an operator's validity, but
       this example uses the DataRepository object instead.

       The DataRepository object is an internal database which keeps track of objects in Softimage. It
       holds the ID for each object in the system which you can retrieve with the GetIdentifier
       method.

       Note: This example is only provided to illustrate what to expect from an XSICollection
       containing frozen operators. Normally, you would not be interested in the returned value
       of an apply-and-freeze-operator operation.
    */

    NewScene( null, false );

    // Get a pointer to the internal object database.
    var objdata = XSIUtils.DataRepository;

    // Apply the Collapse operator in ImmediateMode to see what gets returned.
    var obj = CreatePrim( "Grid", "MeshSurface" );
    var ops = ApplyTopoOp( "Collapse" , obj + ".pnt[30-32,39-41,48-50]", null, siImmediateOperation );
    for (var i=0; i<ops.Count; i++) {
       // Normally this returns 'collapseop'
       logmessage( "Type returns: '" + ops(i).Type + "'" );

       // Wrap the call to DataRepository.GetIdentifier in a try-catch block because it will
       // throw an error if the object is invalid (if it's valid, you would see a GUID)
       try {
           logmessage( objdata.GetIdentifier(ops(i), siObjectGUID) );
       } catch(e) {
           logmessage( "object is not valid" );
       }
    }

    // Output of above script:
    //INFO : Type returns: ''
    //INFO : object is not valid

See Also

ApplyOperator | ApplyOp | ApplyGenOp | ApplyHairOp
Topology Operators |  |  |

Autodesk Softimage v7.5