User Tutorial

From JReality Wiki
Jump to: navigation, search
Main Page: Contents

Getting started with the JRViewer application

This tutorial is based on JRViewer, a Java webstart applications based on jReality. As such, it can be run from any computer connected to the Internet. You only need a relatively up-to-date version of Java (Java 6+) to get started. Check this document for help if you have problems.

As you work through this tutorial, you may wish to consult the following documents which describe more conceptually how jReality works:

To begin the tutorial, start up JRViewer. JRViewer is a configurable viewer based on plugins; the version we use in this tutorial is a simple one designed to help beginners learn about its functionality.

If successful, a window should appear that looks like the image below. The navigator panel on the left side allows you to inspect the jReality scene graph. The other window, currently empty except for a background color gradient, is the 3D graphics window. You may have a menu bar at the top of the window, depending on your operating system.

JRViewer at startup

Check whether the "Viewer" menu contains "de.jreality.jogl.Viewer" then the jogl backend with hardware OpenGL support is available. If there is only "de.jreality.softviewer.SoftViewer" then you don't have hardware support yet. You can still do most of the things in this tutorial. See the getting started document for instructions on installing jogl.


It is possible to configure JRViewer to provide a virtual reality environment JRViewerVR which provides more direct access to features of video games, such as skyboxes, reflection maps, and sophisticated navigation. This tutorial applies with minor changes to JRViewerVR, see Using ViewerVR application.

Loading Geometry

We'll load a simple geometric object into our viewer. First copy this text into a file named and save it somewhere on your computer. Then, choose File->Load content from the application menu. In the open dialog box, go to the location of the file you just saved and select it. You should see something like the following:

After loading a dodecahedron

You can rotate the object by dragging with the left mouse. You can translate by dragging with the middle mouse. The effects of the mouse actions depend on the tools installed in your scene graph. To learn more about jReality tools, see Tools.

If you zoom out and then type the 'e' key, the standard encompass tool is activated, and the object should once more fill the window. This is done by moving the camera, not changing the camera's field of view. See Setting the camera for more details on the camera.

Supported file formats

jReality can import a variety of 3D file formats, including:

Setting appearance attributes

In this lesson you'll learn how to use the Navigator panel to change appearance attributes, which control how the scene is rendered.

The navigator panel consists of a so-called tree view of the scene graph. Each node is listed by its name and different node classes are marked with different colored icons. If a node has children, it can be opened and closed to display its children by clicking on the symbol (grey triangle or circle switch) on the left side of the node. You can select a node by clicking on it. The bottom of the navigator contains an inspector panel for the selected object, where you can set values for the fields within the node.

Toggling display of faces, lines, and points

  • Open up the node labeled root appearance.
  • Select the node labeled DefaultGeometryShader.
  • At the bottom of the panel, set the value of the showFaces field to false in the pull-down menu.
  • The faces of the dodecahedron should disappear.
  • You can conduct similar experiments with the other fields here.

Changing material properties

  • Toggling smooth shading
    • Return all the fields above to their original values, so that faces, lines and points are all drawn.
    • In the tree view, burrow down from the DefaultGeometryShader to the DefaultPolygonShader.
    • In the inspection panel, set the field smoothShading to false. Now, when you rotate the dodecahedron, the lighting looks more reasonable.
  • Changing display of the lines
    • In the tree view, burrow down from the DefaultGeometryShader to the DefaultLineShader. These parameters control the display of the edges of the object.
    • Set the field tubeRadius to .05. The tubes should get bigger.
      • You can click on Inherit to return them to their default size.
    • Click on the button (color swatch or label "inherited") next to the diffuseColor field.
    • A color chooser should appear. Select for example a red color, and click OK.
    • The tubes should appear in red now.
  • Changing display of the points
    • In the tree view, burrow down from the DefaultGeometryShader to the DefaultPointShader. These parameters control the display of the vertices of the object.
    • In the pointRadius field enter .1. You should see the vertices become larger.
    • Click on the button (color swatch or label "inherited") next to the diffuseColor field.
    • A color chooser should appear. Select for example a yellow color, and click OK.
    • The tubes should appear in yellow now.
After changing appearance attributes

Changing transparency

There are several ways to create transparent objects in jReality. Here you'll learn about the simplest ones. In the process you'll learn about jReality backends, and how they offer different features.

By default, transparency is not enabled in the viewer, since the default backend uses the OpenGL graphics package. Because it is based on a depth-buffer rendering package, it's not possible to render transparent layers correctly unless the objects are rendered in sorted order, and this is not yet implemented.

The software jReality backend, however, does render transparency correctly, although naturally it is slower than the hardware accelerated OpenGL backend.

There are situations where OpenGL does a reasonable job rendering transparent objects, as the following example shows.

  • Activate transparency.
    • In the navigator, select the DefaultPolygonShader within the DefaultGeometryShader.
    • In its inspector, set the value of the transparency field to .5. This won't have any effect yet.
    • In the navigator, select the RenderingHintsShader within the root appearance node.
    • In its inspector, set the value of transparencyEnabled to true, and
    • also set the value of opaqueTubesAndSpheres to true.
    • In the 3D window, you should see the dodecahedron with transparent faces, and opaque edges and vertices.

In this example the OpenGL viewer does a good job. The general rule is that transparency works best when there are no more than 2 transparent layers, and when all transparent geometry are rendered after all opaque geometry. These conditions are fulfilled by polyhedra in jReality, since the vertices and edges (drawn opaquely) are rendered before the faces. It's important that the edges are rendered opaquely since they provide the essential 3D structure to the eye.

But in cases where OpenGL does a bad job, you can get better pictures by selecting the menu item menu item View->de.jreality.soft.SoftViewer, which renders transparency correctly.

[Note: Transparency can also be generated via texture maps or colors attached to the geometric primitives, for examples, face or vertex colors. Such colors may have a fourth, or alpha, channel, which is the additive inverse of the transparency. So, an alpha channel value of 1 corresponds to transparency 0, etc. See using the bean shell for an example of loading a transparent texture]

Transparent polyhedron

The rendering hints shader

In addition to polygon, line, and point shaders each geometry shader also includes a rendering hints shader. This shader contains a variety of settings (mostly of type boolean) which allow backends to determine which style or quality of rendering to use. The most important of these are:

Field name Description Default Backends
lightingEnabled Whether to invoke shading model using lights true jogl
tranparencyEnabled Whether to invoke transparency true All
ZBufferEnabled If transparency enabled, use z-buffer? false jogl
opaqueTubesAndSpheres Draw tubes/spheres for edges/vertices opaque? true jogl
backFaceCulling Reject back face polygons w/o rendering false jogl
localLightModel Direct pass-through to openGL function true jogl
separateSpecularColor Direct pass-through to openGL function false jogl
anyDisplayLists Use display lists when possible true jogl
ignoreAlpha0 Fragments with alpha=0 rejected true jogl
depthFudgeFactor Float parameter <=1.0 for drawing lines on surface 1.0 jogl
levelOfDetail Level of detail, between 0 and 1 1.0  ??

To get a better feel how these fields work, just play around with the rendering hints shader in the top-level appearance.

Setting the camera

The jReality camera is a part of the scene graph. In this way it is given a position and orientation in the scene. The camera settings can be accessed in the navigator panel.

When using the JRViewer application, the camera can be found by selecting the path "avatar->cameraNode->camera". Some of the fields are not useful for this tutorial. These include onAxis, FStop and focalLength. The other parameters are described below.

Before inspecting the camera, invoke the encompass tool (type the e key). This tool sets some of the camera parameters to display the scene optimally.

Camera parameters

  • near and far control the distance of the near and far clipping plane.
  • fieldOfView controls how wide an angle the camera sees (input is in degrees, not radians!).
  • perspective toggles whether the camera uses a perspective (closer objects appear larger) or an orthographic (parallel) projection.
    • The orthographic view works best if the focus value has been set to be the distance of the middle of the scene from the eye. The encompass tool attempts to set this to a reasonable value. Otherwise the scene can suddently appear much smaller or larger than the perspective view.
  • focus and eyeSeparation control the behavior of the camera in stereo mode.
    • focus determines the distance of the plane in which the left and right eye lines cross. If an object lies in this plane, the two eyes see identical images.
    • eyeSeparation determines how far apart (in world coordinates) the eyes are. For best results, this should be a fraction of the focus (between 1/12 and 1/24 are reasonable values).
    • The encompass tool (e) attempts to set these values reasonably.

Stereo operation

If you set the field stereo to true, you should see two copies of the scene. This is so-called cross-eyed stereo display mode. To fuse the two images, let your eyes cross gently until the middle two images (of the total 4) are aligned with each other. This overlapping image should appear in 3D. For this to function properly, the focus and eyeSeparation fields must be properly set.

Cross-eyed stereo

Certain operations (like picking) don't work properly in stereo mode.


Select the scene node. Invoke the Edit->Add tool option. In the dialog panel that opens, choose the PickShowTool. Now, when you move the cursor over the geometry, you should see a small sphere. As you move from face to face, the color of the sphere changes from yellow to green and back. Over a vertex, it turns purple. The generic jReality tool extends this simple tool, to perform an action based on the movement of the pick point. For further information on tools see Tools.

Using the bean shell

The Java language supports run-time reflection, allowing one to treat Java as an interactive scripting language. JRViewer supports this facility by offering a so-called "bean shell".

To begin with, remove any geometry which you've loaded by selecting it and using the Edit->Remove menu item and select the scene node, or quit JRViewer and start it up again. Then, to invoke the JRViewer bean shell, activate the menu item Window->Bottom Slot. By default the BeanShell frame appears in the bottom slot of the application. By clicking on the title you can unfold the widget. If you want the BeanShell in a separate window just drag the title of the widget. You should see a window something like the following:

JRViewer Bean Shell

Choose the node content from the Navigator. Then on the bean shell window, and type self, then enter. You should see a display something like: content [de.jreality.scene.SceneGraphComponent]

This is a text form of the scene graph component named content. If you select another node in the Navigator, you'll see that the value of self in the bean shell is set to this new value. But we'll work now with content.

You can also write values, not just read them. Type self.setName("Content") followed by enter. The shell echoes null since that's the return value of the setName() method. But if you look in the Navigator panel, you should see that the name there has changed from content to Content. You might have to click on the node to make the change appear in the Navigator.

We'll use this feature to load some geometry. Type self.setGeometry(Primitives.cylinder(20)). In the 3D window you should see a cylinder, end-on. Type e to encompass it, and rotate it for a sideways view. Then, use what you learned above to turn off edge and vertex rendering, and set the polygon diffuse color to white. You should see something like this:

Cylinder via bean shell

Finally, we can attach a texture map to this object. First of all, save off


in the same location as you saved above. (Use right mouse to get a context menu for saving it). Name it gridSmall.jpg. Right click the content node in the Navigator to get a context menu for it and use Appearance->Load texture. In the file dialog which appears load the file gridSmall.jpg. Now you should see something like:

Texture via navigator

Select the texture object in the navigator by following the path Content->content app->DefaultGeometryShader->DefaultPolygonShader->Texture2D. In its inspection panel you see a field named scale. Set that to 5.0. This has the effect of repeating the texture the same number of times in the u and v directions.

Advanced editing using bean shell

Coupled with the Javadoc for jReality, the bean shell can be a powerful tool for prototyping and testing. We'll show here how to set some methods on the texture above using the bean shell.

It may be that we want to draw different number of copies of the texture in the u and v directions. To do this, we need to know a bit more about the Texture2D class in jReality.

In the Javadoc for jReality, select the package de.jreality.shader and the interface Texture2D. Unfortuneately the documentation is sparse, but you should still be able to locate a method setTextureMatrix(Matrix m). To get more copies, we need to set this matrix to a scaling matrix with the first two entries the scaling factors for the u and v directions, resp. Suppose we decide we want factors of 10 in the u and 5 in the v direction.

Here's what to type in the bean shell. First make sure that the Texture2D instance is selected in the navigator.

>Matrix m = new Matrix()

Texture scaling via Javadoc and bean shell

This shows how you can play around and experiment with the many methods available in jReality which are not directly available via the inspection panel.


Each jReality scene graph component can contain a transformation, a 4x4 real matrix specifying the linear transformation which is applied to the scene graph rooted at this node before traversing its children.

In order to play around with the transformation inspector, it's useful to first set up a scene using the bean shell.

  • Remove any children from the scene node or start up JRViewer afresh.
  • Make sure content is selected in the Navigator.
  • Make the bean shell visible.
  • Type the following commands into the bean shell:

>child=new SceneGraphComponent("child")
child [de.jreality.scene.SceneGraphComponent]
>child.setTransformation(new Transformation())

  • A colored cube should appear in the graphics window. You can encompass and rotate it to bring it into a generic position.
  • In the Navigator, open up the content node, then the new node you created named child, and select the transformation node there.
  • In the inspector panel you should see slots where you can set the translation, rotation, and scale of the object.
  • Enter some non-unit scale factors. The values 2, .8 and 1 were used to create the following picture:
Scaled cube
  • Set the scale factors back to (1,1,1) here.
  • Select the transformation for the content node.
  • Repeat the experiment with the scale factors. The picture should look the same.
  • But then proceed to use the rotate tool. The scale and the rotate interfere with each other in strange ways! This is why we used the bean shell to construct a node with its own transformation independent of the rotation tool!


Use the menu item File->Export to export the current selected jReality scene graph. The following options are available:

Menu entry Description
RIB RenderMan 3D scene description
U3D Adobe 3D format
PDF U3D file embedded in a PDF document
PS PostScript
STL Stereo lithography format
Image Offscreen rendering
Sunflow Java raytracer

Notice that the last two export types create images, not 3D descriptions. The offscreen rendering is performed by the JOGL backend and can render images up to 8Kx8K with 4x4 supersampling. Be sure you have enough memory. Additionally, if you draw points or lines in non-sphere or non-tubed mode, be aware that the size or thickness of the points, resp. lines, will be reduced by the supersampling factor you choose. This should probably be fixed in jReality but until it is, you'll need to make your points and lines thicker before performing the offscreen render. Another reason to use spheres and tubes!

The sunflow backend is still under development. You may notice that certain features are missing or incorrectly implemented. Please report problems to the jReality forum.

Of course, not all features of the jReality scene graph can be mapped onto features of the various 3D output formats.

More detailed descriptions of writing Renderman and U3D files can be found on the following pages.

Export Renderman files

Export U3D files

Display Mathematica graphics

Using JRViewerVR application

This user tutorial applies to JRViewerVR with the following changes. See also the ViewerVR User Manual.

  • The scene graph navigator widget is in the right application slot by default and can be shown via Window->Right slot
  • Many appearance attributes can be edited via the Content Appearance panel in the left slot. This implies that changing attributes in the root appearance have no effect on the content. You'll have to edit the content->content app instead.
Octahedron in JRViewerVR

Previous: Main Page User Tutorial: Contents Next: ViewerVR User Manual