S3D exporter for Blender
This page describes a Blender script that allows Blender to be used to preview XVR Procedural Objects. This is useful when you have to deal with complex objects and you want to have a visual cue of the final appearance, without losing the advantages of procedural objects. The exported file is a S3D script file, containing actual XVR code, that must be included and called from your project.
- 1 Installation
- 2 Running the exporter
- 3 Using the exported code
- 4 Supported Objects
- 5 Supported Features
- 6 Future Work
- 7 Bug reports
- 8 Changelog
- 9 See also
The Blender Python API is constantly evolving, so it is advisable to version-match the script in order to avoid unexpected failures. The current version of the script has been written and tested against Blender version 2.43.
The availability of a full Python install is not required.
Getting the exporter
The exporter is a Python script. You can download it from here.
Installing the exporter
To install the exporter, just drop it in the scripts directory, which is usually placed in
C:\Program Files\Blender Foundation\Blender\.blender\scripts unless you decided to install it in your home, in which case you should find the
.blender directory among your documents.
Alternatively, in Blender, go to the
File Paths tab, in the
User Preferences window, and select a custom additional script directory in the
Python text field. After saving your User Preferences (from the
File menu or pressing
CTRL+U), it is advisable to reload the program.
Afterwards, the S3D exporter should be available in the
File > Export menu.
Running the exporter
If correctly installed, you can find the script in the usual
File > Export menu.
The operation is pretty straightforward. The exporter operates only on selected meshes and does not require any options.
Please note that the exporter won't allow any file overwrite. This is a deliberate design choice: overwriting code files is just too risky, even though a safe programmer should protect his efforts with backups and code versioning.
Using the exported code
In the main script, add:
where <name> of course represents the name of the exported file. In OnInit call:
In OnFrame call:
(of course inside a SceneBegin()/SceneEnd() block). In general proc_<name> is the name of the root object of the procedural hierarchy. You can call all the usual CVmObj methods on it. Remember to download any additional file that you need - that is, textures needed by the exported objects.
Of course not every object can be accurately described as an XVR procedural object. Procedural objects are usually simple primitives combined in possibly complex ways.
To recognize which shape to use in XVR, we followed a pretty simple approach: we look at names and only at names. If an object's name starts with a particular string, than it is a particular type of object. Other object properties are looked up as well, in particular position, rotation, scale; also materials and modifiers may be looked up if available.
Please note that the actual geometry of the object is ignored; only the number of vertex is sometimes looked up to infer how many segments to employ.
Currently supported objects are:
- please note that the default Blender cylinder has its pivot in the middle, why XVR places it at the bottom; take care of this
- there is no Blender Arch primitive, but a renamed cube can be used instead as its bounding box; please note, though, that XVR's Arch has its pivot in the front
More objects will be added in the future. In particular, with Blender 2.44, we will take advantage of the new Python slot in the "Add Mesh" menu, so that we can create all XVR primitives matching XVR pivots and parameters directly into Blender.
The recently added Array modifier comes in handy when dealing with procedural objects. With it, a base mesh can get replicated a number of time in a regular fashion. This exporter supports all three types of displacements, including the incredibly useful "Object" displacement type, that allows not only to translate but also to rotate and scale. Interestingly enough, an Array Modifier becomes a loop in S3D code.
Unfortunately, due to limitations in the Python API, it's not possible to read the current states of the toggle, so take care of zeroing out all of the fields that you don't need. Length limit, curve follow, and vertex merge are not supported. Bear in mind that this modifier acts on a mesh in Blender, while it acts on objects in XVR.
There's basic support for materials too.
If an object has a materials and has an image assigned to its faces, that's the texture that gets exported and forced onto the XVR object. No other parameter is taken into account.
Textures with UV tiling parameters
If an object has a material with a texture in the first slot, the image name is read from there, and the SizeX/SizeY parameters are exported as U_TILING, V_TILING parameters in XVR. No other parameter is taken into account.
As stated in section Supported Objects, we plan to take advantage of the new Python slot in the "Add Mesh" menu that will be available in Blender 2.44, in order to create all XVR primitives matching XVR pivots and parameters directly into Blender.
Please post bug reports in the XVR user forums.
- support for cube, plane, sphere, cylinder and arch
- support for array modifier
- basic materials support