The legacy JavaScript client library shipped with RealityServer was designed in 2010, back when JavaScript in the browser was mostly unusable without some sort of framework like jQuery, WebSockets were still under design and JavaScript on the server was virtually unheard of. A lot has changed since then, JavaScript has significantly evolved and is supported by a huge module ecosystem, WebSockets are under the hood of everything and Node.js is becoming ubiquitous. The RealityServer client library however has barely changed. Until now.
The new realityserver-client is a modern, Promise based, ES6 RealityServer client library that can be used directly both in the browser and Node.js. It utilises WebSockets for all communications providing fast and efficient command execution. The WebSocket connection can stream images to the client directly from render loops and provides synchronised command execution, ensuring that no changes are lost and letting you know exactly when changes appear in rendered images.
It is available now and works with RealityServer 5.2 build 2272.266 or later. If you want to work with the source you can get it from GitHub.
realityserver-client on GitHub
It is licensed under the permissive ISC license so you can use it in all of your projects. If you just want to get going and don’t need to review the full source code you can install it directly with npm.
npm install @migenius/realityserver-client
To learn more about how to use the client library as well as how to migrate from older code we have created extensive API documentation.
realityserver-client API Documentation
If you are new to RealityServer we strongly recommend following the Getting Started sections which provide a step-by-step guide to using the API in both Node.js and your web browser. The client library is maintained separately to RealityServer itself so star and follow our GitHub repos if you want to keep track of changes and updates.
We have tried to keep the client library as tight as possible, only providing the basic scaffolding for communicating with RealityServer, executing commands, getting data back and working with common data types. However we know there is a lot of functionality many customers want to have when getting started.
realityserver-extras on GitHub / realityserver-extras API Documentation
The realityserver-extras module adds additional functionality that is frequently requested but doesn’t really fit into the core library. Right now this is mainly our RS.Camera class which provides a client-side camera representation that can be synchronised to the server and has simple functions for doing things like orbiting, dollying and so on. Like the client library you can also install the extras with npm.
npm install @migenius/realityserver-extras
We plan to extend the extras module over time with functionality that we find our customers are frequently implementing over and over again. We’d love feedback on what you’d like to see.
As most of our users know, we introduced a server-side JavaScript API for writing RealityServer commands back in RealityServer 5.0. This was based on the V8 engine and added modern JavaScript to our server-side. It has proven immensely popular and is now the main way of extending server-side functionality (of course the C++ APIs are still available when needed).
What was frustrating however was that different types were being used for things like vectors and colours between the old client library and the server-side V8 which made coding both ends a pain. When writing our new library we took the opportunity to fix this and the client-side now offers consistent classes for things like vector math and colour storage.
We also take advantage of JSON-RPC class hinting to instantiate appropriate classes where possible from server responses on the client side. This removes the need for a lot of boiler plate for extracting values into client-side classes. We think you’ll find working with both APIs now much simpler and more fluid.
To demonstrate the usage of the new client library and extras module we have created several example projects to give you a head start. A simple browser based application, a Node.js application and a modern React/MobX based application are available.
This is the example you build during the Gettting Started section of the realityserver-client API documentation. We recommend building it by following along the API documentation however if you want to check your work this is the completed version. It connects to RealityServer, streams renders and allows for camera movement and material colour change.
realityserver-client-node-tutorial
Again, this is the example you build in the Getting Started section of the API documentations and yes, we do recommend building it step-by-step from there to get a full understanding. This is a great example of how you can automate rendering from Node.js, either for server-side work or just a nice way to script your rendering tasks.
This is where things get really interesting. migenius has been building RealityServer applications for customers for many years and the React/MobX stack is the battle tested solution we now typically deploy when building these applications. This example shows how you can combine the realityserver-client with React and MobX for a truly modern application. There are a lot of advantages, especially in terms of synchronising data between the client and the server. If you are using React in your applications you’ll definitely want to check out this example. While we know MobX is used less than Redux/Redux-Saga for state management, it is becoming increasing popular and we have found it a great match for RealityServer. We strongly recommend using the approach demonstrated in this example for large scale, modern RealityServer applications. To get a feeling for how far you can take this, checkout a little video of our RealityDesigner application running inside Onshape.
It’s hard for us to stress enough how much of a step forward the new client library is over previous methods for communicating with RealityServer. If you are a modern JavaScript developer and don’t want to have to integrate old world libraries with your application you really need to check it out. For new users we think believe the new library will be much easier to learn and adapt to your own requirements. Either way we want to hear from you.
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.