## X3DObjectCollection.Filter

### Description

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

### C# Syntax

    X3DObjectCollection X3DObjectCollection.Filter( String in_filter, Object in_famArray, String in_path );

### Scripting Syntax

    oReturn = X3DObjectCollection.Filter( [Type], [Families], [Path] );

### Return Value

Collection of X3DObject objects.

### Parameters

Parameter | Type | Description
--- | --- | ---
Type | String | The type of object defined by siType or an empty string if no type is used. The type can be a specific X3DObject type such as siModelType and si3DObjectType or a primitive type such as siPolyMeshType or siSrfMeshPrimType. If a primitive type is supplied, the function considers only the objects defined with a primitive of this type.
Possible Values: | Description:
siPolyMeshType | Polygon Mesh type
si3DObjectType | 3D Object type
siArcPrimType | Implicit Arc Primitive type
siAttractorCtrlType | Attractor Control Object type (electric force)
siCameraPrimType | Camera Primitive type
siCameraRootPrimType | Camera Root primitive type
siChainBonePrimType | Chain Bone Primitive type
siChainEffPrimType | Chain End Effector Primitive type
siChainRootPrimType | Chain Root Primitive type
siCirclePrimType | Implicit Circle Primitive type
siCloudPrimType | Cloud Primitive type
siConePrimType | Cone Primitive type
siCrvListAggregatePrimType | NURBS Curve List Aggregate Primitive type
siCrvListPrimType | NURBS Curve List Primitive type
siCubePrimType | Cube Primitive type
siCylinderPrimType | Cylinder Primitive type
siDiscPrimType | Disc Primitive type
siDodecahedronPrimType | Dodecahedron Primitive type
siDragCtrlPrimType | Drag Control Primitive type
siEddyCtrlPrimType | Eddy Control Primitive type
siFanType | Fan Force Object type
siFurPrimType | Fur Primitive type
siGeoShaderPrimType | GeoShader Primitive Type
siGravityCtrlType | Gravity Force Control Object type
siGridPrimType | Grid Primitive type
siIcosahedronPrimType | Icosahedron Primitive type
siLatticePrimType | Lattice Primitive type
siLightPrimType | Light Primitive type
siModelNullPrimType | Model Null Primitive type
siModelType | 3D Model type
siNullPrimType | Null Primitive type
siOctahedronPrimType | Octahedron Primitive type
siPointCloudPrimType | PointCloud Primitive type
siSpherePrimType | Sphere Primitive type
siSpiralPrimType | Implicit Spiral Primitive type
siSpotInterestPrimType | Spot Interest Primitive type
siSpotRootPrimType | Spot Root Primitive type
siSquarePrimType | Implicit Square Primitive type
siSrfMeshPrimType | NURBS Surface Mesh Primitive type
siTetrahedronPrimType | Tetrahedron Primitive type
siTorusPrimType | Torus Primitive type
siTurbulenceCtrlPrimType | Turbulence Control Primitive type
siVolumeDeformType | Volume Deform type (implicit sphere volume)
siVortexCtrlType | Vortex Control Object type (magnetic force)
siWaveCtrlType | Wave Control Object type
siWindType | Wind Force Object type
Families | siFamily | An array of families defined by siFamily or an empty array if none are required. The families are used for narrowing down the search, the array can contain X3DObject families like si3DObjectFamily or primitive families such as siNurbsSurfaceMeshFamily or siNullPrimitiveFamily. Only the objects that match the supplied families are considered. If primitive families are supplied then only the objects defined with a primitive that belongs to one of them are considered.
Possible Values: | Description:
si3DObjectFamily | 3D Object family
siCameraFamily | Camera family
siChainElementFamily | Chain Element family
siControlObjectFamily | Control Object family
siCurveFamily | Curve Geometry family
siGeometryFamily | Geometry family
siGeometryShaderFamily | Geometry shader family
siImplicitGeometryFamily | Implicit Geometry family
siLatticeFamily | Lattice family
siLightPrimitiveFamily | Light Primitive family
siMeshFamily | Mesh Geometry family
siNullPrimitiveFamily | Null Primitive family
siNurbsCurveListFamily | Nurbs CurveList Geometry family
siNurbsSurfaceMeshFamily | Nurbs Surface Mesh Geometry family
siPointCloudFamily | Point Cloud family
siSurfaceCurveFamily | Surface Curve Geometry family
siSurfaceFamily | Surface Geometry family
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".

### Examples

#### 1. VBScript Example

    'VBScript example
    ' 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"
    set oGeoms = oRoot.findchildren( ,,siGeometryFamily)
    logmessage "The collection of geometry from the root is a " & typename( oGeoms )
    logmessage "There are " & oGeoms.count & " geometry objects under the root."
    logmessage ""
    for each item in oGeoms
            logmessage item.name & " is a " & item.type & " " & typename( item )
    next
    set oNurbFam = oGeoms.filter( ,siNurbsSurfaceMeshFamily )
    set oPolyFam = oGeoms.filter( ,siMeshFamily )
    set oCones = oGeoms.filter( siConePrimType )
    set oCubes = oGeoms.filter( siCubePrimType )
    set oPolyCubes = oGeoms.filter( siCubePrimType, siMeshFamily )
    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 from the root is a X3DObjectCollection"
    'INFO : "There are 4 geometry objects under the root."
    'INFO : ""
    '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: 4"
    'INFO : "       Number of Nurbs objects in collection: 1"
    'INFO : "       Number of Mesh objects in collection: 3"
    'INFO : "       Number of cones in collection: 1"
    'INFO : "       Number of cubes in collection: 2"
    'INFO : "       Number of Mesh cubes in collection: 1"

#### 2. VBScript Example

    'VBScript example
    function create_scene()
            NewScene , false
            set root = ActiveProject.ActiveScene.Root
            call root.AddGeometry( "cone", "meshsurface", "MySuperCone" )
            call root.AddGeometry( "Cylinder", "meshsurface", "MySuperCylinder" )
            call root.AddGeometry( "cone", "nurbssurface", "MyAwesomeCone" )
            call root.AddGeometry( "Torus", "nurbssurface", "MySuperTorus" )
            call root.AddGeometry( "Torus", "meshsurface", "MyAwesomeTorus" )
            call root.AddPrimitive( "cube", "MyImplicitCube" )
            call root.AddNull( "MyAwesomeNull" )
            call root.AddCameraRig( "Camera" )
            set create_scene = root
    end function
    function WriteCollection( in_collection, in_text )
            on error resume next
            LogMessage "-----"
            LogMessage in_text
            size = in_collection.count
            LogMessage "size of collection: " & size
            if size = 0 then
                    exit function
            end if
            for each i in in_collection
                    LogMessage i.type & ":" & i.name
            next
    end function
    set coll = create_scene().children
    arr = Array(siNurbsSurfaceMeshFamily,siNullPrimitiveFamily)
    WriteCollection coll.filter( , ,"*Cone" ), "filter( , ,*Cone )"
    WriteCollection coll.filter( , ,"MyAwesome*" ), "filter( ,,*Awesome* )"
    WriteCollection coll.filter( siConePrimType, arr,"MyAwesome*" ), "filter( Cone, Array(siNurbsSurfaceMeshFamily,siNullPrimitiveFamily), MyAwesome* )"
    WriteCollection coll.filter( siConePrimType, arr ), "filter( Cone, Array(siNurbsSurfaceMeshFamily,siNullPrimitiveFamily) )"
    WriteCollection coll.filter( siConePrimType, siNurbsSurfaceMeshFamily ), "filter( siConePrimType, siNurbsSurfaceMeshFamily )"
    WriteCollection coll.filter( siConePrimType ), "filter( Cone )"
    WriteCollection coll.filter( siTorusPrimType, ,"*Super*" ), "filter( Torus, ,*Super* )"
    WriteCollection coll.filter( , siNurbsSurfaceMeshFamily ), "filter( , siNurbsSurfaceMeshFamily )"
    WriteCollection coll.filter( , siMeshFamily ), "filter( , siMeshFamily )"
    WriteCollection coll.filter( , siMeshFamily,"*Cone" ), "filter( , siMeshFamily, *Cone )"