Xj3D Logo

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:

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

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

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:

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
[ Xj3D Homepage | Xj3D @ Web3d | Download | Screenshots | Dev docs | Dev Releases | Conformance | Contributors | Getting Started | Bug Tracking ]
Last updated: $Date: 2009-06-17 10:33:57 $