Kambi VRML game engine
← Users Developers →
 
Intro and News
 
view3dscene
 
The Castle
 
All Programs
 
Forum
 
Engine
 
VRML/X3D
 
Other
 

view3dscene (version 3.8.0)

Screenshot from "view3dscene"
Screenshot from "view3dscene"
Screenshot from "view3dscene"
Screenshot from "view3dscene"

view3dscene is a VRML / X3D browser, and a viewer for other 3D model formats.

  1. Downloading and installing
    1. Optionally install GNOME (and other freedesktops) integration
  2. Features
  3. Running
  4. Controlling program with keys & mouse
  5. Command-line options
    1. Capturing screenshots and movies of 3D scenes and animations
    2. Other options
  6. Requirements
  7. Freshmeat entry

1. Downloading and installing

Download view3dscene from it's WWW page.

No installation is required. Just download and unpack these archives wherever you want, and run the program inside. The documentation (this web page) is also included inside (look in the documentation/ subdirectory) for offline viewing.

This is free/open-source software. You can download sources of this program (for developers and such) (link to vrmlengine.sf.net).

Demo scenes: Kambi VRML test suite contains many demo VRML / X3D models, you can open them with view3dscene. It also contains links to other 3D models scattered around our repository.

If you want to hear 3D sound, you should also install OpenAL and OggVorbis (VorbisFile and dependencies) libraries. For Windows, they are already included in the zip file, so you don't have to do anything. For Linux, you should install them using your package managar. For Mac OS X, OpenAL is already preinstalled and you can get VorbisFile from fink (link to vrmlengine.sf.net).

1.1. Optionally install GNOME (and other freedesktops) integration

If you use GNOME (or other desktops following freedesktop.org specifications), you can optionally install also view3dscene menu item (will be placed in the Graphics menu category), with a nice icon, and associate it with appropriate 3D model types.

# Place view3dscene on $PATH, for example like this:
sudo ln -s /usr/local/bin/view3dscene view3dscene

# Install menu items, icons, mime types:
cd desktop/
./install.sh

You may need to logout and login again to your GNOME/desktop session for all programs to catch up (alternatively, you can do killall gnome-panel && killall nautilus but this is obviously somewhat brutal method).

If you use GNOME file manager Nautilus there's one more cool thing you can do: use view3dscene to generate on-the-fly thumbnails of 3D models in the viewed directory. Assuming that view3dscene is on the $PATH and you already did previous ./install.sh, you can run:

./install_thumbnailer.sh

This will add the gconf keys to run thumbnailers on your 3D models. Enter some directory with VRML / X3D / other 3D files, and enjoy your thumbnails :) Beware that loading arbitrary 3D scene may take a lot of time, so using the thumbnailer may consume a lot of memory and CPU power. But it seems that thumbnailer is nicely run with appropriate priority, so it doesn't actually exhaust your cpu. And the author of this text is using view3dscene thumbnailer all the time, and it works flawlessly :) So give it a try!


2. Features

Supported file formats:

Among many features are:


3. Running

Simply run without any command-line parameters. Load your model file using "Open" menu item.

You can provide on the command-line file name to load. As usual, dash (-) means that standard input will be read (in this case the input must be in Inventor / VRML / X3D (classic) format).

Also read about view3dscene additional command-line options.


4. Controlling program with keys & mouse

Controls in Examine navigation mode :

Mouse:
Rotate Left mouse dragging
Move Middle mouse dragging (or Left mouse + Shift)
Zoom Right mouse dragging (or Left mouse + Ctrl)
Keys:
Rotate Arrows / PageUp / PageDown
Stop rotating Space
Move Ctrl + Arrows / PageUp / PageDown
Scale + / -
Restore default transformation Home

Controls in Walk / Fly navigation mode :

Basic:
Forward / backward Up / Down
Rotate Left / Right
Raise / bow your head PageUp / PageDown
Restore head raise to initial position (neutralize any effect of PageUp / PageDown) Home
Fly up / down Insert / Delete
Move left / right Comma / Period
Jump / crouch (only when Gravity works, in Walk mode) A / Z
Turn Mouse Look On (Ctrl+M) to comfortably look around by moving the mouse. In the "Mouse Look" mode, the keys for strafe and rotations swap their meaning:
  • Left / Right keys move left / right
  • Comma / Period rotate
Additional controls:
Increase / decrease moving speed (has effect on keys Up / Down, Insert / Delete, Comma / Period) + / -
Increase / decrease avatar height (preferred camera height above the ground) Ctrl + Insert/Delete
Rotate slower (useful when you want to set up camera very precisely, e.g. to use this camera setting to render a scene image using ray-tracer) Ctrl + Left / Right
Raise / bow your head slower Ctrl + PageUp / PageDown
Pick a point, selecting triangle and object Right mouse click

Left mouse button is also universally used for interacting with the VRML/X3D world. When the cursor turns into a grabbing hand you know you can click or drag on this object. This is realized by the VRML/X3D pointing-device sensors.

There are a lot of other keys that work independent of current navigation mode. You can see them all by exploring menus, and looking at the key shortcuts.


5. Command-line options

All options described below may be given in any order. They all are optional.

5.1. Capturing screenshots and movies of 3D scenes and animations

Command-line options:

  --screenshot  TIME  FILE-NAME
  --screenshot-range  TIME-BEGIN  TIME-STEP  FRAMES-COUNT  FILE-NAME

These options allow you to capture a screenshot of the loaded scene. They know about animations stored in 3D files, that's why they take parameters describing the animation time to capture. They are used to take screenshots in "batch mode". (In interactive mode, you can use comfortable menu items Display -> Screenshot....)

For a still 3D scene, you usually just want to use the simpler --screenshot option with TIME set to anything (like zero) and not worry about anything else.

For animations, more possibilities are available. You can capture any frames of the animation by using many --screenshot options. You can also capture a movie by --screenshot-range (as a series of images or, if ffmpeg is installed and available on $PATH, even directly to a single movie file). The biggest advantage of recording movie this way is that the movie is guaranteed to be captured with stable number of frames per second. This is different than using some independent programs to capture OpenGL output, like the fine GLC (nice GLC overview here), as real-time capture usually means that the program runs slower, and often you loose movie quality.

You most definitely want to pass 3D model file to load at command-line too, otherwise we'll just make a screenshot of the default empty (black) scene. So to take a simple screenshot of a scene, at it's default camera, just call

  view3dscene my_model.wrl --screenshot 0 output.png

The detailed specification how screenshot options work:

Examples:

Hints:

Generally, you can take a look at (complex) example how to make a screenshot from animation in screenshot_for_kambi_www/ directory.

5.2. Other options

--write-to-vrml

Option --write-to-vrml means "don't open any window, just convert the input model to VRML, write the result to the standard output and exit". This way you can use view3dscene to convert 3DS, MD3, Wavefront OBJ, Collada and GEO files to VRML, like
  view3dscene scene.3ds --write-to-vrml > scene.wrl ,
you can also use this to do some VRML file processing using options --scene-change-* described below.

--anti-alias AMOUNT

Use full-screen anti-aliasing. You can also configure it from the menu File -> Startup Preferences -> Anti aliasing. Using this command-line option is mainly useful together with --screenshot option.

Argument AMOUNT is an integer >= 0. Exact 0 means "no anti-aliasing", this is the default. Each successive integer generally makes method one step better. But also more demanding — program may run slower (if your graphic card cannot provide context with sufficient number of samples needed for multi-sampling). See Anti aliasing in interactive mode for the meaning of AMOUNT values. Currently, highest value is 4. So AMOUNT numbers above 4 are exactly the same as 4.

There is no guarantee what specific values of AMOUNT exactly mean, as this depends on your graphic card capabilities. The graphic cards themselves don't provide methods to reliably set some specific FSAA method (only hints, like glHint(GL_MULTISAMPLE_FILTER_HINT_NV, ...)) since the general idea is that better GPU models may provide the same or even better results using different methods. From your (user) point of view, you can test each method and just decide which looks best and isn't too slow on your 3D model and graphic card.

--scene-change-no-normals
--scene-change-no-solid-objects
--scene-change-no-convex-faces

Using one of these options changes the scene before it is displayed (or saved to VRML, if you used --write-to-vrml option). These options are useful when you suspect that some of the informations in scene file are incorrect.

These options change only the scene which filename was specified at command-line. Later scenes (that you open using "Open" menu item) are not affected by these options. Instead, you can use "Edit" menu commands to perform any of these scene changes at any time. Really, these command-line options are usable mostly when you're using parameter --write-to-vrml.

Below is the detailed description of what each scene change does. This is also a documentation what corresponding command in "Edit" menu of view3dscene does.

  • --scene-change-no-normals :

    Scene change: For VRML 1.0, all Normal and NormalBinding nodes are deleted. Values of normalIndex field in IndexedFaceSet and IndexedTriangleMesh nodes are deleted. For VRML >= 2.0, all normal fields are set to NULL.

    Effect: view3dscene will always calculate by itself normal vectors. Useful when you suspect that normals recorded in scene file are incorrect (incorrectly oriented, incorrectly smoothed etc.)

  • --scene-change-no-solid-objects :

    Scene change: For VRML 1.0, in all ShapeHints nodes we will set shapeType to UNKNOWN_SHAPE_TYPE. UNKNOWN_SHAPE_TYPE is the default value of this field, so the purpose of this modification is to cancel SOLID values for this field. For VRML >= 2.0, all solid fields are set to FALSE (on all geometric nodes, like IndexedFaceSet, actually all X3DComposedGeometryNode, Extrusion, etc.).

    Effect: program will not use back-face culling optimization. This optimization often saves us time because we don't have to render faces that would be seen from "inside" if these faces are part of some solid object. Unfortunately, many VRML models have objects incorrectly marked as solid. There are also some scenes that were prepared for some special viewing (e.g. as game levels) and so some amount of "cheating" to optimize these scenes was allowed, e.g. to mark some non-solid objects as solid.

    To view such models properly you have to tell view3dscene (using this command-line option) that such objects are not really solid.

  • --scene-change-no-convex-faces :

    Scene change: For VRML 1.0, in all ShapeHints nodes we will set faceType to UNKNOWN_FACE_TYPE. Moreover we will wrap whole scene in Group node and we will add at the beginning node

    ShapeHints { faceType UNKNOWN_FACE_TYPE }
    For VRML >= 2.0, all convex fields are set to FALSE.

    Effect: All IndexedFaceSet and Extrusion faces will be treated as potentially non-convex. This means that we will load the scene a little longer but all faces will be correctly interpreted and displayed. It's useful when you suspect that some scene faces are non-convex but it's not correctly marked in the scene by VRML author.

Example: I have here some model helicopter.wrl that looks incorrectly when it is displayed because all parts of model are marked as SOLID while they are not solid. So to view this model correctly I can use command
  view3dscene --scene-change-no-solid-objects helicopter.wrl
I can also correct this model once using command
  view3dscene --scene-change-no-solid-objects helicopter.wrl --write-to-vrml > helicopter-corrected.wrl.

--navigation EXAMINE|WALK|FLY|NONE...

Set initial navigation type. Default is EXAMINE. This can be overridden in particular VRML/X3D scene by using the NavigationInfo node. Valid values for this option are the navigation type names for VRML/X3D NavigationInfo.type, see link above.

You can always change navigation mode later, while the program is running: use the menu Navigation.

--camera-radius <float>

When you move in the scene with collision detection, the "user" is treated as a colliding sphere with given radius. Default radius of this sphere is the average size of scene bounding box divided by 100. Using this command-line option, you can set the radius of this sphere to any value (greater than 0). This can be very useful, but be careful: too large radius will make moving (with collision detection turned on) impossible (because every possible move will produce a collision). Too little radius may produce precision-errors in depth-buffer (this can lead to some strange display artifacts).

--detail-quadric-slices <integer>
--detail-quadric-stacks <integer>
--detail-rect-divisions <integer>

These options control triangulating. Two --detail-quadric-xxx options control triangulating of spheres, cones and cylinders: how many slices (like slices of a pizza) and how many stacks (like stacks of a tower) to create. The 3rd option, --detail-rect-divisions, says how we triangulate faces of cubes. It's best to test how your models look in wireframe mode to see how these options work.

Note that my programs do two different variants of triangulation, and they automatically decide which variant to use in each case:

  1. Normal triangulation, that is intended to improve the approximation of quadrics as triangle meshes. This is used for collision detection and for ray-tracer.
  2. The so-called over-triangulation (it's my term, used in various places in my code and documentation and printed messages), that is intended to improve the effect of Gouraud shading. This is used when rendering models with OpenGL.

    In this variant we do some more triangulation than in "normal" triangulation. E.g. in normal triangulation we don't divide cones and cylinders into stacks, and we don't divide cube faces (because this doesn't give any better approximation of an object). But when over-triangulating, we do such dividing, because it improves how objects look with OpenGL shading.

--renderer-optimization none|scene-display-list|shape-display-list

Set rendering optimization.

  • "none" doesn't really optimize anything, like the name suggests. It assumes that the 3D world completely changes in every frame, so there's really no point in caching and preparing anything. In practice, used only for testing purposes.

  • "scene-display-list" assumes that the scene is mostly static and is usually completely visible. In such situations, it is absolutely the fastest.

    Some dynamic scene changes don't work, some work but are very slow. When you walk inside the scene, it's very non-optimal (frustum culling and such cannot work).

  • "shape-display-list" is the best general optimization for 3D worlds. This is good for both dynamic and static scenes. This provides nice speedup (frustum culling and such) when you don't see the whole 3D world at once.

For more technical details see documentation of TGLRendererOptimization type in VRMLGLScene unit.

As usual all standard options understood by OpenGL programs, standard options understood by OpenAL (3D sound) programs, standard options understood by all my programs are allowed. Run with command-line --help to get full list.


6. Requirements

To play movies (in VRML MovieTexture nodes) and to record movies (by --screenshot-range option) you have to install ffmpeg and make sure it's available on $PATH.

Also convert program from ImageMagick package must be available on $PATH for some image formats to work.


7. Freshmeat entry

Here's a link to view3dscene entry on freshmeat. You can use this e.g. to subscribe to new releases, so that you will be automatically notified about new releases of view3dscene.