{"id":3080,"date":"2019-09-24T03:05:00","date_gmt":"2019-09-24T03:05:00","guid":{"rendered":"https:\/\/www.migenius.com\/?p=3080"},"modified":"2020-10-15T01:19:51","modified_gmt":"2020-10-15T01:19:51","slug":"introducing-realityserver","status":"publish","type":"post","link":"https:\/\/www.migenius.com\/articles\/introducing-realityserver","title":{"rendered":"Introducing RealityServer"},"content":{"rendered":"\n

RealityServer is a platform for integrating photorealistic 3D rendering into your application. It is based on a web services methodology and can be used both for rendering automation and fully interactive rendering. In this introduction we will cover the core concepts of RealityServer development and what you need to understand in order to get started.<\/p>\n\n\n\n\n\n\n\n

\"\"
Image by Floorplanner<\/figcaption><\/figure>\n\n\n\n

Development with RealityServer is easy! However it helps enormously to be familiar with the overall architecture before diving in. Being a very extensive and generalised platform, it can be a little difficult understanding where to get started. We therefore strongly recommend anyone who is new to RealityServer thoroughly review the material presented here.<\/p>\n\n\n\n

Before getting started, please follow our RealityServer Installation Guide<\/a> for instructions on getting your server up and running. The installation guide also covers the directory structure of RealityServer and where to find things. There are several parts below where we will refer to resources available on the server for you to access, so it’s good to have one running.<\/p>\n\n\n\n

Intended Audience<\/h3>\n\n\n\n

RealityServer is a platform for software developers and is not intended to be an end-user product. If you are not comfortable with the command line, a text editor and coding then RealityServer is likely not well suited to your needs without assistance from an experienced developer. However migenius does offer software development services<\/a> if you want us to build your application for you or help you with integration.<\/p>\n\n\n\n

We’ll focus on web technologies here, however RealityServer is not limited to use with web applications. Anything that can talk to a web server can work with RealityServer, so virtually every modern programming language and tool. Here though, we’ll cover the most commonly used techniques for working with RealityServer.<\/p>\n\n\n\n

What will not be covered here are the details of what RealityServer is from the product perspective. The assumption is you have already determined you are interested in RealityServer and want to get to work developing something. If you want to know more about whether RealityServer is the right product for you, please get in touch<\/a>.<\/p>\n\n\n\n

Fundamentals<\/h3>\n\n\n\n

The following three key concepts are critical to understanding the architecture of RealityServer. We describe them here without reference to the specific technologies used, just the fundamental ideas. It is important that these concepts make sense to you before proceeding.<\/p>\n\n\n\n

Commands<\/h4>\n\n\n\n

These are just like functions in your favourite programming language, they have names and parameters, except they run remotely on the server. Executing a command is what causes RealityServer to actually do something.<\/p>\n\n\n\n

Client<\/h4>\n\n\n\n

The client tells RealityServer which commands to run. Anything that can communicate with RealityServer can be a client. The client will typically also do something with the results sent back by the server after it executes the requested command (for example display an image).<\/p>\n\n\n\n

Server<\/h4>\n\n\n\n

This is where the commands are defined and actually execute. RealityServer hosts multiple programming APIs with which you can program your own commands (and it comes with many built in commands).<\/p>\n\n\n\n

Architecture<\/h3>\n\n\n\n

Now let’s talk about the specific technologies. RealityServer uses an RPC (Remote Procedure Call<\/a>) client\u2013server model. While RESTful<\/a> tends to be a more popular model for client\u2013server architectures today, its stateless nature makes it a poor choice for RealityServer. State data for 3D applications can easily reach into the gigabytes so would be expensive to recreate for each request.<\/p>\n\n\n\n

To make RPC requests to RealityServer you use the JSON-RPC 2.0<\/a> protocol over HTTP. This is very lightweight and easy to understand. It is also possible to send commands over a WebSocket<\/a> connection which has many advantages (e.g., lower latency and server-push). Either way you are performing the same basic operation, asking RealityServer to perform a task (run a command or commands) and give you the answer.<\/p>\n\n\n\n

Spin up your RealityServer and let’s call a command. You can make a JSON-RPC request using anything that can send HTTP POST requests. For example using cURL<\/a> on the command line (Postman<\/a> is another great tool for making calls like this). Here is a really basic one using cURL.<\/p>\n\n\n

\ncurl -X POST -H "Content-Type: application\/json" -d '[\n    {"jsonrpc": "2.0", "method": "echo", "params": {\n        "input" : "Hello world!"\n    }, "id": 1}\n]' "http:\/\/127.0.0.1:8080\/"\n<\/pre><\/div>\n\n\n
This is calling a very simple built in command called echo<\/em> which takes a single parameter input<\/em>. In the JSON-RPC structure above, you might notice the command is in an array (even though it’s just one command). You can put multiple commands in the array and they will execute as a batch<\/em> in order. If you run the above you should get back something like this from the server.<\/p>\n\n\n
\n[{"id":1,"jsonrpc":"2.0","result":"Hello world!"}]\n<\/pre><\/div>\n\n\n
Not very glamorous but you’ve just exercised all of the fundamental pieces of the RealityServer architecture, command (echo), client (cURL) and server (RealityServer). Everything else you will do builds on this basic process. While you may not ever construct commands manually like this, it is important to understand that they are there and that higher level abstractions are doing this under the hood.<\/p>\n\n\n\n
We have another article on Exploring the JSON-RPC API<\/a> which is worth a read and goes into some additional detail on calling this API from other languages which might be helpful if you cannot make use of our client libraries.<\/p>\n\n\n\n
Client Library<\/h3>\n\n\n\n
Calling the JSON-RPC API directly is great for testing simple sequences of commands and working through issues, however you will generally want to use something higher level to send your commands to RealityServer. For this purpose we provide the RealityServer Client<\/a>.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
The RealityServer client can be used both directly from a supported browser (all modern browsers should work) or alternatively from Node.js<\/a> or both. The link above takes you directly to the documentation for the RealityServer Client which contains a detailed step-by-step tutorial for both the browser and Node.js cases where you build up a very simple application.<\/p>\n\n\n\n
We strongly recommend using this new client library<\/strong> and ignoring the examples and deprecated JavaScript Client Library that are provided with RealityServer itself (they will be removed at some point). The step-by-step tutorials in the RealityServer Client will get you going quickly.<\/p>\n\n\n\n
The purpose of the client library is to facilitate sending commands to RealityServer and managing the communication. Instead of using JSON-RPC over HTTP, the client library utilises a WebSocket based connection and custom protocol to improve performance. We’ve written an article going into more detail on the client library here<\/a>.<\/p>\n\n\n\n
Custom Commands<\/h3>\n\n\n\n
While it would be possible to just use the built in commands<\/a> and call them through the client library, this makes for a lot of back and forth between the client and server and isn’t particularly programmer friendly. To help make life easier RealityServer provides two methods for adding your own custom commands to the system.<\/p>\n\n\n\n