Xj3D Filter Chain
Xj3D contains a powerful content transformation engine that utilizes the significant
code amassed over the years by the Xj3D project to process X3D files.
Table of Contents
Overview
Filter: Transforms an X3D stream into another X3D stream. Uses the X3D Abstract Functional
Specifcation as its backing data model.
Chain: Sequence of filters executed in order. No branching capability.
Philosophy: Small purpose built filters to solve specific jobs. Favor small filters
used in a chain instead of a single large filter.
Sample Use Cases:
- Optimization - Make content run faster, use less memory etc.
- ShortenDEF - Shorten DEF Names
- DEFUSEImageTexture - Insure textures are DEF/USEd
- FlattenTransforms - Bake transformations into geometry
- CombineShapes - Combine shapes into one
- CombineAppearance - Combine all shapes of an appearance
- Device/Application Targeting - Change profile or node types for a specific device or application
- Profile Reduction: Immersive to Interchange
- Geometry Type Transformation: IndexedFaceSet to IndexedTriangleSet
- Content Validators - Determine if content follows the requirements
- Manifold - Determine if an object is a watertight, 2-manifold mesh
- Project Requirements - Insure content meets project specific requirements
- Geometry Type Transformation - Change the type of the geometry
- Triangulation - Transform non triangle types like Box, Extrusion, etc into triangles
- Index - Convert non indexed geometries(TriangleSet...) into indexed(IndexedTriangleSet)
Running Filters
The installation of Xj3D creates a converter.bat or converter.sh file. This file can be
used to run a filter chain. If you want to run the filters in an application then look
at how these batch files execute the application in apps/cadfilter.
Parameters
CDFFilter - usage: filter [filters] input output [-loglevel type]
[-exportVersion n] [-compressionMethod n ] [-quantization n ] [-upgrade]
[filter_args]
-loglevel type [ALL|WARNINGS|ERRORS|FATAL|NONE]
The minimum level that logs should be written at
-exportVersion n.n
The exported version of the X3D specification to generate
No error checking is performed for invalid version numbers
Assumes 3.1 if not supplied
-compressionMethod [FASTEST|SMALLEST|LOSSY|STRINGS]
Define what sort of compression algorithms should be used
when X3D Binary format is used for the output. Ignored in
all other cases
-quantization n
Positive floating point value that states how much quantization
of values is allowed. Default is 0.001
-upgrade
When declared, any VRML style PROTO content that can be
upgraded to X3D native nodes, will be
Examples
converter.sh Identity foo.x3d foo.x3dv
Changes X3D encodings from XML to VRML Classic Encoding. The Identity transformation does not change the content.
converter.bat Triangulation Index FlattenTransform foo.x3d bar.x3d
Reduces complex geometry to triangles, indexes those triangles and flattens all transforms.
converter.bat AbsScale foo.x3d bar.x3d -scale 0.1
Scales the geometry to 1/10th of its original size. The -scale parameter is
passed to all filters.
converter.sh Identity foo.dae foo.x3d
Converts a COLLADA file to an X3D file.
converter.sh TriangleCountInfo foo.dae NULL
Runs an info filter with no output.
Current Filters
AbsScale
Scale a files Coordinate nodes.
Sample Usage
filter Triangulate AbsScale foo.x3d bar.x3d -scale 0.1
Parameters
Scale - Factor to multiply each coordinate.
Restrictions
Only scales Coordinate nodes. Any geometry that does not use a Coordinate
node is not scaled. Use the Triangulation filter to convert more complex
geometry to triangles. Does not scale anything else like transforms, viewpoints.
AppearanceFilter
Add an appearance node to any Shape that doesn't contain one.
Sample Usage
filter AppearanceFilter foo.x3d bar.x3d -appAndMat -diffuse 1 0 0
Parameters
- appAndMat - Adds a material node as well
- diffuse - Specifies the diffuse color to use if a material is added, default to 0.8 0.8 0.8
Restrictions
None
Center
Processes each geometry item and centers it in it's local coordinate system
based on the bounds of the coordinates.
Sample Usage
filter Triangulate Center foo.x3d bar.x3d
Parameters
None
Restrictions
Only works for geometry nodes that have Coordinate nodes.
CombineAppearances
Combine multiple Shapes into a single Shape node per unique Appearance.
Sample Usage
filter CombineAppearance foo.x3d bar.x3d
Parameters
None
Restrictions
The input to this filter is presumed to have been run through
the FlattenTransformFilter. Input must have the Shape nodes as
the root nodes of the Scene, otherwise they will be ignored.
At present, only IndexedTriangle* are combined and output.
Not supported
Light associations are lost
Grouping nodes associations are list(Switch, LOD, etc)
Shaders not supported
LocalFog associations are lost
Ignores EXPORTS
Combining textured objects, needs texture coordinate logic, coordinates lost currently
CombineShapes
Combines multiple Shapes into a single Shape node.
Sample Usage
filter FlattenTransform CombineShapes foo.x3d bar.x3d
Parameters
None
Restrictions
The input to this filter is presumed to have been run through
the FlattenTransformFilter. Input must have the Shape nodes as
the root nodes of the Scene, otherwise they will be ignored.
At present, only IndexedTriangleSets, IndexedTriangleStripSet and IndexedTriangleFanSet
are combined and output.
Only supports one appearance.
DEFUSEImageTexture
Finds duplicate url references in ImageTextures and DEF/USE them
This version is 1 pass, so it must DEF all ImageTextures in the
scene.
Sample Usage
filter DEFUSEImageTexture foo.x3d bar.x3d
Parameters
None
Restrictions
Metadata on ImageTextures will be lost. We would need a node buffering strategy to fix this.
Assumes that urls with the first entry the same are equal.
Debug
A debug filter that prints out everything that passes through it and then
passes the information onwards to the next in the chain.
Sample Usage
filter Triangulation Debug Index foo.x3d bar.x3d
Parameters
None
Restrictions
None
FlattenTransform
Filter for removing transform hierarchies. The transformational
components of the Transforms are combined and the coordinates of
the children nodes are transformed to retain the information. The
end result is a file containg geometry (Shape nodes) without the
grouping node.
Sample Usage
filter Triangulation FlattenTransform foo.x3d bar.x3d
Parameters
None
Restrictions
IndexedTriangleSet, IndexedTriangleStripSet,
IndexedTriangleFanSet, and Viewpoint nodes are transformed and
output.
GenNormals
Generates normals if none are specified.
Sample Usage
filter GenNormals foo.x3d bar.x3d
Parameters
None
Restrictions
IndexedTriangleSet, IndexedTriangleStripSet, IndexedTriangleFanSet are supported.
Identity
Sample Usage
filter MinProfile foo.x3d bar.x3d
Parameters
None
Restrictions
Index
A filter which leaves the stream untouched.
Sample Usage
filter Identity foo.x3d bar.x3d
Parameters
None
Restrictions
None
IFSFilter
Converts a IndexedTriangleSet, IndexedTriangleFanSet, or
IndexedTriangleStripSet to a IndexedFaceSet.
Sample Usage
filter Triangulation Index IFSFilter foo.x3d bar.x3d
Parameters
None
Restrictions
Only support changing Indexed(TriangleSet, FanSet, StripSet) geometry. Use the Triangulation and Index filter if you want to
support other geometry types.
MinProfile
Label content with the minimum Profile and Component statement possible. Prefers
a profile to a long string of components.
Sample Usage
filter MinProfile foo.x3d bar.x3d
Parameters
None
Restrictions
Full profile is not supported in Xj3D so it cannot load Full profile files.
Only works on nodes, does not detect language features like PROTO that raise
the profile requirement.
ModifyViewpoint
A filter which changes the position and orientation of a viewpoint.
Sample Usage
filter ModifyViewpoint foo.x3d bar.x3d
Parameters
- type - The type of viewpoint to change. Either DEFAULT which is the X3D default or one DEFed ICON_VIEWPOINT.
- location - Specifies the positon field data for the viewpoint
- orientation - Specifies the orientation field data for the viewpoint
Restrictions
ReIndex
Filter for reducing IndexedTriangleSet, IndexedTriangleStripSet,
IndexedTriangleFanSet and IndexLineSet nodes to their most compact form.
This filter will remove duplicate coordinates from the coordinate point
array and recreate the index array to coorespond to the modified coordinate
points.
Sample Usage
filter ReIndex foo.x3d bar.x3d
Parameters
None
Restrictions
Handling of color, normal and texCoord fields of the indexed
geometry node set is not supported. If the coordinate array is already in
it's most reduced form (i.e. it is passed through unmodified), then the
color, normal and texCoord fields will be pass through unmodifed as well.
If the coordinate and index arrays are changed, the color, normal and
texCoord fields are dropped.
ShortenDEF
Sample Usage
filter MinProfile foo.x3d bar.x3d
Parameters
None
Restrictions
Triangulation
Converts geometry nodes into triangles.
Sample Usage
filter Index Triangulation foo.x3d bar.x3d
Parameters
None
Restrictions
The following geometry nodes are supported:
- IndexedFaceSet - Issues with non polygons
- Box
- Cone
- Cylinder
- ElevationGrid
- Extrusion - Issues with endcaps
TriangleCountInfo
Counts the number of triangles.
Sample Usage
filter Triangulation TriangleCountInfo foo.x3d
Parameters
None
Restrictions
Must be a Triangle* node. Use the Triangulation filter to down convert.
Input Formats
The filter implementation includes several file readers. The following formats
are supported:
AC3D, COLLADA, STL, VRML, X3D
Output Formats
The filter implementation includes several file writers. The following formats
are supported:
STL,VRML,X3D
If the second file parameter is NULL then the results will not be output. This
is useful for informational filters like the TriangleCountInfo.
Professional Training
Yumetech offers training on X3D and how to use Xj3D in your
application. Details available at: Yumetech Training
