How to design a new 3D model for the simulator ?

This page explains how to create new objects in the simulated world.

It is divided in two parts :

  • the first one describes mgEngine file formats (for people who would like to write their own object using vi!)
  • the second one shows how to create your own models with Blender. Before reading this tutorial, you must read this page.

An import/export script has been written for Blender ( It allows simulator users to create their own 3D model (objects in environment, robots, sensors, …) using a powerful modeler rather than doing it by hand. This small tutorial aims at giving a small overview of what you can do with this plugin. It is NOT a blender tutorial.

If you want more information on how to use Blender, pleaser refer to Blender tutorial.

mgEngine file formats

Introduction to mgEngine file formats

The simulated world in mgEngine is described by a set of files:

  • Mesh files for geometry of the objects
  • Material files for material properties definition (color, reflection, …)
  • Texture file for texture definition (single/multi channel textures, transparency,…)

This section gives a description of these three kinds of files.

All mgEngine files have a common structure i.e. each file is divided in several sections. Each section begins with a tag between square brackets, e.g.

[this is a section]

Each file format has a set of allowed sections that will be described in the next parts of this document.

Mesh file format

Mesh files are mgEngine's description of 3D models used in the simulated world. A mesh file is written in text (i.e. you can write it with your favorite editor, as long as you have enough time and patience to do it ). Here is a short description (maybe not exhaustive yet) of the mesh file format.

  • The allowed tags in mesh file format are:

* <code>[closed surface]</code> This is a boolean that says if the surface described by the mesh file is closed or not. * <code>[clock wise]</code> Another boolean that says if the triangles and quads are given clock wise or counter clock wise.

  • [nb vertices]

    The number of vertices in the mesh file

  • [material]

    The name of the material file to apply to the mesh.

  • [vertex coordinates]

    Precedes a list of vertices coordinates in 3D x, y and z.

  • [vertex normals]

    Precedes a list of normal vectors in 3D. The normal number n corresponds to the point number n, i.e. there must be as many normals as vertices.

  • [channel ? texture coordinates]

    Precedes a list of texture coordinates for a given channel in 2D u and v (u and v are in [0,1]),one texture coordinate corresponds to a vertex, there must be as many texture coordinates as vertices.

  • [triangles]

    Precedes a list of triangles. Triangle a b c is the triangle made of vertices number a, b and c in this order.

  • [quads]

    Precedes a list of quads. Quad a b c d is a quad made of vertices number a, b, c and d in this order

  • [child]

    It is used to make a composed mesh. If you want to desgin a complex mesh, you will probably need to split it into several sub-meshes. Therefore you need to create a “parent” mesh that declares all his childs using this tag.

  • Example of mesh file : a checker board for camera calibration
[nb vertices]    4
[material]       checker.material
[vertex coordinates]
-0.1485 -0.105  0
0.1485  -0.105  0
0.1485  0.105   0
-0.1485 0.105   0
[channel 1 texture coordinates]
0 0
1 0
1 1
0 1
[quads] 1
0 1 2 3
Material file format

Like mesh files, material files are text files.

  • The allowed tags are :
    • [ambient]
    • [diffuse]
    • [specular]
    • [emission]
    • [shininess]
    • [alpha test]
    • [channel ? texture]
    • [channel ? tex env mode]
    • [channel ? tex gen mode]
    • [channel ? tex gen {S|T|Q|R} vector]
  • Example of material file : material for the checker board
[ambient]       0 0 0 0
[diffuse]       0 0 0 1
[specular]      0 0 0 0
[emission]      1 1 1 1
[channel 1 texture] checker.texture
Texture file format

Texture files are also text files.

  • The allowed tags are :
    • [base file name]

      The name of the texture file(s) without the extension

    • [extension]

      The extension of the texture file(s) including the “.”

    • [components]

      The color components used in texture file(s) (i.e.: RGB or RGBA)

    • [cube]

      Used for sky boxes

  • If your texture has transparency :
    • You should set the tag [components] to
    • You also need two texture files named :
      • base_file_name.extension
      • base_file_name-alpha.extension
    • The last file must be gray level (black is for total transparency and white is opaque).
  • If you want to create a sky box :
    • Set the tag [cube] to :
    • Create *six* files named
      base_file_name-0.extension -> base_file_name-5.extension
  • Example of texture file : texture for the checker board
CheckerBoard Texture file Checkerboard image
[base file name]  checker
[extension]       .jpg
[components]      RGB
Result in mgEngine

Here is the resulting object in mgEngine. It is created using following the mgEngine commands :

mgEngine file Resulting object
new mgMeshActor cb
cb.SetMesh checker.mesh
Resulting object in mgEngine

Creating 3D models using Blender

How to install Blender import/export plugins
  • First, download the blender plugins from mgEngine CVS repository, or used the

Ubuntu package available in download page :

  • If you choose to download the Ubuntu / Fedora package, simply install it.
  • If you choose the download option, copy into the Blender script directory (in Ubuntu, directory is /usr/lib/blender/scripts/)the two following script files :
    • blender/
    • blender/
  • Then run blender. Normally, you should be able to import/export mgengine objets to/from Blender.

^ Blender view at startup ^ Import script in Blender menu ^

Blender view at startup Import script in Blender menu
What can be exported to mgEngine

As not all Blender features are available in mgEngine, only a few of them can be exported.

The supported features are the following :

  • Mesh object
  • Materials and textures
  • Lights
  • Cameras
  • Moving objects
How can I export a 3D model from Blender to mgEngine

Once your object is modeled :

  • Remember to use Blender tutorial if you don't know how to use Blender.
  • To export your file, simply use the menu :
    File > Export > mgEngine Mesh(.mesh)
Do not use spaces in names (e.g. in textures, materials, meshes,…), mgEngine does not allow such file names.
Blender export menu Object to be exported to mgEngine
Blender export menu An object modeled with Blender, to be exported to mgEngine
Exported object in mgEngine
The exported object in mgEngine
How can I import a 3D model from mgEngine to Blender

To import your file, use the menu :

File > Import > mgEngine Mesh(.mesh)

You will see a new windows asking for the path, simply click on search and give the path to the main mesh object. Materials and textures will be loaded automatically.

Blender import menu Imported car from mgEngine mesh file
Blender Import Menu Imported car for mgEngine mesh file
To be continued…
deprecated/howto/devel-model3d.txt · Last modified: 2010/03/03 18:10 (external edit)
Recent changes RSS feed Creative Commons License Donate Minima Template by Wikidesign Driven by DokuWiki