## Filter

Object Hierarchy | Related C++ Class: Filter

### Inheritance

SIObject

Filter

### Introduced

v4.0

### Description

The Filter object represents an instance of a Softimage filter. Filters are used by Softimage interactive tools and OM objects for validating the use of a set of objects in a given context. Softimage already defines a set of native filters available to users and can be extended with custom filter objects.
Custom filters are defined with a plug-in which can be either compiled or scripted (see Building and Deploying Customizations for a detailed workflow). The mapping between a Filter object and a custom filter plug-in is transparent to the user, each method of the Filter object maps to a specific function callback supplied by the custom filter. The callback functions are documented with each method of the Filter object, please refer to these methods documentation for further details.
The siFilterType enum lists the supported filter types (the type of a filter specifies what the filter does; for example, a filter of type siFilter3DObject filters 3D objects).
The FilterConstant enum lists the built-in filters that you can use.
Like native filters, custom filters can also be used with other base filter functions defined in the SDK such as SIFilter, X3DObjectCollection.Filter, etc...

### Methods

IsApplicable | IsClassOf | IsEqualTo | Match
Subset |  |  |

### Properties

Application | Categories | FullName | Help
Name | NestedObjects | Origin | OriginPath
Parent | Type |  |

### Examples

#### 1. JScript Example

    // display all filters defined in Softimage
    var app = Application;
    var filterArray = app.Filters;
    for (var i=0; i<filterArray.Count; i++)
    {
            app.LogMessage( filterArray(i).Name );
    }
    // sample filter tests
    var root = app.ActiveSceneRoot;
    var sphere = root.AddGeometry( "Sphere", "MeshSurface", "sphere" );
    TestFilter( "Object", root );
    TestFilter( "PolygonMesh", sphere );
    var arr = root.Children;
    var strTest = root.Name + " children";
    TestFilter2( "Object", strTest, arr );
    TestFilter2( "Light", strTest, arr );
    TestFilter2( "Camera", strTest, arr );
    TestFilter2( "PolygonMesh", strTest, arr );
    arr = root.Properties;
    strTest = root.Name + " properties";
    TestFilter2( "Object", strTest, arr );
    TestFilter2( "Light", strTest, arr );
    // helper functions for logging filter operations results
    function TestFilter( in_strFilter, in_ref )
    {
            var app = Application;
            var filter = app.Filters( in_strFilter );
            var bApplicable = filter.IsApplicable(in_ref);
            var bMatch = filter.Match(in_ref);
            app.LogMessage( "*** Filter: " + filter.Name );
            app.LogMessage( "   Target: " + in_ref.Name );
            app.LogMessage( "   Applicable: " + bApplicable );
            app.LogMessage( "   Match: " + bMatch );
    }
    function TestFilter2( in_strFilter, in_strTest, in_arr )
    {
            var app = Application;
            var filter = app.Filters( in_strFilter );
            var bApplicable = filter.IsApplicable(in_arr);
            var bMatch = filter.Match(in_arr);
            var subArray = filter.Subset(in_arr);
            app.LogMessage( "*** Filter: " + filter.Name );
            app.LogMessage( "   Target: " + in_strTest + " count: " + in_arr.Count );
            app.LogMessage( "   Applicable: " + bApplicable );
            app.LogMessage( "   Match: " + bMatch );
            app.LogMessage( "   Subset: " + subArray.Count );
    }
    // Output will include items like this:
    //INFO : "object"
    //INFO : "Null"
    //INFO : "Curve"
    //INFO : "PolygonMesh"
    //INFO : "SurfaceMesh"
    //INFO : "Implicit"
    // etc...
    //INFO : "*** Filter: object"
    //INFO : "   Target: Scene_Root"
    //INFO : "   Applicable: true"
    //INFO : "   Match: true"
    //INFO : "*** Filter: PolygonMesh"
    //INFO : "   Target: sphere"
    //INFO : "   Applicable: true"
    //INFO : "   Match: true"
    //INFO : "*** Filter: object"
    //INFO : "   Target: Scene_Root children count: 3"
    //INFO : "   Applicable: true"
    //INFO : "   Match: true"
    //INFO : "   Subset: 3"
    //INFO : "*** Filter: Light"
    //INFO : "   Target: Scene_Root children count: 3"
    //INFO : "   Applicable: true"
    //INFO : "   Match: false"
    //INFO : "   Subset: 1"
    //INFO : "*** Filter: Camera"
    //INFO : "   Target: Scene_Root children count: 3"
    //INFO : "   Applicable: true"
    //INFO : "   Match: false"
    //INFO : "   Subset: 0"
    //INFO : "*** Filter: PolygonMesh"
    //INFO : "   Target: Scene_Root children count: 3"
    //INFO : "   Applicable: true"
    //INFO : "   Match: false"
    //INFO : "   Subset: 1"
    //INFO : "*** Filter: object"
    //INFO : "   Target: Scene_Root properties count: 5"
    //INFO : "   Applicable: true"
    //INFO : "   Match: true"
    //INFO : "   Subset: 5"
    //INFO : "*** Filter: Light"
    //INFO : "   Target: Scene_Root properties count: 5"
    //INFO : "   Applicable: true"
    //INFO : "   Match: false"
    //INFO : "   Subset: 0"

#### 2. JScript Example

    //--------------------------------------------------------------------
    // JScript example of the Large Mesh filter implementation for
    // IsApplicable and Match. The plug-in is used for filtering polygon
    // mesh geometries  containing more than 50 points. Note: The
    // IsApplicable function is not required for the filter to work.
    //
    // Copy and paste the example into the script editor and run (F5).
    //
    // The filter will now be listed in the Main Control Panel (MCP)
    // filter list.
    //-------------------------------------------------------------------
    function IsLargeMesh( in_object )
    {
            if ( ClassName(in_object) != "X3DObject") {
                    return;
            }
            return (in_object.ActivePrimitive.Geometry.Points.Count > 50);
    }
    function LargeMesh_Match( in_context )
    {
            return IsLargeMesh(in_context.GetAttribute("Input"));
    }
    function LargeMesh_IsApplicable( in_context )
    {
            var obj = in_context.GetAttribute("Input")
            return (ClassName(obj) == "X3DObject" );
    }
    function LargeMesh_Subset( in_context )
    {
            var coll = XSIFactory.CreateActiveXObject("XSI.Collection");
            var in_objects = in_context.GetAttribute("Input");
            var eObjects = new Enumerator(in_objects);
            for (;!eObjects.atEnd();eObjects.moveNext())
            {
                    var obj = eObjects.item();
                    if (IsLargeMesh(obj))
                    {
                            coll.Add(obj);
                    }
            }
            in_context.SetAttribute("Output", coll);
            return (coll.Count > 0);
    }
    //--------------------------------------------------------------------
    //The Large Mesh filter is registered in Softimage by defining the following
    //entry-point in your plug-in implementation file:
    //--------------------------------------------------------------------
    function XSILoadPlugin( in_reg )
    {
            // register plug-in information
            in_reg.Author = "Softimage Co.";
            in_reg.Name = "Filter Example";
            // register filter plug-in item
            in_reg.RegisterFilter("LargeMesh", siFilter3DObject);
            return true;
    }
    //--------------------------------------------------------------------
    // Code to bootstrap example into system
    //--------------------------------------------------------------------
    function ExampleSourceCode()
    {
            return "// XSISDK Doc Example" + "\n" +
                    IsLargeMesh.toString() + "\n" +
                    LargeMesh_Match.toString() + "\n" +
                    LargeMesh_IsApplicable.toString() + "\n" +
                    LargeMesh_Subset.toString() + "\n" +
                    XSILoadPlugin.toString();
    }
    // if we are running from script editor save code to
    // examples addon folder in the user's directory.
    if (GetUserPref("ScriptingSessionActive"))
    {
            var ex_name     = "ExFilter";
            var ex_subfolder        = "Plugins";
            var ex_folder   = "XSISDKDocExamples";
            var ex_langsuffix       = ".js";
            CreateAddonDirectories( InstallationPath(siUserPath), ex_folder );
            var fso = XSIFactory.CreateActiveXObject("Scripting.FileSystemObject");
            var filename = XSIUtils.BuildPath(
                    InstallationPath(siUserAddonPath),
                    ex_folder,
                    "Application",
                    ex_subfolder,
                    ex_name+ex_langsuffix );
            if (!fso.FileExists(filename))
            {
                    var f = fso.CreateTextFile ( filename );
                    f.write( ExampleSourceCode() );
                    f.close();
                    Application.LoadPlugin(filename);
            }
    }

### See Also

SIFilter SetSelFilter ClusterCollection.Filter X3DObject.FindChild X3DObject.FindChildren siFilterType PluginRegistrar.RegisterFilter ConstructionHistory.Filter ConstructionHistory.Find XSIApplication.Filters Definition Callbacks for Filters