Help save net neutrality! Learn more.
Close

Documentation

Using the OSG Max Exporter Plugin

From within 3D Studio you can use several ways to start the plugin;

  1. Choose Export from the File menu and choose OpenSceneGraph Exporter (.OSGB, .OSGT, .IVE, .OSG) as file type (typing the extension specifies which one will be used). This will open a dialog box with export options.
  2. Right-click on the toolbar and select Customize to bring up a dialog for customizing the user interface. Select the Toolbars tab within the dialog. Select Main UI in the Group dropdown menu. Select OpenSceneGraph Exporter in the Category dropdown menu. You can now drag-drop specific exporter actions onto the toolbar.
  3. The Helpers are available from the Helpers section on the Create pane, by selecting the OpenSceneGraph drop-down item.

Toolbar Actions

Export the scene and preview it
Export the selected objects and preview it
Show the export options dialog

Exporting files

Supported Formats

  • osgb: The preferred format for newer OSG versions. This is a binary format which means it will load very quickly and supports embedded image data within the file.
  • osgt: This is a text based format, which means it will take longer to load. However, the benefit of this format is that it can be opened and modified within a simple text editor.
  • ive: The legacy binary format. Only use this format if your version of OSG does not support the newer osgb format.
  • osg: The legacy text format. Only use this format if your version of OSG does not support the newer osgt format.

Limitations

Not everything modelled in 3D Studio can be exported flawlessly to an OSG-file. Below is a list of things that might prove impossible to export and some suggesting to make them work anyway.

  • Animated modifiers: use an OSG Sequence Helper to make this work. Otherwise the animation behaviour of the objects may be unpredictable.
  • Some Space Warps
  • Particle Systems?: only simple ones can be exported without a problem. For complex Particle Systems? the use of an [OSG_Sequence] could also be an option.
  • The AEC Exteneded geometrical object could pose a problem. So far it turns out that the Foliage-objects (trees, shrubs and other items) are not exported very well, supposedly due to the large number of very small objects which the viewer will cull.

Export options

When you've selected a file type you will be presented with a large scrollable dialog box, with the following panel sections:
(Note: This dialog can be accessed directly form the OSG Exporter Toolbar)

Output

  • Save File: If you uncheck this option, no copy of your file will be saved to disk, unless you are previewing the scene with a custom command line. This can be useful if you only want to Quick View your scene.
  • Texture image location: Controls where exported texture images are saved:
    • Embed in binary file: When exporting to a binary format (i.e. ive/osgb), store the image data within the file. This option will generally help speed up load times. When exporting to a text format, this option will fallback to the Save in sub-folder option.
    • Save in sub-folder: The texture images will be saved in an "images" folder in the same directory as the exported file.
    • Use original path: The exported texture images will reference the original file paths used by 3ds Max.
    • Do not save: The texture images will not be saved out, but the generated filenames will be the same as the Save in sub-folder option.
  • Quick View Scene: Preview the exported model. If the preview command line is specified, then the exported file will be passed to the preview application. Otherwise, a small preview window will be created within 3D Studio MAX displaying the exported OSG model.
  • Preview command line: A custom command line to execute when the Quick View Scene option is enabled. The command line must contain an argument named <FILE>, which will be replaced with the exported file name. For example, the following command line will preview the model in stereo with the osgviewer application:

"C:\OpenSceneGraph\bin\osgviewer.exe" --stereo <FILE>

Export Objects

  • Geometry: Export vertices/polygons of geometry objects
  • Materials: Export materials as osg::StateSet objects
  • Textures: Export material maps as osg::Texture objects
  • Cameras: Export camera objects as osg::PositionAttitudeTransform nodes
  • Lights: Export light objects as osg::LightSource nodes
  • Shapes: Export shape objects (splines, curves, etc..)
  • Hidden Nodes: Export hidden nodes
  • Animations: Export key frame animations as osg::AnimationPath objects
  • OSG Helpers: Export OSG helper nodes
  • Point Helpers: Create an osg::Geometry object containing a single point for each point helper node
  • Particles: Export particles as osgParticle::ParticleSystem objects
  • Background Map: If a global environment map is specified in the "Environment and Effects" dialog, then export the map. The geometry used to export the map depends on the map type. Currently spherical, screen, and cube maps are supported.

Geometry State

  • Texture Coordinates: Export texture coordinates of geometry
  • Vertex Normals: Export per-vertex normals of geometry
  • Vertex Colors: Export per-vertex colors of geometry
  • Normalize Normals: Normalize vertex normals by enabling GL_NORMALIZE flag
  • Turn off Lighting: Turn off lighting by disabling GL_LIGHTING flag

Maps

  • Diffuse: Export diffuse maps of standard materials
  • Self-Illumination: Export self-illumination maps of standard materials
  • Reflection: Export reflection maps of standard materials
  • Opacity: Export opacity maps of standard materials
  • Specular: Export specular maps of standard materials
  • Bump: Export bump maps of standard materials
  • Glossiness: Export glossiness maps of standard materials
  • Specular Level: Export specular level maps of standard materials
  • Refraction: Export refraction maps of standard materials
  • Displacement: Export displacement maps of standard materials
  • Ambient: Export ambient maps of standard materials
  • Filter Color: Export filter color maps of standard materials

Material State

  • Auto alpha blending for textures with alpha: Automatically enabling alpha blending on materials which contain an alpha texture. This will add an osg::BlendFunc attribute to the osg::StateSet and apply the osg::StateSet::TRANSPARENT_BIN rendering hint.
  • Automatic 2-sided lighting for 2-sided materials: Applies an osg::LightModel attribute to the osg::StateSet with the two-side flag enabled.
  • Set Diffuse color to white when 100% textured: Set the osg::Material diffuse color to white when a diffuse map is present.
  • Set Self Illumination on baked shell materials: Disable GL_LIGHTING on shell materials
  • Self-Illumination scale: When a self-illumination map is present, apply the given RGB scale to the osg::TexEnvCombine attribute
  • Export Unknown Maps: Convert unknown texture maps to standard bitmaps and export them
  • Export Material Description: Adds a description string to the root node describing each material in the model. The description string format is as follows:

    osgmaxexp material data

    Name <MaterialName>
    Type <MaterialType>
    Map <MapTypeName> <Unit> <BlendAmount> <Filename> <UVMapping> <AlphaAsMono>
    Normal <Unit> <Amount> <MethodName> <FlipRed> <FlipGreen> <SwapRedGreen>
    Cube <Unit>
    SelfIlluminationColorMode <UseColor> <Value>

    Note: All fields are separated by a tab character, \t

  • Name:

    • <MaterialName> - Name of the material, which is also assigned to the name of the corresponding osg::StateSet object
  • Type:
    • <MaterialType> - Type of the material. One of the following:
    • Standard
    • Blend
    • Unknown
  • Map:
    • <MapTypeName> - Name of the map type. One of the following:
    • Ambient
    • Diffuse
    • Specular
    • Glossiness
    • Specular Level
    • Self-Illumination
    • Opacity
    • Filter Color
    • Bump
    • Reflection
    • Refraction
    • Displacement
    • <Unit> - The texture unit of the map in the osg::StateSet object
    • <BlendAmount> - The blend amount specified in standard material
    • <Filename> - The filename associated with the texture map
    • <UVMapping> - The UV mapping mode. One of the following:
    • UVMAP_EXPLICIT
    • UVMAP_SPHERE_ENV
    • UVMAP_CYL_ENV
    • UVMAP_SHRINK_ENV
    • UVMAP_SCREEN_ENV
    • <AlphaAsMono> - 0 or 1 indicating whether the map is specified as a mono value in the alpha channel of the texture
  • Normal
    • <Unit> - The texture unit of the normal map in the osg::StateSet object
    • <Amount> - The bump amount
    • <MethodName> - The normal map method: One of the following:
    • Tangent
    • Local XYZ
    • Screen
    • World
    • <FlipRed> - 0 or 1 indicating whether the red channel is flipped
    • <FlipGreen> - 0 or 1 indicating whether the green channel is flipped
    • <SwapRedGreen> - 0 or 1 indicating whether the red and green channels are swapped
  • Cube
    • <Unit> - The texture unit of the cube map in the osg::StateSet object
  • SelfIlluminationColorMode
    • <UseColor> - 0 or 1 indicating whether to use the specified self-illumination color value
    • <Value> - The self-illumination intensity to multiply with the diffuse color, if <UseColor> is 0

Texture State

  • Allow non-power-of-two: Allow OSG to load non-power-of-two sized images
  • Free image memory after load: Tells OSG to release the image data after uploading it to the GPU. This will help reduce memory usage of your application. However, if you need to access the image data during runtime, then disable this option.
  • Preserve DDS image contents: If the original texture file is a DDS image, then preserve the entire contents of the image when exporting. This allows exporting images with custom mipmaps or non-standard pixel formats.
  • Texture format: The file format to use when writing out textures. If jpg format is used and the texture contains alpha, then the png format will be used instead. The Setup button will open the settings dialog for the selected format.
  • Texture compression: The texture compression format to use. Enabling texture compression can save GPU memory. However, the compression is lossy, so it will introduce some compression artifacts. When compression is enabled and images are being embedded within binary files, the exporter will pre-compress the image and save the compressed data within the file. This will reduce the exported file size and speed up load time of the texture.
  • Anisotropic Filtering: The anisotropic filtering level to apply to textures. Anisotropic filtering enhances the quality of textures when viewed at oblique angles. Higher anisotropic levels will give better image quality, but will require more computation power.
  • Texture clamp mode: The wrap mode to use for clamped textures. Can be CLAMP_TO_BORDER, CLAMP_TO_EDGE, or CLAMP.

Optimize

  • Tri Strip Geometry: Convert Geometry surface primitives into tri strips.
  • Merge Geometry:
  • Check Geometry:
  • Make Fast Geometry:
  • Merge Geodes: Combine geodes
  • Index Mesh: Convert geometry that uses DrawArrays to DrawElements i.e., construct a real mesh. This removes duplicate vertices.
  • Vertex Post Transform: Optimize the triangle order in a mesh for best use of the GPU's post-transform cache.
  • Vertex Pre Transform: Optimize the use of the GPU pre-transform cache by arranging vertex attributes in the order they are used.
  • Flatten Static Transform: Flatten Static Transform nodes by applying their transform to the geometry on the leaves of the scene graph, then removing the now redundant transforms. Static transformed Subgraphs that have multiple parental paths above them are not flattened.
  • Share Duplicate States: Optimize State in the scene graph by removing duplicate state, replacing it with shared instances, both for StateAttributes, and whole StateSets.
  • Spatialize Groups: Spatialize scene into a balanced quad/oct tree.
  • Remove Redundant Nodes: Remove rendundant nodes, such as groups with one single child.
  • Copy Shared Nodes: Copy any shared subgraphs, enabling flattening of static transforms.
  • Static Object Detection: Optimize the setting of StateSet and Geometry objects in scene so that they have a STATIC DataVariance when they don't have any callbacks associated with them.
  • Combine Adjacent LODs: Optimize the LOD groups, by combining adjacent LOD's which have complementary ranges.
  • Flatten Billboards: Flatten MatrixTransform/Billboard pairs.

Miscellaneous

  • Show Error Messages: Turn this on to get some feedback about the conversion progress.
  • Use Default Node Mask: The default node mask value will be applied to all nodes for which no value is specified (for instance in a [OSG_NodeMask] Helper).
  • Convert units to: The units to convert the model to before saving, or No Conversion to use the units specified in Max.
  • Export animations over individual time range: When enabled, animation paths will be exported over their individual time ranges, instead of the overall time range of the model. This allows exporting animations with different durations.

Using the OSG Helpers

The OSG Exporter comes with 11 Helper objects:

  1. Billboard
  2. DOF Transform
  3. Sequence
  4. Switch
  5. Occluder
  6. Group
  7. StateSet
  8. LOD
  9. NodeMask
  10. Imposter
  11. Visibility Group

Related

Wiki: Billboard_Helper
Wiki: Impostor_Helper
Wiki: LOD_Helper
Wiki: Main_Page
Wiki: NodeMask_Helper
Wiki: OSG_NodeMask
Wiki: OSG_Sequence
Wiki: Occluder_Helper
Wiki: Sequence_Helper
Wiki: Space.menu
Wiki: StateSet_Helper
Wiki: Switch_Helper
Wiki: Visibility_Group_Helper