Welcome to pycollada’s documentation

Source Code

The source code for pycollada lives on github

Tutorial

Introduction

pycollada is a python module for creating, editing and loading COLLADA, which is a COLLAborative Design Activity for establishing an interchange file format for interactive 3D applications.

The library allows you to load a COLLADA file and interact with it as a python object. In addition, it supports creating a collada python object from scratch, as well as in-place editing.

pycollada uses lxml for XML loading, construction, and saving. numpy is used for numerical arrays. Both of these libraries are impleted in C/C++ which makes pycollada quite fast.

pycollada was originally written by Alejandro Conty Estevez of Scopia Visual Interfaces Systems in 2009. Since 2011, the library is now maintained by Jeff Terrace. For a list of additional contributors, see the AUTHORS file included with distribution.

Features

Geometry

• Triangles a set of triangles
• Polylist a set of polygons with no holes
• Polygons a set of polygons that can contain holes (holes unimplemented, currently an alias for Polylist)
• Lines a set of lines

Source Data

• Vertex
• Normals
• Multiple texture coordinate sets

Materials

• Shader types: phong, lambert, blinn, constant
• Effect attributes: emission, ambient, diffuse, specular, shininess, reflective, reflectivity, transparent, transparency
• Texture support: Can read from local file, zip archives, or a custom auxiliary file handler
• Loads texture images with PIL if available

Lights

• Directional
• Ambient
• Point
• Spot

Cameras

• Perspective

Scenes

• Full scene construction
• Transformations: rotate, scale, translate, matrix, lookat (for cameras)
• Supports iterating through a scene, yielding transformed geometry

Controllers

• Currently experimental (more support coming)
• Morph
• Skin

Additional Features

• Fast triangulation of polygons
• Fast computation of normals

Installation

github

The source code for pycollada is available on github here: https://github.com/pycollada/pycollada

To pull a read-only copy, you can clone the repository:

git clone git://github.com/pycollada/pycollada.git pycollada

Python Package Index

pycollada is available as a package at: http://pypi.python.org/pypi/pycollada/

You can also use easy_install:

easy_install pycollada

On Mac OS X, try this if you get an error installing lxml:

export ARCHFLAGS="arch i386 -arch x86_64"
easy_install pycollada

On Ubuntu, install these dependencies first:

apt-get install python-lxml python-numpy python-dateutil
easy_install pycollada

Loading A Collada Document

Collada documents can be loaded with the Collada class:

mesh = Collada('file.dae')

Zip archives are also supported. The archive will be searched for a dae file.

The constructor can also accept a file-like object:

f = open('file.dae')
mesh = Collada(f)

Note that this will also work with the StringIO module. When loading from non-file sources, the aux_file_loader parameter can be passed to the constructor. This is useful if loading from an unusual source, like a database:

dae_file = open('file.dae')
dae_data = dae_file.read()
texture_file = open('texture.jpg')
texture_data = texture_file.read()

def my_aux_loader(filename):
    if filename == 'texture.jpg':
        return texture_data
    return None

mesh = Collada(StringIO(dae_data), aux_file_loader=my_aux_loader)

When using the Collada object (see Collada Object Structure), if you try and read a texture, the my_aux_loader function will be invoked.

Loading a collada document can result in an exception being thrown. For a list of possible exceptions, see Exceptions. Sometimes, you may want to ignore some exceptions and let the loader try to continue loading the file. For example, the following will ignore errors about broken references and features that pycollada doesn’t support:

mesh = Collada('file.dae', ignore=[DaeUnsupportedError, DaeBrokenRefError])

If any errors occurred during the load, you can find them in Collada.errors.

Collada Object Structure

After loading a collada document, all of the information about the file is stored within the Collada object. For example, consider the following code:

>>> from collada import *
>>> mesh = Collada('duck_triangles.dae')
>>> mesh
<Collada geometries=1>

This sample file is located in collada/tests/data of the pycollada distribution. We can now explore the attributes of the Collada class.

Let’s see what Collada.geometries it has:

>>> mesh.geometries
[<Geometry id=LOD3spShape-lib, 1 primitives>]

Each geometry has a number of Source objects that contain raw source data like an array of floats. It then has a number of Primitive objects contained. Let’s inspect them:

>>> geom = mesh.geometries[0]
>>> geom.primitives
[<TriangleSet length=4212>]

In this case, there is only a single primitive contained in the geometry and it’s a set of triangles. The TriangleSet object lets us get at the vertex, normal, and texture coordinate information. There are index properties that index into the source arrays, and the sources are also automatically mapped for you. You can iterate over the triangle set to yield individual Triangle objects:

>>> triset = geom.primitives[0]
>>> trilist = list(triset)
>>> len(trilist)
4212
>>> trilist[0]
<Triangle ([-23.93639946  11.53530025  30.61249924], [-18.72640038  10.1079998   26.6814003 ], [-15.69919968  11.42780018  34.23210144], "blinn3SG")>

The triangle object has the vertex, normal, and texture coordinate data associated with the triangle, as well as the material it references. Iterating over the triangle set is convenient, but it can be slow for large meshes. Instead, you can access the numpy arrays in the set. For example, to get the vertex, normal, and texture coordinate for the first triangle in the set:

>>> triset.vertex[triset.vertex_index][0]
array([[-23.93639946,  11.53530025,  30.61249924],
       [-18.72640038,  10.1079998 ,  26.6814003 ],
       [-15.69919968,  11.42780018,  34.23210144]], dtype=float32)
>>> triset.normal[triset.normal_index][0]
array([[-0.192109  , -0.934569  ,  0.299458  ],
       [-0.06315   , -0.99362302,  0.093407  ],
       [-0.11695   , -0.92131299,  0.37081599]], dtype=float32)
>>> triset.texcoordset[0][triset.texcoord_indexset[0]][0]
array([[ 0.866606  ,  0.39892399],
       [ 0.87138402,  0.39761901],
       [ 0.87415999,  0.398826  ]], dtype=float32)

These are numpy arrays which allows for fast retrieval and computations.

The collada object also has arrays for accessing Camera, Light, Effect, Material, and Scene objects:

>>> mesh.cameras
[<Camera id=cameraShape1>]
>>> mesh.lights
[<DirectionalLight id=directionalLightShape1-lib>]
>>> mesh.effects
[<Effect id=blinn3-fx type=blinn>]
>>> mesh.materials
[<Material id=blinn3 effect=blinn3-fx>]
>>> mesh.scenes
[<Scene id=VisualSceneNode nodes=3>]

A collada scene is a graph that contains nodes. Each node can have transformations and a list of child nodes. A child node can be another node or an instance of a geometry, light, camera, etc. The default scene is contained in the Collada.scene attribute. Let’s take a look:

>>> mesh.scene
<Scene id=VisualSceneNode nodes=3>
>>> mesh.scene.nodes
[<Node transforms=3, children=1>, <Node transforms=4, children=1>, <Node transforms=4, children=1>]

We could write code to iterate through the scene, applying transformations on bound objects, but the Scene object already does this for you via its Scene.objects() method. For example, to find all of the instantiated geometries in a scene and have them bound to a material and transformation:

>>> boundgeoms = list(mesh.scene.objects('geometry'))
>>> boundgeoms
[<BoundGeometry id=LOD3spShape-lib, 1 primitives>]

Notice that we get a BoundGeometry here. We can also pass in light, camera, or controller to get back a BoundLight, BoundCamera, or BoundController, respectively. The bound geometry is very similar to the geometry we looked through above. We can use the iterative method:

>>> boundprims = list(boundgeoms[0].primitives())
>>> boundprims
[<BoundTriangleSet length=4212>]
>>> boundtrilist = list(boundprims[0])
>>> boundtrilist[0]
<Triangle ([-23.93639946 -30.61249924  11.53530025], [-18.72640038 -26.6814003   10.1079998 ], [-15.69919968 -34.23210144  11.42780018], "<Material id=blinn3 effect=blinn3-fx>")>

or by accessing the numpy arrays directly:

>>> boundprims[0].vertex[boundprims[0].vertex_index][0]
array([[-23.93639946, -30.61249924,  11.53530025],
       [-18.72640038, -26.6814003 ,  10.1079998 ],
       [-15.69919968, -34.23210144,  11.42780018]], dtype=float32)

In this case, the triangle is identical to above. This is because the collada duck example only has identity transformations. We can inspect these in the scene:

>>> mesh.scene.nodes[0].transforms
[<RotateTransform (0.0, 0.0, 1.0) angle=0.0>, <RotateTransform (0.0, 1.0, 0.0) angle=0.0>, <RotateTransform (1.0, 0.0, 0.0) angle=0.0>]
>>> mesh.scene.nodes[0].children
[<GeometryNode geometry=LOD3spShape-lib>]

Creating A Collada Object

In this section, we outline how to create a collada document from scratch. First, let’s create an empy collada document:

>>> from collada import *
>>> mesh = Collada()

We could save this out, but it would be completely blank. Let’s first add a Material to the document:

>>> mesh = Collada()
>>> effect = material.Effect("effect0", [], "phong", diffuse=(1,0,0), specular=(0,1,0))
>>> mat = material.Material("material0", "mymaterial", effect)
>>> mesh.effects.append(effect)
>>> mesh.materials.append(mat)

Note that the second argument to Effect is for parameters. These are used for textures. We omit textures for simplicity here.

Next, let’s first create some source arrays. These are going to be used to create a triangle set later:

>>> import numpy
>>> vert_floats = [-50,50,50,50,50,50,-50,-50,50,50,
...     -50,50,-50,50,-50,50,50,-50,-50,-50,-50,50,-50,-50]
>>> normal_floats = [0,0,1,0,0,1,0,0,1,0,0,1,0,1,0,
...     0,1,0,0,1,0,0,1,0,0,-1,0,0,-1,0,0,-1,0,0,-1,0,-1,0,0,
...     -1,0,0,-1,0,0,-1,0,0,1,0,0,1,0,0,1,0,0,1,0,0,0,0,-1,
...     0,0,-1,0,0,-1,0,0,-1]
>>> vert_src = source.FloatSource("cubeverts-array", numpy.array(vert_floats), ('X', 'Y', 'Z'))
>>> normal_src = source.FloatSource("cubenormals-array", numpy.array(normal_floats), ('X', 'Y', 'Z'))

Now that we have some sources, let’s create a Geometry and add the sources to it:

>>> geom = geometry.Geometry(mesh, "geometry0", "mycube", [vert_src, normal_src])

To add a triangle set to the geometry, we can call the Geometry.createTriangleSet() method. To do this, we need to define the inputs to the triangle set. In this case, we are going to input the arrays we previously defined:

>>> input_list = source.InputList()
>>> input_list.addInput(0, 'VERTEX', "#cubeverts-array")
>>> input_list.addInput(1, 'NORMAL', "#cubenormals-array")

This says to use the source with identifier cubeverts-array as the vertex source and source with identifier cubenormals-array as the normal source. The offsets indicate that the vertex data is the first offset in the index array and the normal data is the second offset in the index array. Let’s now create the index array:

>>> indices = numpy.array([0,0,2,1,3,2,0,0,3,2,1,3,0,4,1,5,5,6,0,
...     4,5,6,4,7,6,8,7,9,3,10,6,8,3,10,2,11,0,12,
...     4,13,6,14,0,12,6,14,2,15,3,16,7,17,5,18,3,
...     16,5,18,1,19,5,20,7,21,6,22,5,20,6,22,4,23])

Now that we have an index array, an input list, and a material, we can create a triangle set and add it to the geometry’s list of primitives. We then add it to the list of geometries in the mesh:

>>> triset = geom.createTriangleSet(indices, input_list, "materialref")
>>> geom.primitives.append(triset)
>>> mesh.geometries.append(geom)

We now have everything we need in the object except for a scene. To get the geometry to show up, we have to create a scene. First, we instantiate the geometry into a scene node, mapping it to a material:

>>> matnode = scene.MaterialNode("materialref", mat, inputs=[])
>>> geomnode = scene.GeometryNode(geom, [matnode])
>>> node = scene.Node("node0", children=[geomnode])

Now that we have the scene node, we can create a scene, add the node to the scene, add the scene to the document, and then set our scene as the default:

>>> myscene = scene.Scene("myscene", [node])
>>> mesh.scenes.append(myscene)
>>> mesh.scene = myscene

We can now save the document to a file:

>>> mesh.write('/tmp/test.dae')

If you load this file, it should look like a red cube. Here’s a screenshot:

Changelog

0.4 (2012-07-31)

Backwards Compatibility Notes

• Python 2.5 is no longer supported. Supported versions are now 2.6, 2.7 and 3.2.

New Features

• Added support for reading the opaque attribute from <transparent> tag.
• Normals and texture coordinate indices are now available in shapes (Triangle and Polygon).
• Library is now compatible with python’s built-in ElementTree API instead of requiring lxml. lxml is still recommended.
• Added support for Python 3.2. Supported versions are now 2.6, 2.7 and 3.2.
• Added support for index_of_refraction in <effect>.
• Added optional parameter to Collada that does XML schema validation when saving.
• Automatically corrects broken files that don’t have correct xfov, yfov, and aspect ratio in cameras.

Bug Fixes

• Fix the default value for transparency in Effect. Now correctly defaults to 1.0 when opaque mode is A_ONE, and 0.0 when opaque mode is RGB_ZERO.
• Fixed bug where BoundPolylist was not returning the correct length value.
• Removed support for RGB from Effect since it’s not valid in the spec. If an RGB is given, a fourth A channel is automatically added as 1.0.
• Made instance_geometry not write an empty bind_material if it’s empty since it breaks validation.
• Made saving strip out empty <library_*> tags since it breaks validation.

0.3 (2011-08-31)

Backwards Compatibility Notes

• If using the old Camera object, this has been changed to an abstract class with types for PerspectiveCamera and OrthographicCamera
• If using the old Collada.assetInfo dictionary to read asset information, this has been changed to an object. See documentation for more information.

New Features

• Added support for bump maps inside the extra tag of an effect
• Added texbinormal and textangent to triangle sets
• Added a method to generate texture tangents and binormals
• Added detection for double_sided
• Added an optional parameter to specify what filename inside an archive to use when loading from zip
• Added support for loading multiple sets of library_* nodes
• Refactored asset information into a separate module. Fixed #12
• Refactored Camera into PerspectiveCamera and OrthographicCamera, inheriting from Camera

Bug Fixes

• Changed Collada IndexedLists attributes to be properties. Fixed Issue #14
• Updated scene to use a local scope when nodes are instantiated inside a scene
• Changed parsing to raise DaeMalformedError when an lxml parser exception is thrown
• Fixed bug when loading an <image> tag local to an <effect> not showing up in Collada.images
• Fixed bug when loading an empty <polygons>
• Fixed bug in if statement when loading morph controllers
• Fixed bug when triangulating a length-0 polylist
• Updated install instructions for OS X and Ubuntu problems
• Fixed bugs in IndexedList from Issue #13
• Fixed a bug where using the same map twice in an effect would cause incorrrect output
• Changed geometry export to delete any sources in the vertices tag that no longer exist
• Changed library output to not output emtpy library nodes so validator doesn’t complain
• Add same checks in scene loading that was done in library_nodes loading so that if nodes are not found yet while loading, it will keep trying
• Changed the way library_nodes is loaded so that if a referenced node from instance_node is not loaded yet, it will keep trying
• Fixed bug where a triangles xml node would try to set an attribute to None
• Fixed bug in handling joints that influence 0 vertices

0.2.2 (2011-05-03)

• Changed the way instance_node is handled to actually maintain the mapping so it’s not lost when saving
• Added setdata function to CImage and made Effect compare only image path
• Fixed a bug when rewriting geometry sources
• Change primitive sources to point to the <vertices> tag when possible since other importers don’t like not having a <vertices> tag
• Export source data with only 7 decimal precision for better file size
• Prevent NaN from being the result of a normalize_v3 call
• Fixed bug where effect was not correctly reading all four color values
• Fixed a bug where a triangleset would not create its xml node when generated from a polylist
• Big speed increases for converting numpy data to strings
• Moved getInputs function to Primitive
• Added functions to triangleset to generate normals and get an input list
• Fixed bug in saving a scene node if there was no id
• Fixed some bugs/optimizations with saving
• Added function to test if an Effect is almost equal to another Effect
• Adding dynamic dependencies to setup.py

0.2.1 (2011-04-15)

• Fixed bug with saving existing files that didn’t have some library_ tags.

0.2 (2011-04-15)

• Many bugfixes
• polylist support
• polygons support without holes
• lines support
• blinn and constant material support
• More effect attributes
• Better support for auxiliary texture files
• Lights (directional, ambient, point, spot)
• lookat transform
• Experimental controller support (skin, morph)
• polygons/polylist can be triangulated
• Automatic computation of per-vertex normals

0.1 (2009-02-08)

• Initial release
• Triangles geometry
• Reads vertices and normals
• Multiple texture coordinate channels
• Phong and Lambert Materials
• Texture support using PIL
• Scene suppport for geometry, material and camera instances
• Transforms (matrix, rotate, scale, translate)

Reference

API Summary

Main

collada.Collada	This is the main class used to create and load collada documents
collada.common.DaeObject	This class is the abstract interface to all collada objects.

Asset

collada.asset.Contributor	Defines authoring information for asset management
collada.asset.Asset	Defines asset-management information
collada.asset.UP_AXIS	The up-axis of the collada document.

Geometry

collada.geometry.Geometry	A class containing the data coming from a COLLADA <geometry> tag
collada.primitive.Primitive	Base class for all primitive sets like TriangleSet, LineSet, Polylist, etc.
collada.triangleset.TriangleSet	Class containing the data COLLADA puts in a <triangles> tag, a collection of triangles.
collada.lineset.LineSet	Class containing the data COLLADA puts in a <lines> tag, a collection of lines.
collada.polylist.Polylist	Class containing the data COLLADA puts in a <polylist> tag, a collection of polygons.
collada.polygons.Polygons	Class containing the data COLLADA puts in a <polygons> tag, a collection of polygons that can have holes.

Shapes

collada.triangleset.Triangle	Single triangle representation.
collada.polylist.Polygon	Single polygon representation.
collada.lineset.Line	Single line representation.

Controller

collada.controller.Controller	Base controller class holding data from <controller> tags.
collada.controller.Skin	Class containing data collada holds in the <skin> tag
collada.controller.Morph	Class containing data collada holds in the <morph> tag

Camera

collada.camera.Camera	Base camera class holding data from <camera> tags.
collada.camera.PerspectiveCamera	Perspective camera as defined in COLLADA tag <perspective>.
collada.camera.OrthographicCamera	Orthographic camera as defined in COLLADA tag <orthographic>.

Light

collada.light.Light	Base light class holding data from <light> tags.
collada.light.DirectionalLight	Directional light as defined in COLLADA tag <directional> tag.
collada.light.AmbientLight	Ambient light as defined in COLLADA tag <ambient>.
collada.light.PointLight	Point light as defined in COLLADA tag <point>.
collada.light.SpotLight	Spot light as defined in COLLADA tag <spot>.

Material

collada.material.Material	Class containing data coming from a <material> tag.
collada.material.Effect	Class containing data coming from an <effect> tag.
collada.material.CImage	Class containing data coming from a <image> tag.
collada.material.Surface	Class containing data coming from a <surface> tag.
collada.material.Sampler2D	Class containing data coming from <sampler2D> tag in material.
collada.material.Map	Class containing data coming from <texture> tag inside material.
collada.material.OPAQUE_MODE	The opaque mode of an effect.

Source

collada.source.InputList	Used for defining input sources to a geometry.
collada.source.Source	Abstract class for loading source arrays
collada.source.FloatSource	Contains a source array of floats, as defined in the collada <float_array> inside a <source>.
collada.source.NameSource	Contains a source array of strings, as defined in the collada <Name_array> inside a <source>.
collada.source.IDRefSource	Contains a source array of ID references, as defined in the collada <IDREF_array> inside a <source>.

Scene

collada.scene.Scene	The root object for a scene, as defined in a collada <scene> tag
collada.scene.SceneNode	Abstract base class for all nodes within a scene.
collada.scene.Node	Represents a node object, which is a point on the scene graph, as defined in the collada <node> tag.
collada.scene.NodeNode	Represents a node being instantiated in a scene, as defined in the collada <instande_node> tag.
collada.scene.GeometryNode	Represents a geometry instance in a scene, as defined in the collada <instance_geometry> tag.
collada.scene.ControllerNode	Represents a controller instance in a scene, as defined in the collada <instance_controller> tag.
collada.scene.MaterialNode	Represents a material being instantiated in a scene, as defined in the collada <instance_material> tag.
collada.scene.LightNode	Represents a light being instantiated in a scene, as defined in the collada <instance_light> tag.
collada.scene.CameraNode	Represents a camera being instantiated in a scene, as defined in the collada <instance_camera> tag.
collada.scene.ExtraNode	Represents extra information in a scene, as defined in a collada <extra> tag.
collada.scene.Transform	Base class for all transformation types
collada.scene.TranslateTransform	Contains a translation transformation as defined in the collada <translate> tag.
collada.scene.RotateTransform	Contains a rotation transformation as defined in the collada <rotate> tag.
collada.scene.ScaleTransform	Contains a scale transformation as defined in the collada <scale> tag.
collada.scene.MatrixTransform	Contains a matrix transformation as defined in the collada <matrix> tag.
collada.scene.LookAtTransform	Contains a transformation for aiming a camera as defined in the collada <lookat> tag.

Bound

collada.geometry.BoundGeometry	A geometry bound to a transform matrix and material mapping.
collada.primitive.BoundPrimitive	A collada.primitive.Primitive bound to a transform matrix and material mapping.
collada.triangleset.BoundTriangleSet	A triangle set bound to a transform matrix and materials mapping.
collada.lineset.BoundLineSet	A line set bound to a transform matrix and materials mapping.
collada.polylist.BoundPolylist	A polylist bound to a transform matrix and materials mapping.
collada.polygons.BoundPolygons	Polygons bound to a transform matrix and materials mapping.
collada.camera.BoundCamera	Base class for bound cameras
collada.camera.BoundPerspectiveCamera	Perspective camera bound to a scene with a transform.
collada.camera.BoundOrthographicCamera	Orthographic camera bound to a scene with a transform.
collada.controller.BoundController	Base class for a controller bound to a transform matrix and materials mapping.
collada.controller.BoundMorph	A morph bound to a transform matrix and materials mapping.
collada.controller.BoundSkin	A skin bound to a transform matrix and materials mapping.
collada.controller.BoundSkinPrimitive	A bound skin bound to a primitive.
collada.light.BoundLight	Base class for bound lights
collada.light.BoundAmbientLight	Ambient light bound to a scene with transformation.
collada.light.BoundDirectionalLight	Directional light bound to a scene with transformation.
collada.light.BoundPointLight	Point light bound to a scene with transformation.
collada.light.BoundSpotLight	Spot light bound to a scene with transformation.
collada.primitive.BoundPrimitive	A collada.primitive.Primitive bound to a transform matrix and material mapping.

Exceptions

collada.common.DaeError	General DAE exception.
collada.common.DaeIncompleteError	Raised when needed data for an object isn’t there.
collada.common.DaeBrokenRefError	Raised when a referenced object is not found in the scope.
collada.common.DaeMalformedError	Raised when data is found to be corrupted in some way.
collada.common.DaeUnsupportedError	Raised when some unexpectedly unsupported feature is found.
collada.common.DaeSaveValidationError	Raised when XML validation fails when saving.

Util

collada.util.toUnitVec	Converts the given vector to a unit vector
collada.util.checkSource	Check if a source objects complies with the needed components and has the needed length
collada.util.normalize_v3	Normalize a numpy array of 3 component vectors with shape (N,3)
collada.util.IndexedList	Class that combines a list and a dict into a single class

Modules

collada	Main module for collada (pycollada) package.
collada.camera	Contains objects for representing cameras
collada.common
collada.controller	Contains objects representing controllers.
collada.geometry	Contains objects for representing a geometry.
collada.light	Contains objects for representing lights.
collada.lineset	Module containing classes and functions for the <lines> primitive.
collada.material	Module for material, effect and image loading
collada.polygons	Module containing classes and functions for the <polygons> primitive.
collada.polylist	Module containing classes and functions for the <polylist> primitive.
collada.primitive	Module containing the base class for primitives
collada.scene	This module contains several classes related to the scene graph.
collada.source	Module for managing data sources defined in geometry tags.
collada.triangleset	Module containing classes and functions for the <triangles> primitive.
collada.util	This module contains utility functions

API Reference

collada.asset

Contains COLLADA asset information.

Members

collada.asset.Asset	Defines asset-management information
collada.asset.Contributor	Defines authoring information for asset management
collada.asset.UP_AXIS	The up-axis of the collada document.

Indices and tables

• Index
• Module Index
• Search Page