What’s New in RealityServer 5.3 Update 276

This is the seventh update of RealityServer 5.3 since it was released in May. That’s a new release every month folks! While this post will focus on the features added in the most recent, 2593.276 build, we’ll also recap some of the other features added along the way in previous updates. The headline item for this new release is the ability to make HTTP requests from within the server-side V8 JavaScript API. This has been a long standing request from users and we are finally able to ship this feature to you. There’s also some cool new glTF features and much more.

HTTP Requests in V8

We’ve had this one in the backlog for quite a long time now. We build a lot of RealityServer applications for customers and there are so many times we’ve said to ourselves, if only we had HTTP request functionality we wouldn’t need to have this extra Node.js server.

The recently added queue manager was borne of a similar frustration. We had implemented this functionality at least four times as a companion Node.js server application and started to see it should become a core feature. Afterwards we started to look at what other requirements caused us to have to use another server, just to get one key piece of functionality not available in RealityServer.

The queue manager allowed us to lay the ground work since it required us to add a HTTP client to our C++ API (you can access this in our neuray Services API with the IHttp_client class). After this was deployed we used this same C++ class to extend the V8 API with HTTP request functionality. We’ve tried to make this new API as convenient and easy to use as possible. It is as simple as adding something like this to your V8 command.

const response = http.get('http://www.example.com/');

You’ll notice we are calling the get method on our HTTP class here. This is just an alias which internally calls the send method with the HTTP request method property set to GET. So this would be equivalent to.

const response = http.send({ method: 'GET', url: 'http://www.example.com/' });

Similar methods are provided for the standard HTTP verbs GET, POST, DELETE, HEAD, OPTIONS, PATCH and PUT. Of course the vast majority of the time get and post are the methods you’ll be using. Since a lot of web services use JSON for requests and responses you also have the option to have this automatically encoded and decoded for you just by setting the json property of the request to true.

const response = http.post({
    url: 'http://api.example.com/v1/people',
    json: true,
    body: {
        person_id: 'b4q5f3'
    }
});
console.log(response.body.firstname);

In the above example we are sending a JSON encoded body and the response is automatically decoded from JSON into an object and set in the body property of the response. This makes calling JSON based APIs from RealityServer really easy. There is also the ability to make multiple simultaneous requests, you just need to provide an array of URLs, request objects or a mixture of both. Here is a quick example.

const responses = http.send([
    'http://example.com/1',
    'http://example.com/2'
]);

All of the requests will be sent simultaneously and the method will return only once all requests have completed. This is useful when downloading multiple resources if you want to make requests in parallel. There are a lot of other ways to use the API and many properties available on the request object to customise how your requests are sent. Please see the documentation for V8 Http Requests for more details.

Now, of course you may encounter errors when making HTTP requests. Note that responses that have HTTP error codes are not considered errors because they are valid responses, so if you need to react for example to a HTTP 404 code, then you need to check the code property on the response for this. If however there is an error connecting to the server or another error that means the server did not actually provide a response then a http.Error object will be returned instead of a http.Response object. You can easily check for this like so.

const response = http.get('http://invaliddomain');
if (response instanceof http.Error) {
    throw response;
}

Finally there is handling of binary data. If you are requesting binary data you need to ensure you set the encoding property of your request to null, otherwise the response will be interpreted as a utf-8 string. You will then get back an ArrayBuffer as the body property in the response. Let’s download a binary file and write it to disk.

const response = http.get({
    url: 'http://example.com/file.jpg',
    encoding: null
});
fs.writeFile('file.jpg', response.body);

This is probably one of the more commonly requested reasons for having HTTP requests in V8, downloading content from other servers. Of course, you can also upload binary data to servers.

const image = fs.readFile('file.jpg');
const response = http.put({
    url: 'http://example.com/file.jpg',
    body: image.buffer,
    encoding: null
});

These examples really just scratch the surface of what can be done. Of course once you have a general means of making HTTP requests you can connect virtually any service to RealityServer. Be sure to review the documentation for the full details. We think this feature, like the new queue manager will greatly simplify the creation of RealityServer based applications.

Assimp 5.0.0 and glTF 2.0

In this release we have updated the core Assimp library to the newest 5.0.0 release (with a few additional patches we made which have been accepted by the project but not released yet). This brings enhancements to many of the file formats Assimp supports such as FBX, COLLADA and so on as well as a lot of bug fixes. See the Assimp 5.0.0 Release Notes for full details of the changes since 4.1.0.

This also brings some new glTF 2.0 features, including the two most requested by our users, support for the KHR_texture_transform and KHR_lights_punctual extensions. Texture transforms allow you do texture tiling independently of the models UV coordinates and also offset and rotate textures. Many glTF scenes are now using this functionality to remove the need for baking repeating textures into large atlases.

The KHR_lights_punctual extension now results in lights of the specified type being created with valid values in RealityServer. Note however that right now these might not result in useful illumination without some further modifications (which of course you can do with our API). Also note that the range property is not supported since this is not physically correct and would cause problems during rendering. There are also very few example scenes available for this extension, so if you are using it and have good examples please contact us.

glTF 2.0 Test Using KHR_texture_transform

One other major feature we introduced (starting with build 2593.229) is new functionality to allow distilled MDL materials to be used in glTF 2.0 export (actually for simpler properties, other formats will use them as well). Right now this feature only works well in models where texture transformations are not used, however you can get some excellent results for scenes that support it. We’ve written up a separate post for this entitled Automatic Creation of glTF with Quality Materials.

Queue Manager

Queue manager functionality was added in build 2593.209 which allows you to utilise AWS SQS as a job queue for running RealityServer commands. This is a major enhancement for customers doing more batch or job oriented workflows and also offers direct integration with AWS S3 so content can be directly uploaded back and served. You can now even combine this with the new HTTP request functionality to enable your V8 queue jobs to download content (for example pulling your models from S3) when running jobs. The queue manager is so important that we wrote up a dedicated blog post for it entitled Cost Effective Rendering with Amazon SQS and S3. We’re also working on support for platforms other than AWS with Azure likely coming first. Get in touch if you are looking for support for a specific platform other than AWS.

Since releasing the queue manager we had a few requests for enhancements. It is now possible (actually mandatory) to specify a region for your SQS queue so you can have your queues outside the AWS us-east-1 region and we have also significantly expanded the options available to the S3 upload tasks to allow setting various metadata and options.

Filling Out V8

We’ve been gradually filling in the gaps in our V8 API over the course of the year and we now have V8 wrapper classes for all major RealityServer element types. In general you can now build out your V8 commands without resorting to explicitly calling RealityServer commands with the RS.command convention. When we build applications internally, every time we find ourselves needing to do this we add the wrapper class and as a result it has now gotten quite complete.

This also includes some new additions to some of the core classes. For example we have now added fs.unlink and fs.rmdir to allow removing files and directories from within V8 (very handy when downloading things to disk using our new HTTP request functionality). With this latest release we are really starting to get to the point where there is much less need to resort to using other server technologies along side RealityServer in your application. While we don’t aim to replace full fledged application server platforms, we do want users to be able to accomplish the vast majority of RealityServer related tasks with just RealityServer.

Mesh Splitting

This latest release also adds the new geometry_split_mesh command which takes a Polygon_mesh or Triangle_mesh element and splits it into multiple meshes based on the material index assigned to each face. Unless you have a specific need this probably doesn’t sound very interesting but if you do need it, the command can save you a round trip back to your modelling software to separate the meshes by hand. Polygon meshes are automatically tessellated into triangle meshes for you during the splitting process.

One of the reasons this command is being added is to test the initial mesh splitting support we have implemented which will go into a future release of our Assimp exporters. This will allow scenes using meshes with multiple materials to be exported to formats such as glTF which don’t support this, where as currently just the first material is exported. Even though we don’t have automatic support in the exporter yet, you can use the command to implement this already if needed. In a future release the exporter will handle this automatically.

Smaller Additions

The mdl_is_default command was added to allow you to determine if an MDL material instance or function call in the database is used as a default parameter in another material or function call. This is useful so you can exclude these elements which getting lists of materials and functions. To that end we also added a new include_defaults parameter to the list_elements command, if you set this to false (it defaults to true) then you won’t see such MDL elements when listing your elements out.

We discovered during the course of some stress testing that the HTTP server had an internal hard coded limit of 100 concurrent connections. This isn’t generally as bad as it sounds since the operating system also plays a role in managing the traffic however Windows and Linux handle things differently and in general we wanted to be able to control this limit. There is now a http_concurrent_connection_limit directive available in realityserver.conf to control this.

The image_get_original_filename command (and the original_filename property of the Image class in V8) now give you back the filename that was originally given when loading an image. Before you could only get back the resolved filename (so this would be where the file was actually found on the local file system). There was a few rare use cases that popped up where the original filename was needed so we added this command.

Iray Updates

This version and the previous build are using Iray RTX 2019.1.5 build 317500.7473. Of course there are quite a few fixes and updates made to Iray which we incorporate so you should always check the neurayrelnotes.pdf file that comes with RealityServer to see what has changed. If you are using RTX based hardware it is particularly important to keep up with the latest releases of RealityServer since the Iray updates often bring performance improvements.

What’s Next?

Well, we’d like to hear from you. What would you like to see added to RealityServer next? Almost all features added over the last year have been a direct result of user feedback, or because we kept implementing the same thing for different customers over and over. Reach out with your ideas, whether your a long time user or thinking RealityServer would fit your needs, if only it did that one extra thing, we want to hear from you.

Articles