3D modeling
From CSP
| Table of contents |
Overview
This is an evolving set of guidelines for building 3D models used by CSP. Consider this a proposal, not an official policy. Please feel free to make suggestions and comments either at the bottom of this page or in the CSP development forum.
Formats
OSG is able to import a number of common 3D formats: OpenFlight (.flt), TerraPage (.txp), LightWave (.lwo), Alias Wavefront (.obj), Carbon Graphics GEO (.geo), 3D Studio MAX (.3ds), Peformer (.pfb), Quake Character Models (.md2), Direct X (.x), Inventor Ascii 2.0 (.iv)/ VRML 1.0 (.wrl), Designer Workshop (.dw), AC3D (.ac) and the native .osg and .ive formats. So far we have primarily used .3ds models, although as yet there is no official format recommendation or requirement. Note that the import plugins for poorly documented, and that proprietary formats (such as 3ds) occasionally lack support for important features (such as key frames in 3ds). Furthermore, proprietary formats such as 3ds tend to require expensive modeling programs. Ultimately, for internal use we will likely end up using the native binary format of OSG (.ive). Ideally, more capable converters and export plugins for this format will soon be developed independently of CSP, since robust format conversion is a common requirement of many open-source applications using OSG.
As of mid-2005, [osgExp (http://osgexp.vr-c.dk/)] does a reasonable job of exporting native .osg format files from 3dsmax. There is also an [export plugin (http://projects.blender.org/projects/osgexport/)] for Blender. The recommended approach is to use the native format of your modeling software for the development work. Models checked into the repository for use in CSP should first be exported to .osg format.
Coordinates
Scale
CSP uses metric units, so models should be dimensioned in meters.
The scale is set in the following two places for 3D studio Max version 4:
- Under Customize / Preference / General System unit scale: 1 unit = 1.0 meter
- Under Customize / Unit Setup: select Metric, meters
The scale is set in the following place for 3D studio Max version 5:
- Under Customize / Unit Setup: select Metric, meters
- Unit system setup: 1 unit = 1.0 meter
Axes
The `Y` axis points forward, i.e. in the primary direction of motion for the vehicle. The `Z` axis points up, from the bottom toward the top of the vehicle. The `X` axis is chosen to form a right-handed coordinate system. Generally the `X` axis will point from the left side toward the right side of the vehicle, from the perspective of someone looking forward (and upright).
Note that this coordinate system differs from the the standard axes used in aerodynamics literature (the `X` and `Y` axes are swapped and the `Z` axis reversed).
Origin
In general, the model origin should be chosen as close to the center of gravity as possible. For animated subcomponents, the local origin will correspond to the center of motion ("pivot point"). See below for more details on animation.
LOD
Levels of detail (LOD) are handled in a very simple way by OSG. Each model has a root LOD node that has one child graph for each detail level. Only one child graph of the LOD node is rendered, based on the distance from the model to the camera (although eventually we will also account for field of view). The simplest way to enable LOD support for a model is to provide separate models for each detail level, along with a distance threshold for each level assuming a 60 deg field of view. A standalone tool can then combine the models under a single LOD node for use in CSP. As a rough rule of thumb, the triangle count should vary by a factor of 5 between successive LOD.
As of mid-2005 we are not yet actively using LOD for 3D models in CSP. For now models should be generated at moderately high detail (e.g. 10-30k triangles for an aircraft, excluding the cockpit).
Extra Information
Some metadata needs to be supplied with the model. The full list of metadata has not yet been determined, but here are some of the necessary items:
- View point(s): reference coordinates of the viewpoint(s) for operators of the vehicle.
- Contact points: coordinates of extrema of the model used for rough collision detection. The points should be chosen such that if the model is resting on them against a flat surface, no significant part of the model will penetrate that surface. So for an aircraft, one would choose the wingtips, the nose, the top of the vertical stabilizer, etc. A dozen or so points should be sufficient in most cases. Definitely try to limit the contact points to less than 30.
- Landing gear positions, displacement vectors, and compression limits. The positions are for the bottom of the wheels assuming zero compression. Many other parameters related to gear function must be specified, but these few will allow for basic functionality.
- Animations (see below).
All metadata is specified externally in xml files. Every model has at least one associated xml file. For example, the model file for the Mirage 2000 is [here (https://www.zerobar.net/viewcvs/viewcvs.cgi/trunk/csp/data/xml/vehicles/aircraft/m2k/model.xml?view=markup)].
Animation
The infrastructure for animations is still evolving. The original approach required manual definitions of the animation transformations in xml, while the newer approach relies on animations defined in the 3d model. Examples of the older technique can be seen in the xml file (see the link above) that defines the m2k gear animations. The rest of this section will focus on the newer approach.
There are basic three steps in creating animations for CSP. First, define the animations within the 3d model using key frames. Second, label the model nodes that will be animated in the simulation. Third, bind the animated model nodes to data channels within the simulation. Each of these steps is described below.
Model Animations
Creating animations in the 3d model typically involves creating an animation path. There are many online tutorials explaining how animations of this type are defined in the various modeling programs. `TODO(lolo): Add details and/or links relevant to CSP and 3DSMax.`
A model exported to `.osg` format should have an `AnimationPathCallback` along with two or more `ControlPoints` associated with each animated node (typically a `MatrixTransform`). When first experimenting with animations it's a good idea to open the `.osg` file in a text editor and inspect the animation data by eye. One common problem is that the exporter may create a separate control point for each frame over some fixed time interval, even if the frames contain redundant data. For example, a simple 2-state switch may get 100 control points to cover a 4 second interval at 25 frames/sec granularity. Most likely we will create a model post-processing script to optimize animation data.
A simple way to test animations is to load the `.osg` file into `osgviewer`. The default animation behavior is to loop, so all the animated parts should swing repeatedly through their full range of motion.
Animation Labels
Animated nodes need special labels so that they well be recognized by the simulation. All animation labels start with the prefix "`ANIM: `" followed by a unique name of the animation. For example, "`ANIM: HUD.AOAIndexer`" and "`ANIM: FrontGear.Steering`." Occasionally it may be desirable to have several distinct animated parts appear as a single animation. To do so, simply add the unique part name at the end of the label, separated by a colon. For example, parts labelled "`ANIM: Aircraft.Canopy : MainJackBody`" and "`ANIM: Aircraft.Canopy : CanopyGlass`" will be animated together by defining an animation driver for `Aircraft.Canopy`.
Animation Bindings
Animations are connected to the simulation by defining animation bindings in the xml file for the model. There are several different types of animation bindings to handle different types of animations. Most bindings use a vehicle data channel to drive the 3D animation. For example, the `ControlSurfaces.LeftElevatorDeflection` channel can be used to drive the `Aircraft.LeftElevator` animation node (with label "`ANIM: Aircraft.LeftElevator`"). Some channels are common to all vehicles of a given type (such as `Aircraft.LeftElevatorDeflection`) while others are specific to a given vehicle. It is up to developers to document all the public channels for each vehicle, although as yet this has not been done (in part because the infrastructure is still in flux).
Before explaining all the binding types, a simple example may be helpful:
<Object class="ObjectModel">
...
<List name="animations">
<Object class="TimedAnimationPath">
<String name="channel_name">Aircraft.CanopySequence.ReferenceTime</String>
<Key name="model_id">Aircraft.Canopy</Key>
<Float name="time_multiplier">.3333</Float>
<Int name="lod_limit">5</Int>
</Object>
...
</List>
</Object>
This definition binds the `Aircraft.CanopySequence.ReferenceTime` data channel to the `Aircraft.Canopy` animation channel using a `TimedAnimationPath`. `TimedAnimationPath` is one of the available binding types documented below.
Each binding class has its own optional and required parameters. In this case, `channel_name`, `model_id`, and `lod_limit` are required parameters, while `time_multiplier` defaults to 1.0 if not set. As noted earlier, the animation channel (set by `model_id`) may be bound to multiple nodes in the 3D model using appropriate labels. The `lod_limit` parameter is common to all animations and is used to reduce the animation overhead for models that are far from the camera. The `time_multiplier` parameter maps the animation time to the reference time (which ranges from 0.0 to 1.0).
TODO(OS) document the different animation binding types. Also, since the xml definition of animation bindings is somewhat tangential to the topic of this page it should probably be broken out into a separate page. This page should focus on the 3D model requirements for each animation type.
TODO(OS) describe how simple, detailed, and multiple cockpits work.
Licensing and Distribution
Licensing is a complicated issue. It is the responsibility of each modeler contributing original work to CSP to choose a suitable license and provide one or more text files that contain the copyright notice and license. Models and associated artwork should be grouped together under a common directory, with the copyright and license included in the top level directory. If possible it may be wise to mark individual files with short copyright and license statements (e.g. in the jpeg comment of texture images).
All artwork added to the CSP repository must be licensed in such a way as to grant the non-revokable right to perpetual, worldwide, royalty-free distribution of the data as part of CSP. It is also important that that modified versions of the artwork can be distributed in the same way. Artwork with more restrictive licenses can of course be distributed by individual artists for use with CSP, but CSP cannot risk relying on data that could become impossible to distribute in the future.
The following licenses are compatible with the above requirements and are recommended for artwork contributed to CSP. If you would prefer to contribute artwork under a different license, or have general questions about licensing, please ask on the forum.
- Creative Commons Attribution-ShareAlike license (http://creativecommons.org/licenses/by-sa/2.5/) (by-sa).
- Creative Commons Attribution-NonCommercial-ShareAlike license (http://creativecommons.org/licenses/by-nc-sa/2.5/) (by-nc-sa).
Miscellaneous
Comments and suggestions: (please add here)
