User Tools

Site Tools


Sidebar

Navigation

projects:colladaloader

ColladaLoader

The colladaLoader is a java import library to view Google Sketchup files (dae and kmz) inside a Processing IDE

What are the features?

  • supports shapes, colors and transpareny
  • supports textures
  • supports multiple models (new)
  • built in transform functions such as scale, rotate or translation
  • save as a new dat file (new)
  • tested for big files
  • bugfixed (tested in Ubuntu natty 64 + 32, Windows 7)

What are the needs?

  • Processing 2.0
  • freeware version of Google Sketchup version 8

The importer is tested with latest Sketchup release 8.0.16846 12/19/2012

Please note that:

  • It supports no groups
  • It supports no repetive textures
  • No support for files which have been created in previous Sketchup versions

(To handle it read instructions further down)

Download where?

Install it as plugin with Library Manager: Choose menubar "Sketch" → "Import Library…" → "Add Library…" then search for "Collada Loader"

Or get latest versionhere as zip

Older library versions won't work with Processing version 2.0 so they're removed from net.

For more details take also a look to my forum

Step 1: Prepare an existing model

  • Save any existing older .skp files into version 8 and restart Sketchup (older files contain another XML-tree)
  • Remove all groups in your model:
    • Zoom back press CTRL+A then mouse rightclick and choose "explode" (Fig 1).
    • Save and re-open the model
  • Enshure of unique textures:
    • Do mouse rightclick on each faces which have textures applied
    • Then and choose "Make Unique Texture" (Fig 2)

Fig 1: ColladaLoader throws Java Exceptions if you don't ungroup the entire model or you try to load old kmz / dae versions.

Fig 2: Processing produces blurred graphics on the sketch if you don't apply that step. This menu item is not available if SketchUp already considers the texture to be 'unique'.In this example: Susan contains no textures but the wall does.

Zoom

Step 2: Export as kmz or dae

Considering the rules of Sketchupversion groups and textures, export the model into Processing now:

  • Choose in Sketchup "File" → "Export" → "3D-Model"
  • save it as kmz or dae into Processing "data" path

Step 3: Run Processing

The examples folder contain a demo.pde which shows the usage of the library. The very basics to run ColladaLoader is adding the following code into Processing sketch:

class header
  • define an attribute e.g.
    ColladaLoader model2;
setup() section
  • define a sketch size with OpenGL e.g.
    size(500, 500, OPENGL);
  • instantiate the model with filename and current sketch instance e.g.
    model2 = new ColladaLoader("susan.kmz",this);
  • You 're able to instantiate more than one model. ColladaLoader loads in different ways so there exist 3 reserved file suffixes for it:
    • ".kmz" and ".dae" = sketchup models
    • ".dat" = serialized (saved) ColladaLoader objects.
draw() section
  • add the draw method e.g.
    model2.draw();

Take a note that Processing zero points start not in the middle of the sketch and some translations may be nessessary before drawing.

Troubleshooting

The loading or drawing of 3D models claim lots of CPU time and RAM. That may produce several runtime problems. It can be assumed that the model has been loaded into memory correctly (consistent data) if no explicit "ColladaLoaderException" occurs. There is some ways to improve the performance:

  • download latest stable Processing version
  • set a low framerate (10 per second or less) in setup() section
  • add noloop() method into setup() section and call loop() later (e.g. over a keyPressed event)
  • Increase memory size: choose "File" → "Preferences" → "avaiable memory"
  • For Mac 64 users: the previous library version throwed ColladaLoaderExceptions. It has been fixed by re-compiling the sources on the same platform. Use the Ant script for it.
  • Be shure that the model contains at least one triangle AND one line
  • Use the OpenGL Adapter for Processing (see also)

Interface usage

Class ColladaLoader

The class cooladaLoader.ColladaLoader is the entry class and defines the interface too. Whose methods support all the features what is mentioned on the top of this doc. The required data to display the model is wrapped into two arrays which resides in this class:

  • Triangle[]
  • Line[]

The coordinate system and color range of Sketchup is converted into Processing specifications. Following a method/constructor list:

ColladaLoader
ColladaLoader(String,PApplet)Standart constructor to load the model The String defines a file located in the data path. Files only can end with following suffixes:
".dae" or ".kmz" = Sketchup 8 files
".dat" = serialized objects created by ColladaLoader

PApplet defines the current sketch. Colladaloader uses some of its convenient methods internally.

Instantiating more than one model is valid.
void draw()a convenient automatism to draw the model. Note that any model data changes at runtime is displayed immediately.
Triangle[] getTriangles()
Line[] getLines()
Getter methods to access model data
void shift(float, char)translates the model. The changes won't be reseted at runtime

the float defines the length in pixels
the char defines the 3D axis. Valid chars are: 'x', 'y', 'z'
void rotate(float, char)rotates the model. The changes won't be reseted at runtime

the float defines the angle in radiant
the char defines the rotating axis. Valid chars are: 'x', 'y', 'z'
void scale(float)resizes the model. The changes won't be reseted at runtime

the float defines the scalefactor. 0.5f makes smaller, 2.0f makes bigger
void save(String)creates a serializable object and saves the current condition of the model at runtime to a new file in data path

String defines the filename and must end with ".dat"
Class Triangle and Lines

Those classes wrapp all required data to display the model. Each object contains data for one entity. It correlate to coordinates and texture formates of Processing and supports read/write access. Here is a list of properies:

Triangle
Point3D A, B, CVertex coordinates: Each Point3D contains 3 floats (x, y, z)

Example for r/w access: "myTriangle.A.x"
Point2D texA, texB, texCImage coordinates for each vertex: Each Point2D contains 2 floats (x, y). If no texture exist for this shape the value is null

Example for r/w access: "myTriangle.texA.x"
Color colour Defines the color of this shape. It contains 4 floats: red, green, blue, transparency. If any texture exist for this shape the value is null

Example for r/w access: "myTriangle.colour.red"
boolean containsTexture Defines the draw handling. The value is true if any texture exist for this entity. Don't overwrite it.
String imageFileNameThe name of the texture. Don't overwrite it
PImage imageReferenceIs used from Processing to draw the texture. Don't overwrite it.
Line
Point3D A, BVertex coordinates: Each Point3D contains 3 floats: x, y, z

Example for r/w access: "myLine.A.x"
Color colourDefines the color of this shape. It contains 4 floats: red, green, blue, transparency.

Example for r/w access: "myLine.colour.red"

References

Appendix: Detailed specifications

A1 Architecture overview

There exist 3 fundamental jobs for the entire architecture what must be done:

  • Parsing the XML tree from a .dae file into proper java objects
  • Interpreting and completing model data from java objects
  • Implementing of the interface functions such as transformations or I/O management

The parsing operates with the DOM model and is located in package xmlMapping. At first the XML tree is loaded into memory by Processing API. As next step it follows a readout of each xml tag. For that purpose wrappers are created whose classnames are equal to xml tag names. Whose constructors read xml data or instantiate further wrappers. The order of instantiating those wrappers is important because some wrapper objects are linked to each other. Hence, such objects already must exist or be parsed, respectively. For this controlling there exist the class ColladaRAWLoader. It's the package entry class and contains a main method to test this subpackage separately as well.

The output from ColladaRawLoader class contain data which is based on Sketchup specifications such as coordinate system or color ranges and must be converted to Processing specifications. Furthermore, the data still don't include textues but just filenames of them which files have to be loaded before, and kmz files must be unzipped first. These are jobs that the class LoadingHelper does. It's located in the parent package (cooladaloader). The interface ColladaLoader makes use of it.

A2 Collada XML Spec

The xml structure of a .dae files applies the specifications of collada.org. Whose interface definitions permit lots of combinations of xml tags so it's possible that other 3D programms (e.g. cinema4d), if they export collada likewise, define another xml tree or data. Actually, those definitions diverge from sketchup version to version too. Thats why the ColladaLoader library works on Sketchup version 8 (release dec 2012) only.

Fig 4: On the one hand, the xml tree is a static structure on the other hand there exist dependencies of data what the xml tags or child tags contain. Those two facts must be considered in order to map those data into java objects. To get the point in this case: The order in reading the tags start from bottom up.

Fig 5: This example is a detailed view of xml data what contain one triangle. Vertice coordinate or texture-points are stored here. The <p> tag is a subtag of <lines> or <triangles> and contain indices they link to an index position of a <float_array> tag

In this example the Offset 1 is allocated to textures and the vertices have offset 0. After parsing we get following results:

Vertice:
Point A:x=26.2341y=189.0905z=0.0
Point B:x=26.2341y=83.5787z=0.0
Point C:x=95.1952y=83.5787z=0.0
Textures for:
Point A:x=0.9988y=0.0008
Point B:x=0.0012y=0.0008
Point C:x=0.0012y=0.9991

The <lines> tag construction is simillar. An <accessor> tag says how to read a <float_array> tag.

For further details refer to javaDoc or code comments in each classes.

projects/colladaloader.txt · Last modified: 2013-08-04T18:36+0200 by tazimmer