WEMSaveAsU3D

MLModule

genre	WEMPersistence
status	stable
author	Axel Newe
package	MeVisLab/Standard
dll	MLWEMModules
definition	MLWEMModules.def
see also	WEMSave, ComposeWEMDescriptionForU3D
keywords	WEM, save, U3D, CAD

Purpose

The module WEMSaveAsU3D saves a WEM to U3D file format.

Details

The module saves WEMs to U3D files as defined in Standard ECMA-363 (Universal 3D File Format), 4th edition (June 2007).

If a WEM contains more than one patch, each patch is is converted to a U3D object. Each patch should have a unique name, specified by its "Label" property. If the names of the patches in a WEM are not unique (or not specified at all), that module creates new (unique) names for the U3D objects (the patches themselves are not touched). The names must fit in the "NameString" key type scheme (see below).

More U3D object properties can be specified using the "Description" property of a WEM patch. All U3D properties need to be composed to a single string and thereafter written to the "Description" property of a WEM patch to be parsed by the module (if the module's parameter "Parse WEM Description" is activated). Multiple properties can be concatenated by a ";" Each property is specified by a Key=Value string.

The follwing keys are parsed:

Key	Key Type	Description
U3DGroupName	NameString	Objects may be grouped to establish a simple tree-like hierarchy. This key specifies the group an object is assigned to. Important: Altough the U3D standard supports an almost arbitrary hierarchy depth, currently only one group level is supported. All groups will get the same hierarchy level (groups cannot be assigned to other groups, but to models, see below). NB: Objects may be grouped but must still have a unique name. It not allowed to have an object named "ObjectX" in group "A", and another "ObjectX" in group "B". In this case, a new name would automatically be created for the second "ObjectX".
U3DModelName	NameString	Objects and groups may be assigned to models (a kind of top level group). This key specifies the model, an object (and - if specified - its group) is assigned to. Important: Currently only one single model is supported. Different model names may be specified, but only the last one found will be considered and used for all objects!
U3DColor	ColorStringWithTransparency	This key specifies color and transparency of an object.
U3DGroupColor	ColorStringWithTransparency	This key specifies the color and transparency of an object group. If specified, each object is written twice to the U3D file: once with its original color and once with its group color. Two groups are also created: once with the group name plus the appendix " (color coded)" and once with the group name plus the appendix " (grouped)". If this key is not specified, only one group without appendix is created. The file size increased only minimally when this key is specified, since the geometry data of the affected objects is not written twice. NB: This color must have the same value for all objects that are grouped into a group with the same name!
U3DSpecularColor	ColorString	This key specifies the specular color of an object.

The Key Types are specified as follows:

Key Type	Description
NameString	A string that consists of the letters a..z, A..Z, spaces (" "), brackets ("(" and ")") and the figures 0..9 only. Other characters are not allowed. Example: "Object 01 (left)".
ColorStringWithTransparency	Four groups of floats, separated by a space, defining the red, green, blue and transparency values in the range of [0..1]. Example: "1.0 0.0 0.0 0.4" for red with 40% transparency.
ColorString	Three groups of floats, separated by a space, defining the red, green and blue values in the range of [0..1]. Example: "0.0 1.0 0.0" for green.

Example:

The object hierarchy in the image above has been assembled using the following properties:

Object name	Keys/Values
(in WEM Label property)	(in WEM Description property)
BD territory B5	U3DModelName=Demo_LDLT (XYZ123); U3DGroupName=BD Territories; U3DColor=1.0 0.0 0.0 0.0
BD territory B6	U3DModelName=Demo_LDLT (XYZ123); U3DGroupName=BD Territories; U3DColor=0.0 1.0 0.0 0.0
BD territory B8	U3DModelName=Demo_LDLT (XYZ123); U3DGroupName=BD Territories; U3DColor=0.0 0.0 1.0 0.0
BD branch B8	U3DModelName=Demo_LDLT (XYZ123); U3DGroupName=BD Vessels; U3DColor=1.0 0.0 0.0 0.0; U3DGroupColor=0.75 0.75 0.75 0.0
BD branch B6	U3DModelName=Demo_LDLT (XYZ123); U3DGroupName=BD Vessels; U3DColor=0.0 1.0 0.0 0.0; U3DGroupColor=0.75 0.75 0.75 0.0
BD branch B4	U3DModelName=Demo_LDLT (XYZ123); U3DGroupName=BD Vessels; U3DColor=0.0 0.0 1.0 0.0; U3DGroupColor=0.75 0.75 0.75 0.0
Liver	U3DModelName=Demo_LDLT (XYZ123); U3DColor=1.0 0.0 0.0 0.5

Notes:

• For the "BD territory" objects, no U3DGroupColor is specified and therefore only one group without appendix ist created.
• The "BD branch" objects have a U3DGroupColor (the same for all), though. This results in two groups being created: one with the appendix " (color coded)" and one with the appendix " (grouped)". Since object names must be unique, they also get these appendixes.
• The "Liver" object has no U3DObjectGroup specified and is therefore directly assigned to the U3DModelName model. The U3DModelName must be the same for all objects, since more than one model name is not allowed in the current version.
• All these settings are not made in the WEMSaveAsU3D module itself, but in the WEM generating module chain that is connected to its input!

Tips

The ComposeWEMDescriptionForU3D automatically generates valid WEM names and descriptions.

Windows

Panel

DefaultSettings

Input Fields

inWEM

name: inWEM, type: MLBase

The WEM that should be saved in the U3D format.

Parameter Fields

Field Index

apply: Trigger	Default Material Emissive Color: Color	isProcessing: Bool
Auto Apply: Bool	Default Material Name: String	listenToFinishingNotifications: Bool
Auto Update: Bool	Default Material Specular Color: Color	listenToRepaintNotifications: Bool
autoClear: Bool	Default Material Transparency: Float	listenToSelectionChangedNotifications: Bool
Default Group Name: String	Default Shader Name: String	Parse WEM Description: Bool
Default Light Name: String	elapsedTime: Float	progress: Float
Default Material Ambient Color: Color	Filename: String	Save: Trigger
Default Material Diffuse Color: Color	inWEMValid: Bool	Status: String

Visible Fields

Auto Apply

name: autoApply, type: Bool, default: FALSE

If checked, the module saves the input WEM if any parameter changes on the GUI.

Auto Update

name: autoUpdate, type: Bool, default: FALSE

If checked, the module saves the input WEM if the input changes.

Default Group Name

name: defaultGroupName, type: String, default: DefaultGroup

Sets a group name that is used when no U3DGroupName is specified.

Default Shader Name

name: defaultShaderName, type: String, default: DefaultShader

(Reserved for future use.)

Default Material Name

name: defaultMaterialName, type: String, default: DefaultMaterial

(Reserved for future use.)

Default Light Name

name: defaultLightName, type: String, default: DefaultAmbientLight

(Reserved for future use.)

Default Material Ambient Color

name: defaultMaterialAmbientColor, type: Color, default: 0 0 0

(Reserved for future use.)

Default Material Diffuse Color

name: defaultMaterialDiffuseColor, type: Color, default: 0.75 0.75 0.75

Sets an object surface color that is used if no U3DColor is specified.

Default Material Specular Color

name: defaultMaterialSpecularColor, type: Color, default: 0.75 0.75 0.75

Sets an object specular color that is used if no U3DSpecularColor is specified.

Default Material Emissive Color

name: defaultMaterialEmissiveColor, type: Color, default: 0 0 0

(Reserved for future use.)

Default Material Transparency

name: defaultMaterialTransparency, type: Float, default: 0

Sets an object transparency that is used if no U3DColor is specified.

Filename

name: filename, type: String

Sets the file name and path for the generated U3D file.

Save

name: save, type: Trigger

If pressed, the module saves the input WEM with the parameters to a U3D file.

Parse WEM Description

name: parseWEMDescription, type: Bool, default: TRUE

If checked, the WEM Description property will be parsed.

Status

name: status, type: String

Shows the current status of the module.

Hidden Fields

isProcessing

name: isProcessing, type: Bool, default: FALSE

elapsedTime

name: elapsedTime, type: Float, default: 0

autoClear

name: autoClear, type: Bool, default: TRUE

apply

name: apply, type: Trigger

listenToFinishingNotifications

name: listenToFinishingNotifications, type: Bool, default: FALSE

listenToRepaintNotifications

name: listenToRepaintNotifications, type: Bool, default: FALSE

listenToSelectionChangedNotifications

name: listenToSelectionChangedNotifications, type: Bool, default: FALSE

inWEMValid

name: inWEMValid, type: Bool, default: FALSE

Flag that is set when a valid WEM is connected to the input.

progress

name: progress, type: Float, persistent: no