Collada features
| Collada features | Supported by OSG plugin |
| Geometry | Yes |
| VisualScene | Yes |
| Materials | Yes, profile_COMMON |
| Animations | Yes, but writing is incomplete |
| PhysicsScene | No, OSG has no Physics support |
Building the Collada Plugin
The OSG Collada plugin depends on the Open Source Collada DOM library. The current version of the DOM is 2.2. It can build a library for Collada version 1.4 or Collada version 1.5 documents. Both a static and a dynamic library can be build. The osg Collada plugin has only been tested to work with the 1.4 variants of the library. The Collada DOM library itself depends on (a part of) Boost, libxml2, pcre, pcrecpp, minizip, zlib. Precompiled libraries for different platforms and compilers are included in the Collada DOM download from sourceforge. As of December 2011, testing indicates that the plugin still does not work with the COLLADA DOM version 2.3.x, but does work with the 2.2.
In order to build the Collada OSG plugin CMake will try to find the DOM library by using the COLLADA_DIR environment variable. If CMake can not find it specify the COLLADA_DOM_ROOT and reconfigure. The precompiled dependencies used by the DOM will automatically be found and filled in. If only the static library is found CMake will use this and if only the dynamic library is found it will use that library. If both static and dynamic libraries are found it will by default pick the static library. If you switch on the advanced options in CMake you may overrule this setting by manually changing the COLLADA_USE_STATIC option.
Step by step example for Windows and Visual Studio 2005
- Download collada-dom-2.2.zip from Sourceforge
- Unzip it into <yourinstalldir>
- For Visual Studio 2005 open <yourinstalldir>/dom/projects/vc8-1.4/dom.sln and do > Batch Build... > Select all > Build
- Set the environment variable COLLADA_DIR to <yourinstalldir>
- Open CMake > configure > adjust COLLADA_DOM_ROOT if not correct > configure > check other COLLADA_ variables > OK
- Build OpenSceneGraph and the dae plugin
- Running with a statically linked DOM > Make sure the libxml2.dll can be found
- Running with a dynamically linked DOM > Make sure to libcollada14dom21xxx.dll can be found
Step by step example for Linux (likely similar strategy will work on other unices
- Download collada-dom-2.2.zip from Sourceforge
- Unzip it into <yourinstalldir>
- cd <yourinstalldir>
- cp Makefile.linux Makefile
- make os=linux project=minizip
- sudo make os=linux project=dom -C dom/
- sudo make install
Option strings for Collada reader
OSG plugins can be given optional string arguments to influence their behaviour. For the Collada reader one can specify the following option string:
| StrictTransparency | Process transparent and transparency settings according to a strict interpretation of the Collada specification. |
| daeTessellateNone | Do not tessellate at all (Polygons are stored as GL_POLYGON - not suitable for concave polygons) |
| daeTessellatePolygonsAsTriFans | Tessellate the old way (default), interpreting polygons as triangle fans (faster, but does not work for concave polygons) |
| daeTessellatePolygons | Use full tessellation of polygons (slower, works for concave polygons) |
| daeUsePredefinedTextureUnits | Texture units have fixed uses (0: ambient occlusion, 1: main texture...). May create non contiguous units (default). |
| daeUsePredefinedTextureUnits | Texture units are created in sequence (contiguous units)." |
Plugin data for the Collada reader
OSG plugins can be given optional data arguments to influence their behaviour or receive feedback. For the Collada reader one can specify the following PluginData fields
| DAE | A pointer to a previously allocated Collada DOM DAE object- this object will be used to read the dae file and can then be used to programmatically access the loaded DAE database. |
| DAE-DocumentURI | A pointer to a std::string object - This string will be set to the URI of the loaded document on exit |
| DAE-AssetUnitName | A pointer to a std::string object - This string will be set to the AssetUnitName from the Collada document |
| DAE-AssetUnitMeter | A pointer to a float - This will be set to the AssetUnitMeter value from the Collada document |
| DAE-AssetUp_axis | A pointer to a domUpAxisType - This will be set to the AssetUp_Axis from the Collada document |
Option strings for Collada writer
OSG plugins can be given optional string arguments to influence their behaviour. For the Collada writer one can specify the following options strings:
| polygon | Use polygons instead of polylists for element |
| GoogleMode | Write files suitable for use by Google products. (Invert interpretation of A_ONE transparency as Google earth does) |
| NoExtras | Do not write any <extra> elements |
| daeEarthTex | DAE settings for writing earth textures |
| daeZUpAxis | Indicates the up axis is Z instead of Y |
| daeLinkOriginalTexturesNoForce | Writes reference to the original image if found, instead of writing the image in memory |
| daeLinkOriginalTexturesForce | Writes reference to the original image even if not found, instead of writing the image in memory |
| daeNamesUseCodepage | All names except filenames (materials, animation, geometries...) should be considered as encoded using current codepage (UTF8 if not). Filenames follow OSG_USE_UTF8_FILENAME. |
Plugin data for the Collada writer
OSG plugins can be given optional data arguments to influence their behaviour or receive feedback. For the Collada writer one can specify the following PluginData fields
| DAE | A pointer to a previously allocated Collada DOM DAE object- this object will be used to write the dae file and can then be used to programmatically access the loaded DAE database. |
| DAE-DocumentURI | A pointer to a std::string object - This string will be set to the URI of the loaded document on exit |
Example Collada dae models
- Test Model Bank Collection of test models from the Collada project
- Google 3D warehouse Rename the kmz to zip and unzip to find the dae models.
Of course you may also Google for data, but be aware that there are also a lot of invalid Collada files available on the web.
Collada data may be tested for corruption at three levels:
- Well-formedness; conform to the XML syntax rules. Most of the Collada XML data on the web will be well formed, because this is the easiest to catch by tools/parsers.
- Validity; conform to the semantic rules specified in the Collada XML schema.
- Coherency; all element referencing and validation not in the scope of an XML schema. Are all used materials/textures available? Do arrays contain correct data? etc.
To do this you can use the CoherencyTest command-line tool or Java based GUI-tool Collada Refinery
Developer info
A description of the Collada extensions for specific OpenSceneGraph functionality can be found at the OSG Collada extensions page on the Collada wiki.
Tool info
This section should contain information specific to the Collada exporters in various tools and if/how they can export files that the OSG Collada plugin will be able to read. Quirks of the various exporters can be listed here along with workarounds if they exist.
Softimage XSI
The current version of Crosswalk (4.1) includes a Collada 1.4.1 exporter which seems to do a good job of exporting valid Collada files. There are a few quirks:
- You need to check "Export XSI normals" on the ExportCrossWalkOptions - Settings page before exporting, otherwise the models will have no normals.
- The exporter correctly exports Lambert, Phong and Constant materials. Blinn is always exported with a shininess of 0 so it is unusable, use Phong instead.
- There were recent fixes to the OSG Collada plugin to support the way XSI exports animation. Apparently, the animations didn't always contain channels for all X, Y and Z components. OSG SVN as of 2010-03-22 has the fix for this, and animations are read correctly now.
- The hierarchy will be respected:
- Objects will be placed under MatrixTransforms (the object name will be put on the MatrixTransform), so the hierarchy will be MT - Geode - Geometry.
- Objects under other objects will be the same in OSG, so the hierarchy will be MT with 2 children, one Geode - Geometry and the other MT - Geode - Geometry of the child object.
- Nulls become MatrixTransforms too, so an object under a null will become MT - MT - Geode - Geometry.
- You can also create a "Model" node in XSI, these also become MatrixTransforms under which the rest of the model will be.
- For some reason, the name of the material of an object becomes the name of the Geometry in OSG. For example, if I have a sphere called redsphere, with a material called red, this will result in a hierarchy MT("redsphere") - Geode(unnamed) - Geometry("red").
- Animation:
- Animation Sources are exported as separate animations.
- Animation Tracks (as seen in the Animation Mixer) are not exported.
- You can still do some edits to Sources in the mixer, as long as you then freeze the clip by doing Clip - Freeze to New Source or Freeze and Replace before exporting.
- Compounds must also be frozen with Freeze to New Source to work, and if you had transitions in the Compound they will work once frozen to a new Source.
- Using Merge to New Source (with multiple clips selected) is an alternate way to do what a compound would do, but transitions won't have any effect then (even if you also selected the transitions before doing Merge to New Source).
TODO/Wishlist
- Solve differences in drawables, DAE reader should place multiple collation elements into multiple primitivesets in a single geometry where possible (only when same material)
- Solve differences in matrices
- Multitexture support
- Profile_GLSL based on AMD's Collada OpenGL Effects Viewer
- Handling more <extra> to more closely mimic the intended lighting
- Add proper <asset> info
- The OSG Collada plugin doesn't currently read multiple animation cycles from a single dae file. This is under investigation and should be fixed soon.