Scripting: ApplyOp

ApplyOp

Introduced

v1.0

Description

Applies an operator to one or several objects, returns any objects created by the operator, and opens the newly applied operator's property page. This is a generic command that can apply any type of operator (hair, deform, generator, topology, custom, etc.).

You can also use commands that are specific to the type of operator you are applying. For example, the ApplyGenOp command can be used to apply generator operators (such as the Birail or Loft operators). Some operators have their own commands, such as the HairCombOp which can be applied with the ApplyHairCombOp.

This command supports group-level ConnectionSets only. To specify a port-level ConnectionSet, use the ApplyOperator command instead.

Tip: These type-specific commands often have features that are specialized for the type of operator you are applying. For example, the ApplyGenOp command gives the option of applying the operator in immediate or persistent mode and another option for what to do with the input (original) objects after the new geometry has been generated, whereas this command does not provide those options.

Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference. Normally you can get the output arguments via either XSIApplication.ExecuteCommand method (C#) or the ISIVTCollection (scripting languages), but this command already returns a value.

The only available workaround in this case is to create a VBScript custom command which returns both the output arguments and the return value in one array. For details, see What Happens when the Function Already Returns a Value?.

Scripting Syntax

oReturn = ApplyOp( PresetObj, [ConnectionSet], [ConnectType], [ImmediateMode], [OutputObjs], [ConstructionMode] );

Return Value

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

Parameters

Parameter	Type	Description
PresetObj	String or a preset object (for example, an object obtained from SIGetPreset)	Operator Preset.
ConnectionSet	ConnectionSet	Specifies the objects connected to an 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	siOperationMode	Specifies whether or not the operator should be immediately frozen. Default Value: siPersistentOperation
OutputObjs	XSICollection	Returns the primitives created by the operator. For example, Loft creates a primitive surface.
ConstructionMode	siConstructionMode	Specifies in which construction mode the operator will be applied. Default Value: Use the current construction mode

Examples

1. VBScript Example

'
' This example illustrates how to create
' loft operators
'
'
' Use Loft to create a surface from 2 curves
'
set curve1 = CreatePrim( "Arc", "NurbsCurve" )
translate curve1, , , 2
set curve2 = CreatePrim( "Arc", "NurbsCurve" )
set oplist = ApplyOp( "Loft", curve1 & "," & curve2,,,createdobjects )
set loftop = oplist(0)
' change the subdivision level in U
setvalue loftop & ".subdivu", 19
'
' Loft onto an existing surface
'
set surface = createdobjects(0)
surface.name = "Surface_created_by_lofting_2_curves"
set curve1 = CreatePrim( "Arc", "NurbsCurve" )
translate curve1, , , 2
set curve2 = CreatePrim( "Arc", "NurbsCurve" )
set surface = CreatePrim( "Grid", "NurbsSurface", "Loft_into_existing_surface" )
' Freeze the surface so that the object can be used to contain a
' new lofted surface
FreezeObj surface
set oplist = ApplyOp( "Loft", curve1 & "," & curve2 & ";" & surface )
set surface = oplist(0)
surface.name = "Surface_created_by_lofting_2_curves"

2. JScript Example

/* 
        Example showing how to retrieve the newly created operator
        when ApplyOp is called on a single object
*/
// Create primitive
oCube = activesceneroot.addgeometry( "Cube", "MeshSurface" );
// Call command to apply a Taper deformer and 
// retrieve the newly created operator
oColl = ApplyOp( "Taper", oCube, 3, 0, null, 0 ) ;
// Because there is only 1 input object (oCube)
// we know there is only one operator created
var oOp = oColl(0);
// Modify the Amplitude Parameter
oOp.ampl = 0.25 ;

3. JScript Example

// Create empty collection to store objects that
// we want to apply the operator to
oInputCollection = XSIFactory.CreateObject( "XSI.Collection" );
// Create primitive
oInputCollection.add( activesceneroot.addgeometry( "Cube", "MeshSurface" ) );
oInputCollection.add( activesceneroot.addgeometry( "Sphere", "MeshSurface" ) );
// Call command to apply a Taper deformer and populate collection with its return value
oOps = ApplyOp( "Taper", oInputCollection, 3, 0, null, 0 ) ;
// Validate result
for( var i=0; i < oOps.count; i++ )
{
// Get operator
oOp = oOps(i);
logmessage( oOp.fullname );
}
//Expected results:
//INFO : cube.polymsh.taperop
//INFO : sphere.polymsh.taperop