Home   Donators   Contact Us       

<< Previous Tutorial

Tutorial 21 - COLLADA imports
COLLADA is developed by the KHRONOS Group.
www.khronos.org/collada

Theory

Producing exceptional 3D productions and simulations, require that you have access to a variety of 3D assets. You might invest into building your own library of 3D assets using your favorite 3D editor, or decide to make use of 3D assets produced by other designers, artists, engineers and computer scientists.

Building a comprehensive 3D asset library is a very time-consuming task, and it is common practice for 3D communities to share 3D assets commercially or publicly. When you design your 3D production line, you might want to make use of different 3D tool sets, created by different 3D tool makers.

The COLLADA specification provides an industry adopted standard to transport 3D assets between different tool sets, at different stages of your 3D production line. COLLADA makes it super easy to import 3D assets from other 3D environments into your own 3D domain.

So what exactly is COLLADA? COLLADA is a XML specification that stores information about models, materials, scenes, cameras, lights, etc. This information is then transferable between different 3D applications. The specification is designed in such a way to accommodate most of the mainstream 3D development tools. As a starting point to support COLLADA, we will only implement a subset of the COLLADA Release 1.4.1 specification during this tutorial. The portion of the specification that we will be implementing is concerned with the geometric information of models.

The 3D cube model above is described by the COLLADA XML given below.


  
    
      
        <source id="Cube-mesh-positions">
          
		    1 1 -1 1 -1 -1 -1 -1 -1 -1 1 -1 1 1 1 1 -1 1 -1 -1 1 -1 1 1
		  
        </source>
        
          <input semantic="POSITION" source="#Cube-mesh-positions" />
        
        
          <input semantic="VERTEX" source="#Cube-mesh-vertices" offset="0" />
          4 4 4 4 4 4 
          <p>0 1 2 3 4 7 6 5 0 4 5 1 1 5 6 2 2 6 7 3 4 0 3 7</p>
        
      
    
  
  
    
      
        
      
    
  

All the COLLADA information of the cube model is wrapped in the <collada> root node of the XML tree. The two children of the root node, <library_geometries> and <library_visual_scenes>, describe the geometric information and instantiation of the cube respectively.

When we look at the <library_geometries> node it is easy to see that a geometry named "Cube-mesh" is defined. This mesh contains 8 vertices (the 24 float values are the x, y and z dimensions of these vertices), and 6 four-sided polygons created from these vertices. The integer values in the <p> tag are indexes into the vertex array. The values in the <vcount> node indicates that the <p> tag should be interpreted as defining 6 four-sided polygons.

In the <library_visual_scenes> section of the COLLADA, we use the <node> tag, to instantiate a "Cube-mesh" geometry. A highlevel view of the XML is shown below.

The COLLADA information is separated into two major sections, namely <library_geometries> and <library_visual_scenes>. Think of <library_geometries> as the space in which we define what a model looks like, and of <library_visual_scenes> the space in which we give create an instance of the model with specific properties such as position, scale, rotation, etc.

As you can imagine, the example in this tutorial illustrates a tiny fraction of COLLADA's capabilities. We simply defined the geometric information of the cube without taking into account material settings, placement, scale rotation, textures, etc. The complete COLLADA specification provides for a very advanced 3D asset exchange mechanism and we recommend that you have a look at the specification, for more information on how to integrate COLLADA into your 3D production line. The intention of this tutorial is simply to give you an introduction on how to parse COLLADA information.

Tutorial Steps
Tutorial created with Real Studio 2012 Release 1.2.
1. Download and extract the following project base to a new folder:
2. Open the project file with Real Studio.
3. Add the following code to the Action event of cmdImport:
Dim dlg As new OpenDialog
Dim daeFile As FolderItem
Dim models() As R3Model
Dim daeType As New FileType
Dim i As Integer

' configure COLLAD Digital Asset Exchange (*.dae) file type

daeType.Name = "COLLADA Digital Asset Exchange"
daeType.MacType = "DAE"
daeType.MacCreator = "dae"
daeType.Extensions = "dae"

dlg.Filter = daeType

daeFile = dlg.ShowModal()

' did the user select a R3 Model Asset (*.rma) file to open?
if daeFile <> nil then

  ' yes, so let's load the model into our scene, and refresh the OpenGL surface

  ' import the models from the DAE COLLADA file
  models = R3_COLLADA_LoadModels(daeFile)

  if models.Ubound >= 0 then
  
    ' add the models to list
  
    lstModels.DeleteAllRows
  
    for i = 0 to models.Ubound
      lstModels.AddRow "Model " + Str(i + 1)
      lstModels.RowTag(lstModels.LastIndex) = models(i)
    next i 
  
    if lstModels.ListCount > 0 then
      lstModels.ListIndex = 0
    end if

  end if

  OpenGLSurface1.Render ' refresh the OpenGL surface

end if
4. Add the following code to the Action event of cmdSave:
Dim dlg As new SaveAsDialog
Dim rmaFile As FolderItem
Dim rmaType As New FileType

If Scene <> nil then

  If Scene.Model.Ubound >= 0 then
  
    ' configure R3 Model Asset (*.rma) file type
  
    rmaType.Name = "R3 Model Asset"
    rmaType.MacType = "RMA"
    rmaType.MacCreator = "rma"
    rmaType.Extensions = "rma"
  
    dlg.Filter = rmaType
  
    rmaFile = dlg.ShowModal()
  
    ' did the user select a R3 Model Asset (*.rma) file to save?
    if rmaFile <> nil then
	
      if Right(rmaFile.Name, 4 ) <> ".rma" then
        rmaFile.Name = rmaFile.Name + ".rma"
      end if
	
      ' yes, so let's save the model into our scene, and refresh the OpenGL surface
	
      R3_SaveModel(rmaFile, Scene.Model(0))
	
    end if
  
  end if

end if
5. Add the following code to the Action event of cmdOpen:
Dim dlg As new OpenDialog
Dim modFile As FolderItem
Dim model As R3Model
Dim rmaType As New FileType

' configure R3 Model Asset (*.rma) file type

rmaType.Name = "R3 Model Asset"
rmaType.MacType = "RMA"
rmaType.MacCreator = "rma"
rmaType.Extensions = "rma"

dlg.Filter = rmaType

modFile = dlg.ShowModal()

' did the user select a R3 Model Asset (*.rma) file to open?
if modFile <> nil then

  ' yes, so let's load the model into our scene, and refresh the OpenGL surface

  ' first remove all the current models from the scene
  while Scene.Model.Ubound >= 0
    Scene.Model.Remove Scene.Model.Ubound
  wend

  ' load the model from the file
  model = R3_LoadModel(modFile)

  ' add the model to our scene
  Scene.AppendModel model

  OpenGLSurface1.Render ' refresh the OpenGL surface

end if
6. Download and extract the following archive of test DAE files to your project folder:
7. Save and run the project. Import COLLADA models using the "Import..." button. Save and load the models using the RMA format with the "Save..." and "Open..." buttons respectively. Rotate the models with your mouse cursor.
  • 3point.dae - A teapot and an abstract geometric 3D shape.
  • c3logo.dae - The letters "C" and "3D".
  • dirlight.dae - An abstract geometric 3D shape hovering above a plane.
  • ducati.dae - A Ducati motorbike.
  • halli.dae - A 3D model of a house.
  • stair.dae - A sphere and steps hovering above a plane.
Code Analysis

In the cmdImport.Action event we make a call to R3_COLLADA_LoadModels, and store the result in a R3Model array named models. The R3_COLLADA_LoadModels function does the heavy lifting for us by parsing the COLLADA information into our familiar R3Model object format.

During the previous tutorial, Tutorial 20 - File IO, we were introduced to the R3 Model Asset file format, as well as the R3_SaveModel and R3_LoadModel functions. These functions can be used to respectively save and load R3Model objects. When you study the code in the cmdSave.Action and cmdOpen.Action events, you will notice how these two functions are used to convert COLLADA information to the R3 Model Asset file format.

This tutorial introduced you to the COLLADA specification is far from a full COLLADA implementation. It is shown that COLLADA provides an industry adopted standard to exchange 3D assets between different 3D applications, and can make a positive difference to your own 3D production line.

Project Downloads

<< Previous Tutorial


 
All the content on Real 3D Tutorials, with the exception of the SyntaxHighlighter which is licensed under the MIT License, is provided to the public domain and everyone is free to use, modify, republish, sell or give away this work without prior consent from anybody. Content is provided without warranty of any kind. Under no circumstances shall the author(s) or contributor(s) be liable for damages resulting directly or indirectly from the use or non-use of the content.
Should you find the content useful and would like to make a contribution, you can show your support by making a donation.