Filter (MappedItemCollect ion)

Description

Returns a subset of this collection as a new collection of objects matching the filter criteria. If no items are found, Filter returns "Nothing", which allows you to trap errors.

You can set up the filter criteria by using the 'Type', 'Families', and/or 'Path' parameters which roughly correspond to searching by type as outlined in the siType constant, searching by family as outlined in the siFamily constant, or searching by name of the object (see Object Name for more about valid syntax for the Path parameter).

Note: If you combine these parameters, they will narrow the scope of your search, not broaden it. For example, if you specify 'Nurbs Surface Mesh Geometries' (siNurbsSurfaceMeshFamily) for the Families parameter and 'Cone*' for the Path parameter, the return collection will contain any Nurbs cone that was in the original collection, but no Polygon Mesh cones and no Nurbs cubes, spheres, etc.

Scripting Syntax

    MappedItemCollection.Filter( [Type], [Families], [Path] )

Parameters

Parameter | Type | Description
Type | String | siType (for example, "Model", "cube", "torus", etc.). Providing a type argument is equivalent to testing each object with the ProjectItem.IsKindOf method. Default Value: Empty string
Families | siFamily or Array of siFamily values | Specifies the families that objects must belong to. To match the filter, an object must belong to at least one of the specified families. Default Value: Empty Variant
Path | String | An Object Name. This can be a partial name using wildcards. For example, "a*" returns all matches that begin with the character "a". Default Value: Empty string

Return Value

Collection of objects (subset of original collection).

Examples

1. VBScript Example

    '
    '  This example demonstrates how to use the Filter method to separate specific types of
    '  objects out from the rest of the collection by families.

    ' Set up the example using a mesh grid, cube, cone, and a nurbs cube:
    set oRoot = ActiveSceneRoot
    oRoot.AddGeometry "grid", "meshsurface"
    oRoot.AddGeometry "cube", "meshsurface"
    oRoot.AddGeometry "cone", "meshsurface"
    oRoot.AddGeometry "cube", "nurbssurface"

    ' Use the X3DObject.FindChildren method, limited to geometry objects
    set oGeoms = oRoot.FindChildren( , , siGeometryFamily )
    LogMessage "The collection of geometry objects under the root is a " & ClassName( oGeoms )
    LogMessage "There are " & oGeoms.Count & " geometry objects under the root."
    LogMessage ""

    for each geomobj in oGeoms
       LogMessage geomobj.Name & " is a " & geomobj.Type & " " & ClassName( geomobj )
    next

    ' Filtering by family
    set oNurbFam = oGeoms.Filter( , siNurbsSurfaceMeshFamily )
    set oPolyFam = oGeoms.Filter( , siMeshFamily )

    ' Filtering by type
    set oCones = oGeoms.Filter( "cone" )
    set oCubes = oGeoms.Filter( "cube" )

    ' Filtering by both gives you a more narrow hitlist
    set oPolyCubes = oGeoms.Filter( "cube", siMeshFamily )

    ' Now print out the results
    LogMessage ""
    LogMessage "=========================================================================="
    LogMessage " Stats for the collection:"
    LogMessage " ------------------------"
    LogMessage " Total number of objects in collection: " & oGeoms.Count
    LogMessage " Number of Nurbs objects in collection: " & oNurbFam.Count
    LogMessage " Number of Mesh objects in collection: " & oPolyFam.Count
    LogMessage " Number of cones in collection: " & oCones.Count
    LogMessage " Number of cubes in collection: " & oCubes.Count
    LogMessage " Number of Mesh cubes in collection: " & oPolyCubes.Count

    ' Output of above script is:
    'INFO : The collection of geometry objects under the root is a X3DObjectCollection
    'INFO : There are 10 geometry objects under the root.
    'INFO :
    'INFO : MySuperCone is a polymsh X3DObject
    'INFO : MySuperCylinder is a polymsh X3DObject
    'INFO : MyAwesomeCone is a surfmsh X3DObject
    'INFO : MySuperTorus is a surfmsh X3DObject
    'INFO : MyAwesomeTorus is a polymsh X3DObject
    'INFO : MyImplicitCube is a cube X3DObject
    'INFO : grid is a polymsh X3DObject
    'INFO : cube is a polymsh X3DObject
    'INFO : cone is a polymsh X3DObject
    'INFO : cube1 is a surfmsh X3DObject
    'INFO :
    'INFO : ==========================================================================
    'INFO :  Stats for the collection:
    'INFO :  ------------------------
    'INFO :  Total number of objects in collection: 10
    'INFO :  Number of Nurbs objects in collection: 3
    'INFO :  Number of Mesh objects in collection: 6
    'INFO :  Number of cones in collection: 3
    'INFO :  Number of cubes in collection: 3
    'INFO :  Number of Mesh cubes in collection: 1

2. Python Example

    #
    #  This example demonstrates how to use the Filter method to find any owners
    #  who are of a specific family (in this case, the "Groups" family).
    #
    #  It also demonstrates a number of issues related to working with Python in
    #  the SDK, such as how to call commands and methods or properties on global
    #  objects (instrinsic), and how to get around using output arguments.
    #

    # Set up a new scene (Python needs all commands to be treated as methods of the
    # Application object and all global objects to be explicitly named)
    Application.NewScene( "", 0 )

    # Python can't handle the output object, so we use an ISIVTCollection instead
    # when we add a new camera to the scene
    cam3DObj = Application.SIGetPrimCamera( "Camera" )(0)
    Application.LogMessage( "Collection contains these items:" )
    for i in cam3DObj.Owners:
       Application.LogMessage( " - item " + i.Name )

    Application.LogMessage( "------------" )

    # The Family filter criteria will include both groups and cameras
    family_list = [ "Groups", "Camera" ]

    # Get a list of owners for the new camera (but only if they are members
    # of either the "Groups" or "Camera" families
    coll2filter = cam3DObj.Owners.Filter( "", family_list )
    Application.LogMessage( "Filtered collection now contains these items:" )
    for fi in coll2filter:
       Application.LogMessage( "found item " + fi.Name )

    # Output of the above script:
    #INFO : Collection contains these items:
    #INFO :  - item Scene_Root
    #INFO :  - item Layer_Default
    #INFO : ------------
    #INFO : Filtered collection now contains these items:
    #INFO : found item Layer_Default

3. JScript Example

    /* --------------------------------------------------------------

       This example demonstrates how to combine the parameters of
       the Filter method to fine-tune the search criteria

    */
    // Build a new scene with lots of objects to filter and return the scene root
    var child_coll = CreateScene().Children;

    // Using this criterion will match either nulls or srfmesh elements
    families2find = new Array( "Nurbs Surface Mesh Geometries", "Nulls" )

    WriteCollection( child_coll.Filter( "", "","*Cone" ),
       "filter( , ,'*Cone' )", "any item with a name ending in 'Cone'" );

    WriteCollection( child_coll.Filter( "", "","MyAwesome*" ),
       "filter( '', '', '*Awesome*' )", "any item with a name starting with 'MyAwesome'" );

    WriteCollection( child_coll.Filter( "Cone", families2find,"MyAwesome*" ),
       "filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ), 'MyAwesome*' )",
       "any cone with a name starting with 'MyAwesome' that is either a surfmsh or a null" );

    WriteCollection( child_coll.Filter( "Cone", families2find ),
       "filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )",
       "any cone that is either a surfmsh or a null" );

    WriteCollection( child_coll.Filter( "", families2find ),
       "filter( '', Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )",
       "any item that is either a surfmsh or a null"  );

    WriteCollection( child_coll.Filter( "Cone", "Nurbs Surface Mesh Geometries" ),
       "filter( 'Cone', 'Nurbs Surface Mesh Geometries' )",
       "any surfmsh cone"  );

    WriteCollection( child_coll.Filter( "Cone" ),
       "filter( 'Cone' )", "any cone"  );

    WriteCollection( child_coll.Filter( "Torus", "","*Super*" ),
       "filter( 'Torus', '', '*Super*' )",
       "any torus with a name containing 'Super'"  );

    WriteCollection( child_coll.Filter( "", "Nurbs Surface Mesh Geometries" ),
       "filter( '', 'Nurbs Surface Mesh Geometries' )",
       "any surfmsh" );

    WriteCollection( child_coll.Filter( "", "Mesh Geometries" ),
       "filter( '', Mesh Geometries )", "any polymsh"   );

    WriteCollection( child_coll.Filter( "", "Mesh Geometries","*Cone" ),
       "filter( '', 'Mesh Geometries', '*Cone' )",
       "any polymsh item with a name ending in 'Cone'" );

    /* --------------------------------------------------------------

       This function adds the following items to the scene root:

       Name                Primitive Type      Geometry Type
       ---------------     --------------      -------------
       MySuperCone         polymsh             Cone
       MySuperCylinder     polymsh             Cylinder
       MyAwesomeCone       surfmsh             Cone
       MyAwesomeTorus      polymsh             Torus
       MySuperTorus        surfmsh             Torus
       MyImplicitCube      cube                Cube
       MyAwesomeNull       --                  Null
       CameraRoot          --                  CameraRig
       camera1             --                  Camera
       CameraInterest      --                  Null

    */
    function CreateScene()
    {
       NewScene( null, false );

       var root = ActiveProject.ActiveScene.Root;
       root.AddGeometry( "cone", "meshsurface", "MySuperCone" );
       root.AddGeometry( "Cylinder", "meshsurface", "MySuperCylinder" );
       root.AddGeometry( "cone", "nurbssurface", "MyAwesomeCone" );
       root.AddGeometry( "Torus", "nurbssurface", "MySuperTorus" );
       root.AddGeometry( "Torus", "meshsurface", "MyAwesomeTorus" );
       root.AddPrimitive( "cube", "MyImplicitCube" );
       root.AddNull( "MyAwesomeNull" );
       root.AddCameraRig( "Camera" );

       return root;
    }

    /* --------------------------------------------------------------

       This function prints the collection information

    */
    function WriteCollection( in_collection, in_filter_text, in_plain_text )
    {
       // Make sure the script doesn't break
       try {
           LogMessage( "-----" );
           LogMessage( "TEST: " + in_filter_text );
           LogMessage( "      [" + in_plain_text + "]" );
           LogMessage( "Size of collection: " + in_collection.Count );

           for ( var i=0; i<in_collection.Count; i++ ) {
              LogMessage( "\titem #" + (i+1) + ": " + in_collection(i).Name
                  + " (type = " + in_collection(i).Type + ")" );
           }
           return 1;
       } catch(e) {
           LogMessage( "Encountered a problem with the input collection. Quitting..." );
           return 0;
       }
    }

    /* --------------------------------------------------------------

       Output of the above script:

    */
    //INFO : -----
    //INFO : TEST: filter( , ,'*Cone' )
    //INFO :       [any item with a name ending in 'Cone']
    //INFO : Size of collection: 2
    //INFO :  item #1: MySuperCone (type = polymsh)
    //INFO :  item #2: MyAwesomeCone (type = surfmsh)
    //INFO : -----
    //INFO : TEST: filter( '', '', '*Awesome*' )
    //INFO :       [any item with a name starting with 'MyAwesome']
    //INFO : Size of collection: 3
    //INFO :  item #1: MyAwesomeCone (type = surfmsh)
    //INFO :  item #2: MyAwesomeTorus (type = polymsh)
    //INFO :  item #3: MyAwesomeNull (type = null)
    //INFO : -----
    //INFO : TEST: filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ), 'MyAwesome*' )
    //INFO :       [any cone with a name starting with 'MyAwesome' that is either a surfmsh or a null]
    //INFO : Size of collection: 1
    //INFO :  item #1: MyAwesomeCone (type = surfmsh)
    //INFO : -----
    //INFO : TEST: filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )
    //INFO :       [any cone that is either a surfmsh or a null]
    //INFO : Size of collection: 1
    //INFO :  item #1: MyAwesomeCone (type = surfmsh)
    //INFO : -----
    //INFO : TEST: filter( '', Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )
    //INFO :       [any item that is either a surfmsh or a null]
    //INFO : Size of collection: 5
    //INFO :  item #1: Camera_Root (type = CameraRoot)
    //INFO :  item #2: MyAwesomeCone (type = surfmsh)
    //INFO :  item #3: MySuperTorus (type = surfmsh)
    //INFO :  item #4: MyAwesomeNull (type = null)
    //INFO :  item #5: CameraRoot (type = CameraRoot)
    //INFO : -----
    //INFO : TEST: filter( 'Cone', 'Nurbs Surface Mesh Geometries' )
    //INFO :       [any surfmsh cone]
    //INFO : Size of collection: 1
    //INFO :  item #1: MyAwesomeCone (type = surfmsh)
    //INFO : -----
    //INFO : TEST: filter( 'Cone' )
    //INFO :       [any cone]
    //INFO : Size of collection: 2
    //INFO :  item #1: MySuperCone (type = polymsh)
    //INFO :  item #2: MyAwesomeCone (type = surfmsh)
    //INFO : -----
    //INFO : TEST: filter( 'Torus', '', '*Super*' )
    //INFO :       [any torus with a name containing 'Super']
    //INFO : Size of collection: 1
    //INFO :  item #1: MySuperTorus (type = surfmsh)
    //INFO : -----
    //INFO : TEST: filter( '', 'Nurbs Surface Mesh Geometries' )
    //INFO :       [any surfmsh]
    //INFO : Size of collection: 2
    //INFO :  item #1: MyAwesomeCone (type = surfmsh)
    //INFO :  item #2: MySuperTorus (type = surfmsh)
    //INFO : -----
    //INFO : TEST: filter( '', Mesh Geometries )
    //INFO :       [any polymsh]
    //INFO : Size of collection: 3
    //INFO :  item #1: MySuperCone (type = polymsh)
    //INFO :  item #2: MySuperCylinder (type = polymsh)
    //INFO :  item #3: MyAwesomeTorus (type = polymsh)
    //INFO : -----
    //INFO : TEST: filter( '', 'Mesh Geometries', '*Cone' )
    //INFO :       [any polymsh item with a name ending in 'Cone']
    //INFO : Size of collection: 1
    //INFO :  item #1: MySuperCone (type = polymsh)

4. Python Example

    #
    #  This example uses the Path argument of the PropertyCollection.Filter method
    #  to find Properties based on their names.
    #

    # Helper function for displaying contents of a PropertyCollection
    def WriteCollection( in_collection, in_filter_text, in_plain_text ) :
       Application.LogMessage( "-----" )
       Application.LogMessage( "TEST: " + in_filter_text )
       Application.LogMessage( "      [" + in_plain_text + "]" )
       Application.LogMessage( "Size of collection: " + str(in_collection.Count) )

       for oProp in in_collection:
           Application.LogMessage( "\titem #" + ": " + oProp.FullName
              + " (type = " + oProp.Type + ")" )

    # Build a sample scene
    Application.NewScene( "", 0 )
    oModel = Application.ActiveSceneRoot.AddModel( None, "PropModel" )
    oNull = oModel.AddNull( "NullWithProps" )

    # Add a whole lot of properties
    oNull.AddProperty( "CustomProperty", 0, "Prop1" ) ;
    oNull.AddProperty( "CustomProperty", 0, "Prop2" ) ;
    oNull.AddProperty( "CustomProperty", 0, "Prop3" ) ;
    oNull.AddProperty( "CustomProperty", 0, "MyProp" ) ;
    oNull.AddProperty( "CustomProperty", 0, "Other" ) ;
    oNull.AddProperty( "CustomProperty", 0, "PROP4" ) ;

    #
    #  Demonstrate the Filter method:
    #
    # Filtering by Object Name works based on the FullName of the property
    WriteCollection( oNull.Properties.Filter( "","","PropModel.NullWithProps.Prop*" ),
       "Filter(,,\"PropModel.NullWithProps.Prop*\")",
       "All Properties under the Null starting with Prop" ) ;

    WriteCollection( oNull.Properties.Filter( "","","PropModel.NullWithProps.*Prop*" ),
       "Filter(,,\"PropModel.NullWithProps.*Prop*\")",
       "All Properties under the Null containing Prop" ) ;

    # Because the matching is done by the full name, we might accidentally match
    # with other properties because the Model and Null also have "Prop" in their names
    WriteCollection( oNull.Properties.Filter( "","","*Prop*" ),
       "Filter(,,\"*Prop*\")",
       "Properties under the Null with Prop somewhere in the FullName" ) ;

    # Expected Results:
    #INFO : -----
    #INFO : TEST: Filter(,,"PropModel.NullWithProps.Prop*")
    #INFO :       [All Properties under the Null starting with Prop]
    #INFO : Size of collection: 4
    #INFO :  item #: PropModel.NullWithProps.Prop1 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Prop2 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Prop3 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.PROP4 (type = customparamset)
    #INFO : -----
    #INFO : TEST: Filter(,,"PropModel.NullWithProps.*Prop*")
    #INFO :       [All Properties under the Null containing Prop]
    #INFO : Size of collection: 5
    #INFO :  item #: PropModel.NullWithProps.Prop1 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Prop2 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Prop3 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.MyProp (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.PROP4 (type = customparamset)
    #INFO : -----
    #INFO : TEST: Filter(,,"*Prop*")
    #INFO :       [Properties under the Null with Prop somewhere in the FullName]
    #INFO : Size of collection: 7
    #INFO :  item #: PropModel.NullWithProps.Prop1 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Prop2 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Prop3 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.MyProp (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Other (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.PROP4 (type = customparamset)
    #INFO :  item #: PropModel.NullWithProps.Scene_Material (type = material)

Autodesk Softimage v7.5