"White_dune", what's that ?

White_dune is a graphical VRML97 editor, simple (NURBS) 3D modeller and animationtool in development. It can read VRML97/X3DV files, display and let the user change the scenegraph, fields and routes. This can be used to improve or make VRML97/X3DV 3D-worlds, animations and interactions.
The modelling features of white_dune are not strong enough (yet), to use it alone. It makes sense, to let it work together with a 3D modelling tool with static VRML97 export (like for example wings3D or Art Of Illusion).
In difference to most 3D modelling tools the lightning/coloring and the interal structure of white_dune is based on the VRML97/X3D standards. This leads to a better support of the possibilities of VRML97/X3DV, when you create or postprocess 3D models with white_dune.
Compared with the general purpose 3D modellers (which often support only the export of mesh (IndexedFaceSet) and interpolator nodes) white_dune supports all VRML97 nodes and the major part of the nodes of the X3D standards.

"White_dune" crashed, work lost ?

White_dune is work in development and it is not always as stable as it should be.

If white_dune crashed, is your work lost ?

No not automatically !

"White_dune" will try to save the VRML97 file short before crash. This is not always successful e.g. when the error which caused the crash destroyed the internal data structure (this occures seldom). If the file is written sucessfully, white_dune will write under Unix/Linux something like

   Internal Crash !
   Try to save Files
   attempt to write file to /home/someone/.dune_crash_NUMBER_NUMBER.wrl
   write sucessful
to standard error of the starting window and to system console (eg. to the window of the xconsole application).
The important line is the line "write successfull".
Under M$Windows you get (possibly after clicking "ignore", if you are asked about using a debugger) a similar Messagebox

When you restart white_dune and use the file menu, you should see the filename of this .dune_crash file.

Just click to it and save to another file.
This Method can fail, if the error that led to crash has damaged the internal data structure of the program.
In this case it is worth to search in directory of VRML-files for temporary files (".dune_*"), that are produced during the execution of File->Preview or File->Textedit.
These Files will be deleted at a normal program end, but not in case of a program crash.
When white_dune often crashes but all data can be restored successfully, it can be usefull to search this intermediate files and delete them in order to recover diskspace.
Beside files for preview and textedit, white_dune also stores the content of edited scriptnodes in a temporary textfile for use by a texteditor.

Starting "White_dune" with foreign menues

White_dune can be started with menues in foreign languages.
For example, to start white_dune with the german language, the commandlineoption "-german" must be used.
Currently 3 commandlineoptions for languages are available:

Cause it is not very usefull, always to type this in a commandline, there is a second way, to select the language. Under Linux/UNIX this is done via the LANG environment variable. If the first 2 characters of this environment variable is set to "de", german menus are used, if they are set to "it", italien menus are used.
If you want to work in a foreign language environment with $LANG set, but want to use the english menus for white_dune, you must use the -english option.
This can be done with a shellscript (Linux/UNIX/MacOSX) or batchfile (Micro$oft Windows).
If you can not find a matching file (e.g. germandune for the german language), you can create one (e.g. for the german language) with the commandlines: For MacOSX you can modify in the file the lines with the options for the program start:
and add e.g. the -german option for the german language:
   DUNEOPTIONS="-german "
For other exotic UNIX desktops you will find similar options in the following files In a similar way, it is possible to include other commandlineoptions of white_dune. See the man page of white_dune for other options.
The most important options are: The menus and dialogs of white_dune can be translated to foreign language without programming skills.
If you are interested to translate the white_dune menus and errormessages into a new foreign language (no programming skills required), please read the step by step instructions about localisation in the developer documentation.

What is scenegraph, fieldvalues, routes etc. about ?

White_dune (without -4kids or -4catt option) is a lowlevel tool to make/change VRML97 or X3DV Files. The user needs to knows the basic structure of VRML97/X3D.
Of course white_dune can also be used to learn and explore the basics of VRML97/X3D.
A good startpoint is of course the "-4kids" commandline argument, but then the features are limited to building 3D-Objects and Animation. The more interesting VRML/X3D features about interaction and scripting are not available in the "-4kids" variant.

You can find some typical VRML/X3D examples (you can load into white_dune) here, but take care about the fact, this examples do not show modelling or animation features, they show mainly VRML97 examples about interaction and scripting. These are features, which can be not shown in white_dune directly (yet).
The examples are a start base to build interactive 3D worlds with white_dune, which are showed later with a "real" VRML/X3D browser.
The route view and the scripting code is most interesting for a beginner.

You can find detailed technical information about VRML97 in the official ISO specification at . For the use of white_dune, especially the node reference is important.
A good, simple tutorial about VRML97 for beginners you can find (beside in a range of books) at
X3D is the sucessor of VRML97. Despite some minor technical differences (which are handled automatically by white_dune) are alle commands of the VRML97 standard still available in X3D.
This is not the case for the "forgotten" VRML97 Amendment 1 Standard from 2002. Sone VRML97 Amendment 1 commands like e.g the CoordinateDeformer node do not exist anymore, but all still existing VRML97 Amendment 1 commands are handled automatically by white_dune, when a VRML97 file is stored as X3D(V) file.

X3D compiler und Open Wonderland Unterst¨tzung

White_dune can export the data of the VRML97/X3DV scenengraph to the programing languages C, C++ or java ("X3D-compiler").
You will find the details in the manpage of white_dune.
There is a library in development for the programing language C to render 3D objects and animation with OpenGL. You will find examples in the directory docs/export_example_c of the source archive. The similar example for the programing language C++ can be found in the directory docs/export_example_c++.
For the programing language java there is a possiblity to render 3D objects and animation with the Java Monkey Engine (JME, Version 2).
The matching examples can be found in the directory docs/export_example_java.
The export to sourcecode of a module of Open Wonderland(a internet 3d multiuser environment).
Beside the rendering of 3D objects and animation there is also interaction (via the VRML97/X3D sensornodes) possible. But not all X3D nodes and not the wohl runtime behaviour) are supported (yet).
In difference to VRML/X3D and traditional OpenGL supports Open Wonderland no graphical 3D objects, which are made from polygons with more the 3 or 4 edges (despite Open Wonderland internally uses OpenGL). Therefore white_dune trianglulates this objects before the wonderland export.
This is not so easy for morphing animation of 3D objects made of polygons with more than 4 edges. This 3d objects do not support morphing animation in the Open Wonderland export.
To find out, if a X3D node is supported in Open Wonderland, you need to look at the right, lower side of its icons: there is a small blue point (as at the icon for Box)

if the node is supported in Open Wonderland.
The question about which interactions are possible is decided in the RouteView window. For sensornodes and interpolators (only this nodes) the supported events are marked with colors.
A blue or lila mark of the events of a node in the routeview means the support of the event in the Open Wonderland exporter, while a red or no mark means no Open Wonderland support (yet). A red mark means a often used event, a lila mark should show a mix of red and blue: these events are often used as well as supported by the Open Wonderland exporter.
In the example above, the TouchSensor node is shown in the routeview together with some of it's eventnames.

For example a route information way can be built from the TouchSensor.isActive event (blue marked) to a script node. At the script node a small, self written java program build a new event, that another route information way lead in a event of another Open Wonderland supported node.
For example a route information way can also built from the TouchSensor.touchTime (lila marked) to a TimeSensor.set_startTime event (also lila marked), to start a simple animation (cause simple animation in X3D are made from the ROUTE commands "TimeSensor (e.g. with field loop FALSE) -> interpolator > animated node").
The event TouchSensor.hitPoint_changed (red marked) is often used in X3D, but is not supported by the Open Wonderland exporter.

What "white_dune" can not do/can do

The 5 windows of "white_dune"

Beside some toolbars with icons and messages "white_dune" (without the "-4kids" or "-4catt" startoptions) essentially contains 5 windows. Beside the "3D Preview" window you can switch on/switch off this windows via the menu "View". Switch this windows on and off to match your current work status.

Menu overview

The main menu of white_dune is seperated into the following submenus:


To navigate in the 3D Preview Window, you have two differ between different walk modes.

Additional you have from version 0.16 a SGI like navigation. Please note, that is it not seldom, that a similar configured windowmanager interpret all mouse input, that uses the Alt key but itself.... When a 6D inputdevice is active and the Scene icon is selected in the Scene Tree you can navigate depending on the transform icons in the VRML file.
The Scene icon is selected, wenn you klickt into the void of the 3D preview window.
Additionally, there is each a Icon that forces navigation with the mouse or the inputdevice .

Changing the scenegraph

The most simple way to change the scenegraph is to add new node by clicking to the matching VRML node icon.
To identify a VRML node icon, move the mouse to it and wait. A descriptive text will occure in the status bar at the bottom of the white_dune window.
White_dune tries either to include the new node at the point of selection in the scenegraph,

or to the root of the scenegraph ("Scene" icon).
White_dune will gray out all node icons, that are impossible to add.

The following table shows the requirements for this nodes in the VRML97 standard:

For example a Appearence node need to be selected, to include a ImageTexture node, or a Shape node need to be selected to include a Appearence node.
All of the matching node fields in the VRML97 are of type SFNode, therefore only one node can be inserted. A icon is also grayed, if there is already a matching node.
For example you can not include two ImageTexture Nodes to a Appearence node. Therefore the ImageTexture is also grayed, if a Appearence node is selected, but a ImageTexture node is already there.
According to the VRML97 Standard the shape nodes Box, Sphere, Cone, Cylinder, IndexedFaceSet, IndexedLineSet, PointSet, ElevationGrid, Extrusion and Text need a Shape node. The needed structure for the usage of this Shape.geometry nodes is clear. Therefor the click on the icons and the usage of the Create -> Shape -> menuitems build a complete Shape-structure (including default Appearance/Material nodes and a surrounding Transform node).
(New in Version 0.29beta) If the selection in case of a creation of such a node is not a node a Shape node can be part of, the surrounding Transform node is filled in a way, that the new node is shown directly in front of the actual viewpoint.
For the new, but now deprecated nodes of the VRML97 Amendment 1 standard (CoordinateDeformer, NurbsSurface) there are additional rules. The extensions and extra nodes of the immersive Cover VRML97 browser also need additional rules. The extensions and extra nodes of the kambi VRML game engine also need a additional rule. White_dune itself also has a scripted PROTO extensions, which has also a additional rule. Cause there are much more X3D nodes than VRML97 nodes, the list of needed nodes is very much longer: Additionally, there are rules for the X3D nodes of the Rigid Body Physics component, which is listed seperatly, cause this rules alone are not sufficent for a sensefull use: This rules are not sufficent, cause only a structure make sense, where CollideableShape and CollideableOffset nodes are in the root nodes or the scenengraph and get USE-ed in several other nodes, which are USE-ed again. To simplify the creation of this structure, there is a similar operation for scenegraph branchs.

The commands Edit -> copy, Edit -> paste and Edit -> delete work similar to the same commands in many programs.
Of course only changes of the scenegraph are possible, which match the rules above about "node A needs node B". Depending on the selected node in the scenegraph (the target of a Edit -> paste command) the menupoint Edit -> paste can be grayed out or not.
In a unchanged scenegraph it can occured, that it is not possible to insert a copied node at once, cause a node needed to inserted the copied node is missing. The missing node must be created first, before the copy action can be completed successfully.

A unusual command is the Edit -gt; copy branch to root command. It copies all nodes along the path to the root of the current scenegraph branch into the paste buffer.
This can be very handy, if you need to double and split a scenegraph branch.

Another way to change the scenegraph is to drag parts of it with the mouse.
White_dune will show you with a icon of a stop sign, if the target node is not possible cause of the "missing node rules".

If the target node is possible, white_dune will show the normal mousepointer.

The target is not possible, if there are multiple SF/MFNode fields of the target node.

Nodes with multiple fields of type SF/MFNode (e.g. the collision node) always display the field names in the scenetree (despite a opposite setting in the Options -> Preferences dialog), so you can use the field names as targets in this case.

Similar to the local copy/move in the explorer program of M$Windows2000 and similar filemanagers it is possible to change the behaviour, if the keyboard is used when the mouse is still dragged:

Using USE

(new in Version 0.29beta)
Beside the drag and drop method above, there is a additional way to use the USE construct. The node to be USEd need a DEF name which can be applied with Edit -> DEF. The usage of Edit -> USE (if possible) adds a new USE of the last DEFd node at the point of the selected node.
In white_dune (unlike when using a text editor on a VRML97 file), you can legally delete the DEFd node. The first written formerly USEd node becomes the new DEFd node. pointers.
Using USE is useful for keeping VRML files small (faster downloadable), it increases maintainabilty and it can maybe used for faster rendering by a smart VRML browser (e.g. by using glLists on OpenGL rendering).
Additional commands, that can create USE constructs are the array tool and some of the "create" scenegraph operations following.

Scenegraph Operations

(new in Version 0.27beta)
There is no way to move multiple nodes in the scenegraph (yet). As a workaround there are operations to rearrange the current scenegraph branch (Actions -> Move Sibling -> up/down/to first/last position) and operations which can be applied to all nodes in the scenegraph branch following the selection (including the selection itself).

The are commands available via Actions -> Rest of scenegraph branch: Unfortunatly some of these operations are (still) very slow.

Input/erase of ROUTEs

In white_dune, there are two different settings, which drive the way to insert a ROUTE.

ROUTEs are made in white_dune by finding the right icon in the RouteView Window (if you click to the icons, the matching icon in the scene tree windows is selected) or useing Route -gt; Move node to top to add the node to the RouteView Window and click to the boxes of the matching events. The name of the matching event is shown, and you can draw a line to the next icon/event.

As required by the VRML standard, only events with the same type (same color of boxes) can be connected.
To erase ROUTEs, simply cut the line.

As a sugestion for beginners, some event boxes are marked with a small red point. The red point marks a important/often used event.
Of course the importance/usage of events differ with the task of your VRML world. All sensor nodes (the original source of most eventprocessing) have event boxes with red points.

In complex VRML worlds with a lot of objects (for example the VRML export from a 3D-Modelling program like Wings3D, Blender, AOI, Catia, 3D Studio Max, Maya etc.) it can be difficult to find the wanted VRML nodes in the RouteView window.

There are operations to jump to the selected node (with Routes -> Unzoom/jump to selection )

or zoom out of the Routeview (with Routes -> Zoom out)

but in such cases, the usage of the Inline VRML node is recommended. It can be used to put static objects (for example parts of the environment or parts of rigid shapes) in their own VRML files. In result the complete VRML world can only consist of very few VRML nodes.

Commands with automatic generation of ROUTEs
There are two commands to automatically generate new ROUTEs.

Changing fieldvalues

There is more than one way to change fieldvalues:

Simplified scriptbuilding (new in Version 0.22beta)

Before you can use the scripteditor dialog, you need plan what are the datatypes and eventIn/eventOut informations of the nodes you want to connect. To do this, you need to read the node description of the VRML standard (e.g. you can use the menuitem Help -> name of currently selected Node or use a advanced book).
For fast experimenting, you may find it more convenient to use a simplified scriptbuilding method.
Create a new "empty" scriptnode with the "Script" icon (or the menuitem Create -> Programming -> Script).
Following the "get out of the way!" philosophy of the orginal dune project, simply press "OK" on the scripteditor dialog (see above).
Now you can use the RouteView window for further work.

Scriptnodes have a special "connect anything" eventOut. If you click and drag this with the mouse, a white route will be drawn.

Keep the mousebutton pressed while routing and you see (like "normal" routing), you can connect this route to eventIns of other nodes,

but (unlike "normal" routing) the color of the route (marking the datatype) can change with the probed eventIn.

When you release the mousebutton, the route will be established.

In a similar way, you can use the special "connect anything" eventIn of the scriptnode

and connect it to a eventOut of a other node.

Now you need to edit the "url" field of the script node. Beside using urledit you can also select the script node in the SceneTree window, the "url" field in the FieldView.

and press the "Object Edit" icon (or use the menuitem Actions -> Object edit).

Now "white_dune" will try to start a external editor - UNIX die-hards use "xterm -e vi", this is the default under Linux/UNIX ("xedit" for MacOSX, "edit" for M$Windows) if $WINEDITOR was not set at first run. You can change the editor with the Options -> Texteditor Settings ... menuitem.
In the editor window, you will see a schema of the needed javascript code.

Use the editor to complete the javascript code and save/quit the editor - in case of the vi editor use the keystrokes :wq
Use Options -> ECMAscript settings to control, if you want extended comments in the schema.
A lot of comments are written per per default. This is usefull for beginners, they only have to select from the possible commands for the used datatypes. But unfortunatly, this makes larger scripts difficult to read.
User with experience tend to uncheck anything in the Options -> ECMAscript settings window, so only the hardwired comments about the used datatypes remain.

NURBS Modelling (partitially new in Version 0.25beta)

Superformula Modelling (new in Version 0.27beta)

Superformula basics

White_dune has support for 3D-modelling based on the so called "superformula"

        pow(pow(fabs(cos(m * angle / 4.0) / a), n2) + 
            pow(fabs(sin(m * angle / 4.0) / b), n3), -1.0 / n1)

This formula has been found by a biologist a few years ago and can be used to form n-symetric shapes similar to shapes in nature like flowers, leafs, insect bodies, shells or starfishs.

See this range of shapes, which are all done with the SuperShape PROTO.

Superformula based shapes are not part of VRML97 by itself and are implemented by a PROTO (self defined VRML97 node) with scripting ("scripted PROTO").
Superformula based shapes can be converted either to a Extrusion node or to a IndexedFaceSet node. IndexedFaceSet based scripted shapes can also be approximated to a Nurbs(Patch)Surface node as a starting point for further NURBS-modelling.

Subdivide Modelling (new in Version 0.99pl624)

Subdivide Modelling is available via the actions -> subdivide command or pressing "s" if a mesh based node (e.g. IndexedFaceSet, Box or NurbsSurface) is selected. Subdivide uses the Catmull-Clark Algorithm to make objects smoother.
You can start with a selected box:

Use actions -> subdivide or press "s"

Use selection -> faces and drag the clicked face out with the left mouse button still pressed.

To get it smoother again, use actions -> subdivide or press "s"

To hide the faces, you can set creaseAngle of the IndexedFaceSet.

Be aware that ist no unsmooth command in white_dune, except the tessellation fields in Nurbs(Patch)Surface or superformula based nodes.

So it is usefull to often use edit -> undo to test and modify the subdivided object.
Unfortunatly Subdive do not work with all faces, it works only with closed objects. Therefore is Subdivide gray when a SuperExtrusion node is selekted.

Changing coordinate based nodes (new in Version 0.29beta)

Since version 0.29beta also Coordinate based nodes (like IndexedFaceSet ("Mesh"), IndexedLineSet or PointSet) can be changed interactivly in the 3D preview window in the same way as changing the controlpoints of a NURBS shape.
For nodes with very much vertices, this (still) only usefull to change small details.

Flip/swap and set center actions

There are a few handy modelling actions in the Action menu:

Array tool(new in Version 0.27beta)

White_dune allows to multiply objects. In difference to similar functions in some 3D-Modellers (like the "Art of Illusion" program) it do not create N copies of the same object. It creates N VRML Transform nodes (for translation, rotation etc. in respect to the Array dialog below.) with a VRML USE construct. A USE construct is a compact way to repeat things in VRML. It is a sort of "pointer without difference" similar to a hardlink to a UNIX file (if you know only M$Windows: a more smart way of a shortcut to a file). A USEd node also changes, when it orginal changes.

To use the Array tool, select the object you want to multiply

and use Actions -> Array. A dialog will occure

where you can input the number of objects and the parameters for the transform node.

When you change the orginal, all USEd nodes change too.

Repair commands in the "Actions" menue

The following commands are usefull, when you work with VRML/X3D files made by other tools. The commands are made to correct some minor errors and problems.

Other commands in the "Actions" menue

PROTO creation/editing

(new in Version 0.99pl444)

To create a PROTO, a scenegraph branch has to be created first. The nodes of the scenegraph branch are the major part of the PROTO.
In this example, the nodes of a Shape/Box, Shape/Sphere and Viewpoint are in the scenegraph branch.

To create a PROTO with this nodes you must click Actions->Rest of scenegraph branch->Move to->new PROTO.

This is followed by a dialog, that asks for the name of be PROTO, here you select "DOME".

As next follows a dialog, which let you select the arguments of the PROTO. Later you select this Dialog by selecting the PROTO and use Edit -> Object edit. As field argument you select SFColor color and press "Add".

Then you press "ok" to end the Dialog.

Next opens the RouteView/IS-Fenster, the PROTO "DOME" is selected.

It is now possible to add/change nodes of the PROTO with the rest of the scenegraph. In this case, the Viewpoint node is moved out of the PROTO into the scene.
Next Create -> PROTO usage -> DOME is used to display the DOME in the scenegraph.

Next you select a Material node in the PROTO and use Routes/IS -> Show node on top .

Next you move Material node and PROTO in the Route/IS view to connect color and diffuseColor zu.

Next you select the other Material node in the PROTO and use Routes/IS -> Show node on top .

Next you move the other Material node and PROTO in the Route/IS view to connect color and diffuseColor zu.

After that you can change "color" in the DOME node and insert another Transform and DOME pair.

VrmlCut scripted Proto

(new in Version 0.29beta)

In VRML/X3D it is amaizingly different to build sequences of animations, usually called "movie". According to the realtime 3D nature of VRML/X3D animations can be started interactivly and independendly from each, so it there is difficult to define a overall timeline, just like the cutting of a movie.
One approach to ease this problem in white_dune is the usage of the scripted PROTO node VrmlCut. It has a Field "scenes", where single animation VRML/X3D data can be put into other scripted PROTO nodes named VrmlScene. The content of such a VrmlScene node can be seen similar to a single scene in a movie. The VrmlCut node switches from one VrmlScene to the next VrmlScene and try to jump to the first camera viewpoint and try to start all the animations in the current VrmlScene node.
Just like the SuperShape, SuperEllipsoid, etc. node the VrmlCut node is not a buildin VRML node. It is a PROTO, a sequence of VRML nodes, that is composed by a Switch node and a Script node and TimeSensor node.
Like a Script node it has a changable set of fields/events. Cause multiple VrmlCut nodes would have multiple different sets of fields/events, you can have only one Proto definition of VrmlCut and therefore you can have only one VrmlCut node per VRML-file.
The VrmlCut switches between a sequence of VrmlScene nodes (basically a Group-like node with some scripting for routing) driven by the internal TimeSensor and the Script.
All information between the VrmlCut, VrmlScene, TimeSensors (for animations) and Viewpoints (cameras) are passed via ROUTE commands. This makes the concept flexible (for example the ROUTE sources can be reused to drive other nodes like Sound or Fog) but building much ROUTEs is much work.
To reduce the work, the following method can be used:

At the end, you can use the "play" icon or File->previewto start the sequence of animations.
With the sceneNumber, numberPreviousScenes and numberNextScenes fields of VrmlCut can be used play a reduced range of scenes. This is usefull to optimize the lengths of the scenes in the sceneLengths field of VrmlCut.

File -> upload

(new in Version 0.27beta)

White_dune has a command (menuitem File -> Upload) to upload a VRML file to a internet server.
When you upload files to the internet, you are usually ask about a access password. White_dune has the ability to store the password in a memory protected from swapspace by mlock/vlock calls.
The swapspace is a region on the disk where the content of the computer memory can be swapped out to make space for other running programs. A intruder can inspect the swapspace to search for passwords.
Passing a password from one application (white_dune) to a other application (the upload command) in a secure way is not a easy task in respect to things like swapspace.
In the upload settings dialog (see Options -> Upload settings...)

the upload command can have two parameters. Each parameter of the upload commandline is set with the characters "%s".

The last line in the upload settings dialog gives you the ability to reload a HTML-webpage after the upload. To use it, you have to type in the HTML tags that will be copied into a HTML file.
For example, the following dialog will copy the data by white_dune to a VRML file with a static name and will display this VRML file together with the string "hello" in the webbrowser on the next File -> upload command.

The HTML tags line can contain "%s" characters, which would be replaced by the password. This would result in a HTML file with the password in it. This is a very high security risk, do not use this feature without knowing exactly what you are doing !