Getting Started with RealityServer

So you have obtained RealityServer and installed your license server, what now? We frequently get questions about the best place to start learning about RealityServer and how to use it. As RealityServer is a large, very generalised platform it can be difficult to know where to start. This article provides some pointers on where to start and the best way to learn the basics.

Assumed Knowledge

RealityServer is a platform for software developers and specifically those who want to incorporate photorealistic 3D rendering into their applications. While we believe almost any software developer can learn to use RealityServer there is some basic knowledge that we are assuming you will have if you are reading this article. The following describes the assumed knowledge in more detail, expand each to see the full details.

Comfort with Command Line Tools

RealityServer has no user interface and is entirely managed from the command line and through editing of configuration files. You will therefore need to be comfortable using shell commands on your chosen platform. It is not important which shell you use but you will need a general experience with using shells. You will also need to be able to read the log output which RealityServer outputs which frequently contains useful diagnostic information.

General Web Development Concepts

While not strictly only used for web based applications, many of the examples utilise web concepts. We therefore assume that you are familiar with all of the basic principles of web development, including:

  • HTTP Protocol (general understanding needed)
  • HTML (mainly HTML5 used by RealityServer examples)
  • CSS (not heavily used by RealityServer examples)
  • JavaScript (can be used on both client-side and server-side)
  • JSON (Used extensively by JSON-RPC and in other areas)

This list is not exhaustive and only includes the basic technologies needed to understand the examples. When building a modern web application you will likely be integrating with many other frameworks and technologies not listed here.

Web Services

RealityServer at its core uses JSON-RPC 2.0 web services to enable you to trigger actions on the server and receive responses. While we provide some libraries that abstract out the JSON-RPC protocol so you don’t have to implement the low level functionality you should still understand what JSON-RPC is and how it works, particularly the JSON-RPC 2.0 standard used by RealityServer.

Take the time to read the specification listed above, it’s really short and simple (part of the advantage of using JSON-RPC over something like SOAP or XML-RPC). While you don’t need to frequently use every part of it you need to understand the concepts of commands, parameters and batches as a minimum. This will make the example code much easier to understand.

Why not a REST API? We get asked this frequently since RESTful web services are a common trend now. While there are many advantages to RESTful services, RealityServer is fundamentally stateful. This is mainly because it is desirable to retain complex 3D data in memory rather than reload it on every request. It is of course perfectly possible to write your own service proxy that wraps the RealityServer JSON-RPC service in a RESTful API if you wish.

3D Graphics

If you are working with a partner to create your 3D content then you may only need enough 3D graphics knowledge to manipulate your content rather than create it. Assuming you are having your content build by someone else, you should at least have a grasp of the following concepts:

  • Matrix Transformation (specifically affine world to object transforms)
  • Polygonal Geometry (vertices, faces, normals and connectivity)
  • Scenegraph Structures (groups, instances and hierarchy)
  • Basic Rendering (camera, tone-mapping, lighting, materials)

You can do a lot in RealityServer just by loading content and rendering it however most people will want to manipulate the content in some way and having a basic understanding of the above concepts can help a lot. If you are also preparing the content yourself then you will need content creation experience with a tool that can output something supported by RealityServer (e.g., 3ds max, Maya or anything that can write Wavefront OBJ data).

Optional Knowledge

The following items are not needed for all RealityServer users however if you have knowledge in these areas you can significantly extend the functionality of RealityServer.

Advanced C++ Programming

In addition to accessing RealityServer through the web services, you can further extend RealityServer by writing C++ plugins which are loaded and used on the server-side. This includes the ability to write plugins for the underlying Iray rendering platform. This is an advanced topic not covered here other than pointing to the included source code examples. If you wish to take on such development you will need strong C++ experience including working with heavily templated classes, handles and reference counting systems.

HAProxy

When building a production level system, RealityServer is frequently accessed through a reverse proxy and often using load balancing features or user limiting functionality. RealityServer now ships with advanced plugins to integrate directly with HAProxy and communicate with the reverse proxy server to dynamically adjust load balancing rules. In order to utilise these features you must have a solid understanding of HAProxy.

Installation

We are assuming here that you have been able to install RealityServer and obtain your licenses. Licensing instructions are available in your release email, if you require any assistance please email support@migenius.com or your dedicated support address if you were provided one. RealityServer is provided as a compressed tarball file with a name something like this:

rsws-43-1346.162.tgz

The format for the name is rsws-{major}{minor}-{branch}.{build}.tgz so you can tell immediately which version you have. The above example is for RealityServer 4.3 build 1346.162. If you have any issues with RealityServer you should always quote your full version number when reporting problems.

RealityServer does not have an installer or a graphical user interface, you simply extract it to your desired directory and run it. Under Linux this would be done as follows (obviously change the filenames accordingly):

 mkdir -p /usr/local/migenius
 cd /usr/local/migenius
 tar zxf rsws-43-1346.162.tgz
 cd rsws-43-1346.162
 ./realityserver_ws

Under Windows you may need to download a tool that supports the .tgz file format such as 7-Zip or WinRAR. You can also use Cygwin or MingW however note that the shell scripts for starting RealityServer won’t work under Windows, you need to use the batch file instead. Under Windows, after extracting with your favorite tool start RealityServer as follows:

  1. Press Windows+R to bring up the _Run_ window
  2. Type cmd into the Open field and press OK
  3. At the command prompt enter c: to ensure you are on the right drive
  4. Next enter cd\migenius\rsws-43-1346.162 to enter the directory
  5. Now enter realityserver_ws and press enter

Once RealityServer is running you should see a lot of log output, the last part of which should look similar to the following:

 15/12/02 10:22:20 1.1 PLUGIN main info : RealityServer(R) Web Services plugin initialized.
 15/12/02 10:22:20 1.1 ICB io info : cb_importer (build 246000.8334, 16 Nov 2015) initialized
 15/12/02 10:22:20 1.1 IRAY_C net info : iray_bridge_snapshot (build 246000.8334, 16 Nov 2015) initialized
 15/12/02 10:22:20 1.1 IRAY_C net info : iray_bridge_server (build 246000.8334, 16 Nov 2015) initialized
 15/12/02 10:22:20 1.1 EEMI io info : .mi exporter (build 246000.8334, 16 Nov 2015) initialized
 15/12/02 10:22:20 1.1 EIMI io info : .mi importer (build 246000.8334, 16 Nov 2015) initialized
 15/12/02 10:22:20 1.1 PLUGIN main info : OBJ importer v3.0.0.15 (build 1346.162, 23 Nov 2015) loaded.
 15/12/02 10:22:20 1.1 PLUGIN main info : Render loop plugin initialized
 15/12/02 10:22:20 1.0 PLUGIN main info : The iray renderer will use GPUs 1, 2 and CPUs
 15/12/02 10:22:20 1.0 PLUGIN main info : The irt renderer will use GPUs 1, 2 and CPUs
 15/12/02 10:22:20 1.0 PLUGIN main info : Create RealityServer(R) Web Services
 15/12/02 10:22:20 1.0 PLUGIN main info : HTTP server configured to listen on 0.0.0.0:8080.
 15/12/02 10:22:20 1.0 PLUGIN main info : RTMP server configured to listen on 0.0.0.0:1935.
 15/12/02 10:22:20 1.0 PLUGIN main info : Starting RealityServer(R) Web Services
 15/12/02 10:22:20 1.0 RTMP net info : RTMP server listens on 0.0.0.0:1935
 15/12/02 10:22:20 1.0 TMOUT main info : Not installing Timeout HTTP handler as it is not configured correctly or has a zero period.
 15/12/02 10:22:20 1.0 PLUGIN main info : Not installing CORS HTTP handler as it is not configured.
 15/12/02 10:22:20 1.0 PLUGIN main info : Render loop command plugin initialized
 15/12/02 10:22:20 1.0 PLUGIN main info : Installed falsecolor render loop handler.
 15/12/02 10:22:20 1.0 PLUGIN main info : Installed default render loop handler.
 15/12/02 10:22:20 1.0 UAC_HA main info : Not installing UAC HAProxy manager plugin as it is not configured.
 15/12/02 10:22:20 1.0 PLUGIN main info : The command in the file 'C:\Users\arden\Desktop\rsws-43-1346.162\javascript_services\check_render_capabilities.js' has just been added.
 15/12/02 10:22:20 1.0 PLUGIN main info : The command in the file 'C:\Users\arden\Desktop\rsws-43-1346.162\javascript_services\create_texture.js' has just been added.
 15/12/02 10:22:20 1.0 PLUGIN main info : Started RealityServer(R) Web Services.
 15/12/02 10:22:20 1.0 PLUGIN main info : The command in the file 'C:\Users\arden\Desktop\rsws-43-1346.162\javascript_services\echo.js' has just been added.
 15/12/02 10:22:20 1.0 PLUGIN main info : The command in the file 'C:\Users\arden\Desktop\rsws-43-1346.162\javascript_services\log_render_capabilities.js' has just been added.
 15/12/02 10:22:20 1.0 PLUGIN main info : The command in the file 'C:\Users\arden\Desktop\rsws-43-1346.162\javascript_services\log_scene_structure.js' has just been added.
 15/12/02 10:22:20 1.0 PLUGIN main info : The command in the file 'C:\Users\arden\Desktop\rsws-43-1346.162\javascript_services\pick_item.js' has just been added.
 15/12/02 10:22:20 1.0 PLUGIN main info : The command in the file 'C:\Users\arden\Desktop\rsws-43-1346.162\javascript_services\use_camera.js' has just been added.

This output will update as you take actions with your server and should be monitored, particularly during development phases. If you wish to redirect the output to a file you can do so as follows (on Windows drop the dot forward slash from the start):

./realityserver_ws > rs.log 2>&1

You will find this useful if you want to keep the log data, for example to send to support. Note that you can also add a log_file directive to the realityserver.conf file to achieve the same effect, however when getting started it can be more convenient to just use redirection.

To stop RealityServer just press Ctrl+C and it will perform a clean shutdown for you. The rest of this guide assumes you have a running RealityServer with the default settings. If you have modified your settings some of the instructions will need to change accordingly.

Where Do I Start?

The most frequent question we get with RealityServer is where to start and where the documentation is. The issue here is that while the documentation and examples are comprehensive it isn’t necessarily clear where in this material to begin your journey with RealityServer. What follows are the recommended first steps for someone who doesn’t necessarily have a specific use-case in mind (though you should definitely try and think about your use case before approaching RealityServer).

Verify Your Installation

Your absolute first step after installing and running RealityServer is to confirm that it is working correctly before going further. The easiest way to do this is to open your browser and navigate to:

http://127.0.0.1:8080/

This assumes you are accessing RealityServer from the same machine as it is running on. If you are remotely accessing RealityServer simply change 127.0.0.1 to the hostname or ip address of your RealityServer machine. Likewise the port 8080 is the default RealityServer port, if you reconfigured this then change that too. The above should give you a page like the following:

RealityServer Homepage

There are many useful links on this page and you should come back here and explore later. However for now you will want to click on the Simple JavaScript Render Loop rendering sample which will launch a small example that will actually do some rendering. The page should look like the following image if everything is working:

Simple JavaScript Render Loop rendering sample

If you are getting this image then everything is up and running. If you are not seeing this then please email support@migenius.com to get some help diagnosing what is going wrong. Note that you can also drag on the image and it should orbit around the object interactively. When you stop the rendering should refine.

Examine the Renderloop Example in Detail

Now that you have confirmed that everything is running, the best way to understand how RealityServer actually works is to examine the previously mentioned Renderloop Example in full detail. You will note that the example is served from RealityServer itself. RealityServer has a built in web server and this is what you are accessing when navigating to the URL mentioned above. The web server serves content found in the configured directory of your RealityServer installation. Take a look in the following directory of your RealityServer installation:

content_root/applications/renderloop_demo

This is the complete source code for the RealityServer application you were just viewing. The application is served to the browser and the JavaScript code found in index.html and included files runs on the browser, this in turn calls the JSON-RPC web services of RealityServer to load the scene, manipulate it and render images.

The application code for the Renderloop Example uses what we call the JavaScript Client API. This is a JavaScript library that you can use in your browser that handles all of the marshaling of web service requests and provides various convenience functions to speed up development. You do not have to use this and can call the JSON-RPC services directly however if accessing RealityServer from the browser it can greatly simplfy things. The full source code for the JavaScritp Client API can be found here:

content_root/client_libraries/javascript

There is also documentation in the RealityServer Document Center that is linked to the RealtiyServer homepage on your server under Client APIs → JavaScript Client API. The Renderloop Example uses the client library heavily but it is still quite clear which commands are actually being used.

We strongly recommend reading through the full source code of index.html for the Renderloop Example. The main RealityServer related code starts at line 249 and is heavily commented throughout explaining exactly what each step does. This example covers the basics of loading a scene, progressively rendering the scene and displaying the results in the browser.

As an exercise we recommend you try to make the following changes to the RenderLoop Example to test your understanding of the code you have reviewed.

  1. Change the example to load the solids.mi scene file instead of meyemII/main.mi.
  2. Change the rendering mode from iray to irt.
  3. Add a button that resets the camera to its home position.
  4. Grab a Wavefront OBJ (.obj) model from the Internet and load it.

After reviewing this example you will have a considerable base of general RealityServer knowledge with which to look at other aspects of the platform in detail. While the Renderloop Example is somewhat long almost all of the code is actually comments.

Hint: Above we talk about changing the scene you are loading as an example exercise to perform. Scene data can be installed anywhere in your content_root folder and is referenced relative to that location. If you look in content_root/scenes you will find the pre-installed example scenes that come with RealityServer.

We cannot emphasise enough how important it is to explore this example code before attempting to understand other aspects of RealityServer. The Renderloop Example is really the simplest useful application you could build with RealityServer. If you do not understand the concepts used in this application you will not be able to understand more complex concepts in RealityServer.

Explore the Playground

Back on the RealityServer homepage on your server, you will see a link titled RealityServer Code Playground. This is an interactive set of RealityServer examples that show you how to perform common operations like loading a scene, manipulating the camera, changing renderer, modifying materials and lighting, and several other tasks. The Playground also lets you see and edit the actual code that it is running so you can learn more about how it is working. Your Code Playground page should look like this:

RealityServer Code Playground

We strongly recommend the above step of reviewing the source code of the Renderloop Example prior to using the Code Playground since many of the code examples are effectively just modifications of the same code used in the Renderloop Example. There is a lot of boiler plate code you are not seeing which is shown in the Renderloop Example and you need to be aware of it.

Check Out the Non-Browser Examples

Not everyone wants to use RealityServer from the browser. Some may want to integrate it with other server-side application logic or even use it from the command line for automated rendering tasks. To provide an example of a more direct use of the JSON-RPC services without the JavaScript Client API and use out of the browser we ship some examples that use Node.js, a popular JavaScript runtime that can run as a command line tool or form the basis for a complete server-side stack. The Node.js examples can be found in the following directory:

src/nodejs_demos

Three examples are provided along with a README.md file explaining how to use them. You will need Node.js installed and need to run the module install process described in the README in order to use the examples. However even if you don’t plan to run them examining the code can also help reveal a lot about how to go about directly accessing the JSON-RPC services.

Examine the List of Available Commands

On the RealityServer homepage on your server you will see a link for Command Documentation. This contains a list of all commands available on your server (including custom server-side JavaScript commands or C++ plugin commands you may have added). Here is a direct link to the documentation (again, change the IP address if needed):

Command Documentation

You will refer to this often and it is likely to become the most common piece of RealityServer documentation you view. The page contains detailed documentation for every command that can be accessed through JSON-RPC web services and represents the set of functionality you can use.

Get Familiar With Important Documentation

You likely won’t need to read all of the RealityServer documentation and the pages you will need will depend heavily on your use case. However you will need to be familiar with where to find everything. This is all centralised in the RealityServer Document Center which is also linked to from the RealityServer homepage on your server. It should look something like this:

RealityServer Document Center

The menu bar across the top contains links to all of the included documentation. Below we will describe the most useful of the documentation sections that we find people need to access the most frequently. Please note, you should still explore other areas of the documentation if your use case isn’t covered in these sections. Note that you can also search the Document Center from the search field in the top right.

Getting Started → Iray Programmer’s Manual

Here we have a complete set of Iray documentation for the NVIDIA Iray rendering engine that is included inside RealityServer. This will launch in a separate tab/window and should be your first port of call when you are looking for anything to do with settings in the Iray renderer itself as well as details of the rendering modes and their various advantages and disadvantages.

There is also a great section called Physically plausible scene setup describing how to ensure your scene is correctly setup for physically based rendering. Basically everything you will want to set with the element_set_attribute command that has to do with rendering will be found here so you are likely to be referring to this set of documentation frequently.

Getting Started → RealityServer Configuration

While you can use RealityServer in its default configuration you will very likely want to adjust some of the settings for your own purposes. This section describes all of the supported configuration directives that can be used in the realityserver.conf file found in your installation directory as well as the command line parameters RealityServer accepts. The Networking Directives and Logging Directives are the most commonly used ones.

Server APIs → Server-Side JavaScript

A PDF document is linked to here which describes a plugin system that ships with RealityServer that allows you to write new commands that can be accessed just like built-in commands. The new commands are written in JavaScript and installed in:

javascript_services

You can find several example commands in this directory which you can copy and modify. Server-side JavaScript commands are great when you have a frequently used operation that involves a complex sequence of built-in commands, particularly where the flow may depend on the result of some of the commands or the input of one command relies on the output of another.

Normally you would need to make several round trips to the server if your command’s input depended on the output of another, however with server-side JavaScript you can package up a sequence of commands into a single command you can call with a single round trip. Typically you might use this to create convenience commands that perform common operations. Indeed the shipped examples such as create_texture.js and use_camera.js are were built exactly for this reason.

Server APIs → Command Descriptions

This is just the same link to the Command Documentation described above but linked to from within the Document Center. As mentioned above however, this is definitely an important part of the documentation and the one you are likely to access the most.

More Resources → MDL

A separate window will open when clicking this link which provides the documentation for the NVIDIA MDL (Material Definition Language). This is the system used to describe materials in the Iray rendering engine and therefore in RealityServer. An introduction is provided along with the language specification and details of the base modules that are accessible from Iray.

For a more artist-oriented introduction to MDL please see the NVIDIA MDL Handbook. Note also that all current migenius exporter tools support MDL output and now create MDL materials by default.

Exporters and Loading Content

Your RealityServer release will have shipped with an exporter for Autodesk 3ds max as well as Autodesk Maya. These exporters allow you to export content from those packages which are using supported material and lighting types (for materials Arch & Design / mia material with basic texturing is fully supported). In 3ds max you use MAX → Export and select the RealityServer MI file type and in Maya you will find a dedicated RealityServer menu with options for exporting.

RealityServer also supports loading of Wavefront OBJ files which can be exported from a wide range of software. If an associated MTL file and textures are found they will also be loaded. Finally, if you want to support other file formats or your own proprietary format you can write a custom importer plugin using the server-side C++ API.

Content is generally kept under the content_root/scenes directory however this is by convention only. The content can be placed anywhere in the configured content_root directory.

The Admin Console

One final gem which can help diagnosing various issues you might have is the RealityServer Admin console. By default this is accessible on port 8081 and so if you are browsing on the same machine as your RealityServer you would access this as follows:

http://127.0.0.1:8081/

This page is not perfectly formatted but contains some important information about the running RealityServer and in particular the database and its contents. You can search for the names of anything in the database and then examine the tags and scopes associated with them. This can be helpful when you are running commands that are not finding elements you think are in the database, or if you are wondering when things are loaded and unloaded from the database.

Going Further

This material only scratches the surface of what is possible. In particular the C++ API which is not discussed in detail here allows for a wide range of additional functionality such as custom importers, CGI request handlers, render loop handlers and many more. Many users of RealityServer are targeting unique and innovative use-cases for which there is not an already documented process. For these we recommend a consultation with migenius.

In addition to software licensing, migenius also offers software development and consultation services should you not wish to build your application or integration yourself. We are happy to chat about your application and what development options you might have so please contact us if you want help.

Paul Arden

Paul Arden has worked in the Computer Graphics industry for over 20 years, co-founding the architectural visualisation practice Luminova out of university before moving to mental images and NVIDIA to manage the Cloud-based rendering solution, RealityServer, now managed by migenius where Paul serves as CEO.

More Posts - LinkedIn

Articles Tutorials
Get in Touch