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.
ClipCollection ClipCollection.Filter( String in_filter, Object in_famArray, String in_path ); |
oReturn = ClipCollection.Filter( [Type], [Families], [Path] ); |
Collection of objects (subset of original collection).
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 |
' ' 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 |
# # 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 |
/* -------------------------------------------------------------- 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) |
# # 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) |