{"id":1455,"date":"2016-06-15T20:41:33","date_gmt":"2016-06-15T20:41:33","guid":{"rendered":"http:\/\/www.migenius.com\/?p=1455"},"modified":"2016-10-25T03:47:54","modified_gmt":"2016-10-25T03:47:54","slug":"creating-a-simple-scene-programmatically","status":"publish","type":"post","link":"https:\/\/www.migenius.com\/articles\/creating-a-simple-scene-programmatically","title":{"rendered":"Creating a Simple Scene Programmatically"},"content":{"rendered":"

In this article I am going to show you how to create a simple 3D scene, completely from scratch using RealityServer. You will learn about the anatomy of a RealityServer scene and the different components that go into making it up, including options, groups, instances, cameras, geometry and environment lighting. While the scene will be very simple there will be many key principles of RealityServer and NVIDIA Iray demonstrated which you can expand on to build more complex scenes.<\/p>\n

<\/p>\n

Before You Begin<\/h3>\n

If you haven’t already done so, I highly recommend reading the article on Exploring the RealityServer JSON-RPC API<\/a>. This article \u00a0will be assuming you are familiar with the information there, particularly how RealityServer commands work. The scene you will build here will be created entirely by giving RealityServer commands. To follow along you will need an environment from which to send these commands to RealityServer as well as a running instance of RealityServer itself. I\u00a0recommend Postman<\/a>\u00a0for sending commands, however any tool that can send HTTP POST requests will do.<\/p>\n

This article also assumes you are running RealityServer 4.4 build 1527.40 or later and uses some features introduced in that version. Even so the information can be easily adapted to earlier versions if needed.<\/p>\n

What We Will Be Making<\/h3>\n

To the right you can see the image we will be making in this article.\u00a0It includes a simple piece of geometry illuminated by daylight and the configuration of several Iray features such as the implicit ground plane and tone mapping.<\/p>\n

We will use two HTTP requests to make this image, one with an array of commands to generate the scene and another with an array of commands to perform the rendering and clean up the database.<\/p>\n<\/div><\/div>

\"Finished<\/p>\n

Finished Scene We Will Render<\/p>\n<\/div>\n<\/div><\/div><\/div>\n

Terminology<\/h3>\n

In this article I will use a few terms which have important meanings. Here are two terms in particular that\u00a0are used often which you need to understand as they might have different meanings in common language but mean something very specific in RealityServer.<\/p>\n

Elements<\/h5>\n

An element in RealityServer is something that is created in the RealityServer database, usually to be added to a scene but not always. Elements are things like options, instances, groups, lights and many other items. Elements usually serve a specific purpose in Iray, refer to the RealityServer documentation for more details.<\/p>\n

Attributes<\/h5>\n

Attributes represent information we can attach to elements. These have a type and a value and elements can have many attributes attached to them. These attributes usually represent options which tell the element to behave a certain way, For example, an instance element can have a visible<\/em> attribute which controls whether you can see it or not.<\/p>\n

Creating a Scope<\/h3>\n

We will cover scopes in more detail in another article, however when doing anything in RealityServer, usually you will utilise a unique scope in order to prevent other users of the server seeing or conflicting with your data. Let’s go ahead and create a scope and then instruct RealityServer to use that scope immediately for the duration of our request.<\/p>\n

\r\n[\r\n\t{"jsonrpc": "2.0", "method": "create_scope", "params": {\r\n\t\t"scope_name" : "exScope"\r\n\t}, "id": 1},\r\n\r\n\t{"jsonrpc": "2.0", "method": "use_scope", "params": {\r\n\t\t"scope_name" : "exScope"\r\n\t}, "id": 2}\r\n]\r\n<\/pre>\n
Normally you would use a unique identifier such as a UUID<\/a> when making a scope to ensure it doesn’t clash with others. Since we are going to be testing on our own server we will just use a simple name. Notice the above request is a batch of two commands. Throughout this article the commands we are adding will be added to this single batch array of commands. Commands after the use_scope<\/em> call above will be performed in the named scope.<\/p>\n
Creating the Scene<\/h3>\n
In RealityServer, a scene holds references to everything needed to create a 3D rendering. There are three essential elements a scene must have, a root group<\/em>, a camera instance<\/em> and options<\/em>. First we will create an empty scene element in the RealityServer database as follows.<\/p>\n
\r\n[\r\n\t...\r\n\t\r\n\t{"jsonrpc": "2.0", "method": "create_scene", "params": {\r\n\t\t"scene_name" : "exScene"\r\n\t}, "id": 3}\r\n]\r\n<\/pre>\n
You will need to use the scene_name<\/em> often in future commands. Since the scene is created inside the scope you don’t need to ensure it is unique, as long as the scope is.<\/p>\n
Creating the Options<\/h3>\n
The options element is basically a container for attributes that control various Iray rendering settings. These settings do not relate to specific elements but rather apply to the entire scene. Later we will attach attributes to the options to control the rendering. For now we just need to create the options and tell the scene to use them.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "create_element", "params": {\r\n\t\t"element_name" : "exOptions",\r\n\t\t"element_type" : "Options"\r\n\t}, "id": 4},\r\n\r\n\t{"jsonrpc": "2.0", "method": "scene_set_options", "params": {\r\n\t\t"scene_name" : "exScene",\r\n\t\t"options" : "exOptions"\r\n\t}, "id": 5}\r\n<\/pre>\n
Here we call the create_element<\/em> command for the first time. With the exception of scenes (which use the special create_scene<\/em> command), the create_element<\/em> command is used to add new elements to the database. For a list of available element types refer to the documentation for the command.<\/p>\n
Creating the Root Group<\/h3>\n
The root group is a container which holds references to all of the instances, geometry, lights and other groups which will be used to render the scene. Every scene needs a root group so let’s create an empty one to begin with.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "create_element", "params": {\r\n\t\t"element_name" : "exRootGroup",\r\n\t\t"element_type" : "Group"\r\n\t}, "id": 6},\r\n\r\n\t{"jsonrpc": "2.0", "method": "scene_set_rootgroup", "params": {\r\n\t\t"scene_name" : "exScene",\r\n\t\t"group" : "exRootGroup"\r\n\t}, "id": 7}\r\n]\r\n<\/pre>\n
This is the same process used for the options. For geometry to actually render it must be attached to the root group. We will cover this a bit later on.<\/p>\n
Creating the Camera<\/h3>\n
Now for something with a bit more complexity. We need to create a camera which will define the viewpoint for our rendering. The scene needs a camera instance rather than the camera itself so we will need to make that as well.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "create_element", "params": {\r\n\t\t"element_name" : "exCamera",\r\n\t\t"element_type" : "Camera"\r\n\t}, "id": 8},\r\n\r\n\t{"jsonrpc": "2.0", "method": "camera_set_resolution", "params": {\r\n\t\t"camera_name" : "exCamera",\r\n\t\t"resolution" : { "x" : 640, "y" : 480 }\r\n\t}, "id": 9},\r\n\r\n\t{"jsonrpc": "2.0", "method": "create_element", "params": {\r\n\t\t"element_name" : "exCameraInstance",\r\n\t\t"element_type" : "Instance"\r\n\t}, "id": 10},\r\n\r\n\t{"jsonrpc": "2.0", "method": "instance_set_world_to_obj", "params": {\r\n\t\t"instance_name" : "exCameraInstance",\r\n\t\t"transform" : {\r\n\t\t\t"xx": -1.0, "xy": 0.0,                 "xz": 0.0,                 "xw": 0.0,\r\n\t\t\t"yx": 0.0,  "yy": 1.0,                 "yz": 0.20395425411200102, "yw": 0.0,\r\n\t\t\t"zx": 0.0,  "zy": 0.20395425411200102, "zz": -1.0,                "zw": 0.0,\r\n\t\t\t"wx": 8.0,  "wy": -5.0,                "wz": -25.0,               "ww": 1.0\r\n\t\t}\r\n\t}, "id": 11},\r\n\r\n\t{"jsonrpc": "2.0", "method": "instance_attach", "params": {\r\n\t\t"instance_name" : "exCameraInstance",\r\n\t\t"item_name" : "exCamera"\r\n\t}, "id": 12},\r\n\r\n\t{"jsonrpc": "2.0", "method": "group_attach", "params": {\r\n\t\t"group_name" : "exRootGroup",\r\n\t\t"item_name" : "exCameraInstance"\r\n\t}, "id": 13},\r\n\r\n\t{"jsonrpc": "2.0", "method": "scene_set_camera_instance", "params": {\r\n\t\t"scene_name" : "exScene",\r\n\t\t"camera_instance" : "exCameraInstance"\r\n\t}, "id": 14}\r\n]\r\n<\/pre>\n
First we create the actual camera. Immediately afterwards we call one of the specialised camera commands camera_set_resolution<\/em> to set the size of the image we want to render. You can find other camera commands in the camera<\/em> group of the command documentation. We use the defaults for focal length and aperture for now but there are commands to set these available.<\/p>\n
Once the camera is made we create a new instance element. Instances are special elements which reference something in the scene and allow you to position it by applying a transformation matrix. We do that here with the instance_set_world_to_obj<\/em> command which sets the 4×4 matrix representing the world to object space transform of the instance. In this case we are using it to move the camera along the Z-axis, raise it up the Y-axis and tilt it downwards.<\/p>\n
For the instance to actually reference the camera element we need to attach it using the instance_attach<\/em> command. We then place the instance in our root group with the group_attach<\/em> command. Finally with this all setup we can tell the scene which camera to use by calling the scene_set_camera_instance<\/em> command.<\/p>\n
Turning on the Light<\/h3>\n
If we were to render the scene now we would just get a black image because there is no environment or light source. For this example we are going to setup a daylight environment which will be used both as the background and as the source of illumination in the scene. We use the physically based sun_and_sky<\/em> function provided by MDL for this. This function is provided in the MDL base<\/em> module. The base<\/em> module is a special case, even though we are going to call import_scene_elements<\/em> to load it from a file that file actually doesn’t exist anywhere. It is a special internal file, later when we load a material we will load a read MDL file from disk. Here are the commands for making the daylighting and turning it on.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "import_scene_elements", "params": {\r\n\t\t"filename": "${shader}\/base.mdl"\r\n\t}, "id": 15},\r\n\r\n\t{"jsonrpc": "2.0", "method": "create_function_call_from_definition", "params": {\r\n\t\t"arguments" : {\r\n\t\t\t"multiplier" : 0.10132,\r\n\t\t\t"rgb_unit_conversion" : { \r\n\t\t\t\t"r" : 1.0,\r\n\t\t\t\t"g" : 1.0,\r\n\t\t\t\t"b" : 1.0\r\n\t\t\t},\r\n\t\t\t"sun_disk_intensity" : 1.0,\r\n\t\t\t"physically_scaled_sun" : true,\r\n\t\t\t"sun_direction" : { "x" : 0.0, "y" : 0.5, "z" : -1.0 }\r\n\t\t},\r\n\t\t"function_definition_name" : "mdl::base::sun_and_sky(bool,float,color,float,float,float,float,float,color,color,float3,float,float,float,bool,int,bool)",\r\n\t\t"function_name" : "exSunSky"\r\n\t}, "id": 16},\r\n\r\n\t{"jsonrpc": "2.0", "method": "element_set_attribute", "params": {\r\n\t\t"element_name" : "exOptions",\r\n\t\t"attribute_type" : "Ref",\r\n\t\t"attribute_name" : "environment_function",\r\n\t\t"attribute_value" : "exSunSky",\r\n\t\t"create" : true\r\n\t}, "id": 17}\r\n]\r\n<\/pre>\n
So there are three steps, first import the MDL module containing the function, then create a function call from the function definition and finally set an attribute on our options element to tell Iray which MDL function to use to generate the environment. You will note a few things about the\u00a0create_function_call_from_definition<\/em> command used above. Firstly, you can see that you can provide initial values for the various attributes of the function at the time of creation. If there are parameters which do not have defaults you will need to provide values for them here otherwise you will get an error.<\/p>\n
Secondly, note the odd value for the function_definition_name<\/em> parameter. This is the function signature<\/em>. Since MDL supports overloading of functions (similar to various Object Oriented programming languages), the function needs to be referenced by its full signature. You can find the signatures of the loaded functions by calling\u00a0import_scene_elements with the “import_options” : { “list_elements” : true }<\/em> parameter. You can also call the\u00a0get_function_definition_overloads<\/em> command if you know the function name. This will give you an array of strings representing the function signatures.<\/p>\n
When setting the environment_function<\/em> attribute on the options, we use the Ref<\/em> attribute type since while we are using a name this particular attribute expects a reference to a function.<\/p>\n
Setting up Tonemapping<\/h3>\n
Now if we rendered the scene we wouldn’t get a black image, we would get a completely white image! Well that’s progress but really we want to see the sky we just created. For this we need to turn on the tonemapping functionality of Iray which controls how the physically correct values generated by Iray are mapped to the limited range of RGB colour values used to display images on computer screens.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "element_set_attributes", "params": {\r\n\t\t"create" : true,\r\n\t\t"element_name" : "exCamera",\r\n\t\t"attributes" : {\r\n\t\t\t"tm_tonemapper" : {\r\n\t\t\t\t"type" : "String",\r\n\t\t\t\t"value" : "mia_exposure_photographic"\r\n\t\t\t},\r\n\t\t\t"mip_cm2_factor" : {\r\n\t\t\t\t"type" : "Float32",\r\n\t\t\t\t"value" : 1.0\r\n\t\t\t},\r\n\t\t\t"mip_film_iso" : {\r\n\t\t\t\t"type" : "Float32",\r\n\t\t\t\t"value" : 100.0\r\n\t\t\t},\r\n\t\t\t"mip_camera_shutter" : {\r\n\t\t\t\t"type" : "Float32",\r\n\t\t\t\t"value" : 250.0\r\n\t\t\t},\r\n\t\t\t"mip_f_number" : {\r\n\t\t\t\t"type" : "Float32",\r\n\t\t\t\t"value" : 8.0\r\n\t\t\t},\r\n\t\t\t"mip_gamma" : {\r\n\t\t\t\t"type" : "Float32",\r\n\t\t\t\t"value" : 2.2\r\n\t\t\t}\r\n\t\t}\r\n\t}, "id": 18}\r\n]\r\n<\/pre>\n
We are using a new command here, element_set_attributes<\/em>, which is basically the same as element_set_attribute used earlier but allows us to set multiple attributes on an element in a single call. Since we are creating the attributes we must provide the type as well as the value for each. The attributes created above are attached to the camera (not the camera instance). You can find more details on how tone mapping works in the RealityServer documentation.<\/p>\n
Geometry<\/h3>\n
The scene would now render with a sky and horizon but no objects which is a bit boring so we’ll add some geometry to the scene. We will use a command that was introduced in RealityServer 4.4 for this, generate_extrusion<\/em>.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "generate_extrusion", "params": {\r\n\t\t"name" : "exObject",\r\n\t\t"profile" : [\r\n\t\t\t{ "x" : 0.0, "y" : 0.0 },\r\n\t\t\t{ "x" : 4.0, "y" : 0.0 },\r\n\t\t\t{ "x" : 4.0, "y" : 6.0 },\r\n\t\t\t{ "x" : 8.0, "y" : 1.0 },\r\n\t\t\t{ "x" : 12.0, "y" : 6.0 },\r\n\t\t\t{ "x" : 12.0, "y" : 0.0 },\r\n\t\t\t{ "x" : 16.0, "y" : 0.0 },\r\n\t\t\t{ "x" : 16.0, "y" : 12.0 },\r\n\t\t\t{ "x" : 12.0, "y" : 12.0 },\r\n\t\t\t{ "x" : 8.0, "y" : 7.0 },\r\n\t\t\t{ "x" : 4.0, "y" : 12.0 },\r\n\t\t\t{ "x" : 0.0, "y" : 12.0 }\r\n\t\t],\r\n\t\t"length" : 12.0\r\n\t}, "id": 19},\r\n\r\n\t{"jsonrpc": "2.0", "method": "element_set_attribute", "params": {\r\n\t\t"element_name" : "exObject",\r\n\t\t"attribute_type" : "Boolean",\r\n\t\t"attribute_name" : "visible",\r\n\t\t"attribute_value" : true,\r\n\t\t"create" : true\r\n\t}, "id": 20},\r\n\r\n\t{"jsonrpc": "2.0", "method": "create_element", "params": {\r\n\t\t"element_name" : "exObjectInstance",\r\n\t\t"element_type" : "Instance"\r\n\t}, "id": 21},\r\n\r\n\t{"jsonrpc": "2.0", "method": "instance_attach", "params": {\r\n\t\t"instance_name" : "exObjectInstance",\r\n\t\t"item_name" : "exObject"\r\n\t}, "id": 22},\r\n\r\n\t{"jsonrpc": "2.0", "method": "group_attach", "params": {\r\n\t\t"group_name" : "exRootGroup",\r\n\t\t"item_name" : "exObjectInstance"\r\n\t}, "id": 23}\r\n]\r\n<\/pre>\n
We give the generate_extrusion<\/em> command a list of points defining an M<\/em> shape from which it can build a nice mesh for us to render. The geometry created by this command has no attributes assigned to it and by default objects are not visible so we need to call element_set_attribute<\/em> to set the visible<\/em> attribute to true so we can see it.<\/p>\n
In order to actually place the object in the scene we need to first create an instance to reference it, then as we did with the camera we attach the object to the instance and add the instance to the root group. At this point we could render the scene and we would get a big M with a funny pink material.<\/p>\n
Defining a Material<\/h3>\n
The M renders pink because we haven’t defined a material for it yet. RealityServer ships with some materials you can use and setup so we’ll import one of those and change its parameters to suit our needs.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "import_scene_elements", "params": {\r\n\t\t"filename": "${shader}\/material_examples\/architectural.mdl"\r\n\t}, "id": 24},\r\n\r\n\t{"jsonrpc": "2.0", "method": "create_material_instance_from_definition", "params": {\r\n\t\t"arguments": {\r\n\t\t\t"diffuse" : { "r" : 0.8, "g" : 0.1, "b" : 0.25 },\r\n\t\t\t"reflectivity" : 0.5,\r\n\t\t\t"refl_gloss" : 0.3\r\n\t\t},\r\n\t\t"material_definition_name": "mdl::material_examples::architectural::architectural",\r\n\t\t"material_name": "exMaterial"\r\n\t}, "id": 25},\r\n\r\n\t{"jsonrpc": "2.0", "method": "instance_set_material", "params": {\r\n\t\t"instance_name" : "exObjectInstance",\r\n\t\t"material_name" : "exMaterial"\r\n\t}, "id": 26}\r\n]\r\n<\/pre>\n
Before making an instance of the MDL material we need to load its definition from disk. We use import_scene_elements<\/em> for this purpose. The ${shader}<\/em> path causes RealityServer to look in all MDL search paths for the file specified. With the MDL file loaded we can now call\u00a0create_material_instance_from_definition<\/em> to create a material within our scene based on the definition contained in the MDL file. In a similar way to when we made the function for the environment, we can set the initial values of any arguments we want. Here we make the material bit red and setup a glossy reflection.<\/p>\n
Finally we call the instance_set_material<\/em> command (this was introduced in RealityServer 4.4 build 1527.40) to actually assign the material to the instance of our M object. If we render the scene now we will get a nice red M lit by daylight, however it will look like it is floating in space, so let’s fix that next.<\/p>\n
Turning on the Ground<\/h3>\n
Iray has a nice feature called the implicit ground plane. This is a special option you can enable which creates an automatic ground surface in the scene which can catch shadows and reflections from objects in the scene. The beauty of this feature is you just turn it on and everything is automatic, there is no need to model very large planes or surface. We turn it on simply by setting attributes on our options element.<\/p>\n
\r\n[\r\n\t...\r\n\r\n\t{"jsonrpc": "2.0", "method": "element_set_attributes", "params": {\r\n\t\t"element_name" : "exOptions",\r\n\t\t"create" : true,\r\n\t\t"attributes" : {\r\n\t\t\t"environment_dome_ground" : {\r\n\t\t\t\t"type" : "Boolean",\r\n\t\t\t\t"value" : true\r\n\t\t\t},\r\n\t\t\t"environment_dome_ground_reflectivity" : {\r\n\t\t\t\t"type" : "Color",\r\n\t\t\t\t"value" : { "r" : 0.4, "g" : 0.4, "b" : 0.4 }\r\n\t\t\t},\r\n\t\t\t"environment_dome_ground_glossiness" : {\r\n\t\t\t\t"type" : "Float32",\r\n\t\t\t\t"value" : 1000.0\r\n\t\t\t},\r\n\t\t\t"environment_dome_ground_shadow_intensity" : {\r\n\t\t\t\t"type" : "Float32",\r\n\t\t\t\t"value" : 0.8\r\n\t\t\t}\r\n\t\t}\r\n\t}, "id": 27}\r\n]\r\n<\/pre>\n
In this case we turn on the ground, then give it a reflectivity, glossiness and slightly reduce the shadow intensity. We use the element_set_attributes<\/em> command again to set multiple attributes in one go. At this stage we now have a complete scene which we can render to produce the image shown at the start of this article.<\/p>\n
Putting it All Together<\/h3>\n
So we broke down all of the commands needed to make the scene above, now let’s put it all together in a single call we can make to RealityServer to generate the scene. There are 27 commands in all and here they are in one go. You can cut and past this into a tool like Postman and send it a post request to RealityServer and it will create the scene for you and it will reside in the scope. After reviewing the full scene creation request below we will finally make one more request to do the actual rendering. Here is the complete scene generation request. Click the box below to show the full source.<\/p>\n
Complete Scene Creation Request (Click to Expand)<\/i><\/i><\/h3>
\n
\r\n[\r\n  {"jsonrpc": "2.0", "method": "create_scope", "params": {\r\n    "scope_name" : "exScope"\r\n  }, "id": 1},\r\n  {"jsonrpc": "2.0", "method": "use_scope", "params": {\r\n    "scope_name" : "exScope"\r\n  }, "id": 2},\r\n  {"jsonrpc": "2.0", "method": "create_scene", "params": {\r\n    "scene_name" : "exScene"\r\n  }, "id": 3},\r\n  {"jsonrpc": "2.0", "method": "create_element", "params": {\r\n    "element_name" : "exOptions",\r\n    "element_type" : "Options"\r\n  }, "id": 4},\r\n  {"jsonrpc": "2.0", "method": "scene_set_options", "params": {\r\n    "scene_name" : "exScene",\r\n    "options" : "exOptions"\r\n  }, "id": 5},\r\n  {"jsonrpc": "2.0", "method": "create_element", "params": {\r\n    "element_name" : "exRootGroup",\r\n    "element_type" : "Group"\r\n  }, "id": 6},\r\n  {"jsonrpc": "2.0", "method": "scene_set_rootgroup", "params": {\r\n    "scene_name" : "exScene",\r\n    "group" : "exRootGroup"\r\n  }, "id": 7},\r\n  {"jsonrpc": "2.0", "method": "create_element", "params": {\r\n    "element_name" : "exCamera",\r\n    "element_type" : "Camera"\r\n  }, "id": 8},\r\n  {"jsonrpc": "2.0", "method": "camera_set_resolution", "params": {\r\n    "camera_name" : "exCamera",\r\n    "resolution" : { "x" : 640, "y" : 480 }\r\n  }, "id": 9},\r\n  {"jsonrpc": "2.0", "method": "create_element", "params": {\r\n    "element_name" : "exCameraInstance",\r\n    "element_type" : "Instance"\r\n  }, "id": 10},\r\n  {"jsonrpc": "2.0", "method": "instance_set_world_to_obj", "params": {\r\n    "instance_name" : "exCameraInstance",\r\n    "transform" : {\r\n      "xx": -1.0, "xy": 0.0,                 "xz": 0.0,                 "xw": 0.0,\r\n      "yx": 0.0,  "yy": 1.0,                 "yz": 0.20395425411200102, "yw": 0.0,\r\n      "zx": 0.0,  "zy": 0.20395425411200102, "zz": -1.0,                "zw": 0.0,\r\n      "wx": 8.0,  "wy": -5.0,                "wz": -25.0,               "ww": 1.0\r\n    }\r\n  }, "id": 11},\r\n  {"jsonrpc": "2.0", "method": "instance_attach", "params": {\r\n    "instance_name" : "exCameraInstance",\r\n    "item_name" : "exCamera"\r\n  }, "id": 12},\r\n  {"jsonrpc": "2.0", "method": "group_attach", "params": {\r\n    "group_name" : "exRootGroup",\r\n    "item_name" : "exCameraInstance"\r\n  }, "id": 13},\r\n  {"jsonrpc": "2.0", "method": "scene_set_camera_instance", "params": {\r\n    "scene_name" : "exScene",\r\n    "camera_instance" : "exCameraInstance"\r\n  }, "id": 14},\r\n  {"jsonrpc": "2.0", "method": "import_scene_elements", "params": {\r\n    "filename": "${shader}\/base.mdl"\r\n  }, "id": 15},\r\n  {"jsonrpc": "2.0", "method": "create_function_call_from_definition", "params": {\r\n    "arguments" : {\r\n      "multiplier" : 0.10132,\r\n      "rgb_unit_conversion" : { \r\n        "r" : 1.0,\r\n        "g" : 1.0,\r\n        "b" : 1.0\r\n      },\r\n      "sun_disk_intensity" : 1.0,\r\n      "physically_scaled_sun" : true,\r\n      "sun_direction" : { "x" : 0.0, "y" : 0.5, "z" : -1.0 }\r\n    },\r\n    "function_definition_name" : "mdl::base::sun_and_sky(bool,float,color,float,float,float,float,float,color,color,float3,float,float,float,bool,int,bool)",\r\n    "function_name" : "exSunSky"\r\n  }, "id": 16},\r\n  {"jsonrpc": "2.0", "method": "element_set_attribute", "params": {\r\n    "element_name" : "exOptions",\r\n    "attribute_type" : "Ref",\r\n    "attribute_name" : "environment_function",\r\n    "attribute_value" : "exSunSky",\r\n    "create" : true\r\n  }, "id": 17},\r\n  {"jsonrpc": "2.0", "method": "element_set_attributes", "params": {\r\n    "create" : true,\r\n    "element_name" : "exCamera",\r\n    "attributes" : {\r\n      "tm_tonemapper" : {\r\n        "type" : "String",\r\n        "value" : "mia_exposure_photographic"\r\n      },\r\n      "mip_cm2_factor" : {\r\n        "type" : "Float32",\r\n        "value" : 1.0\r\n      },\r\n      "mip_film_iso" : {\r\n        "type" : "Float32",\r\n        "value" : 100.0\r\n      },\r\n      "mip_camera_shutter" : {\r\n        "type" : "Float32",\r\n        "value" : 250.0\r\n      },\r\n      "mip_f_number" : {\r\n        "type" : "Float32",\r\n        "value" : 8.0\r\n      },\r\n      "mip_gamma" : {\r\n        "type" : "Float32",\r\n        "value" : 2.2\r\n      }\r\n    }\r\n  }, "id": 18},\r\n  {"jsonrpc": "2.0", "method": "generate_extrusion", "params": {\r\n    "name" : "exObject",\r\n    "profile" : [\r\n      { "x" : 0.0, "y" : 0.0 },\r\n      { "x" : 4.0, "y" : 0.0 },\r\n      { "x" : 4.0, "y" : 6.0 },\r\n      { "x" : 8.0, "y" : 1.0 },\r\n      { "x" : 12.0, "y" : 6.0 },\r\n      { "x" : 12.0, "y" : 0.0 },\r\n      { "x" : 16.0, "y" : 0.0 },\r\n      { "x" : 16.0, "y" : 12.0 },\r\n      { "x" : 12.0, "y" : 12.0 },\r\n      { "x" : 8.0, "y" : 7.0 },\r\n      { "x" : 4.0, "y" : 12.0 },\r\n      { "x" : 0.0, "y" : 12.0 }\r\n    ],\r\n    "length" : 12.0\r\n  }, "id": 19},\r\n  {"jsonrpc": "2.0", "method": "element_set_attribute", "params": {\r\n    "element_name" : "exObject",\r\n    "attribute_type" : "Boolean",\r\n    "attribute_name" : "visible",\r\n    "attribute_value" : true,\r\n    "create" : true\r\n  }, "id": 20},\r\n  {"jsonrpc": "2.0", "method": "create_element", "params": {\r\n    "element_name" : "exObjectInstance",\r\n    "element_type" : "Instance"\r\n  }, "id": 21},\r\n  {"jsonrpc": "2.0", "method": "instance_attach", "params": {\r\n    "instance_name" : "exObjectInstance",\r\n    "item_name" : "exObject"\r\n  }, "id": 22},\r\n  {"jsonrpc": "2.0", "method": "group_attach", "params": {\r\n    "group_name" : "exRootGroup",\r\n    "item_name" : "exObjectInstance"\r\n  }, "id": 23},\r\n  {"jsonrpc": "2.0", "method": "import_scene_elements", "params": {\r\n    "filename": "${shader}\/material_examples\/architectural.mdl"\r\n  }, "id": 24},\r\n  {"jsonrpc": "2.0", "method": "create_material_instance_from_definition", "params": {\r\n    "arguments": {\r\n      "diffuse" : { "r" : 0.8, "g" : 0.1, "b" : 0.25 },\r\n      "reflectivity" : 0.5,\r\n      "refl_gloss" : 0.3\r\n    },\r\n    "material_definition_name": "mdl::material_examples::architectural::architectural",\r\n    "material_name": "exMaterial"\r\n  }, "id": 25},\r\n\r\n  {"jsonrpc": "2.0", "method": "instance_set_material", "params": {\r\n    "instance_name" : "exObjectInstance",\r\n    "material_name" : "exMaterial"\r\n  }, "id": 26},\r\n  {"jsonrpc": "2.0", "method": "element_set_attributes", "params": {\r\n    "element_name" : "exOptions",\r\n    "create" : true,\r\n    "attributes" : {\r\n      "environment_dome_ground" : {\r\n        "type" : "Boolean",\r\n        "value" : true\r\n      },\r\n      "environment_dome_ground_reflectivity" : {\r\n        "type" : "Color",\r\n        "value" : { "r" : 0.4, "g" : 0.4, "b" : 0.4 }\r\n      },\r\n      "environment_dome_ground_glossiness" : {\r\n        "type" : "Float32",\r\n        "value" : 1000.0\r\n      },\r\n      "environment_dome_ground_shadow_intensity" : {\r\n        "type" : "Float32",\r\n        "value" : 0.8\r\n      }\r\n    }\r\n  }, "id": 27}\r\n]\r\n<\/pre>\n<\/p><\/div><\/div><\/p><\/div>\n
Rendering an Image<\/h3>\n
Creating a scene is great but of course we actually want to render an image of our creation. We will do that in a separate request where we setup some rendering settings first then perform a batch render. This request is special because it will return an image rather than a JSON response. For the scene creation part it was useful to leave out the render command since if there are any errors during the scene creation we want to see those and returning an image would prevent us from seeing any errors. You can however create the scene and render the image in a single request if needed. Here is what we need to render our image.<\/p>\n
\r\n[\r\n\t{"jsonrpc": "2.0", "method": "use_scope", "params": {\r\n\t\t"scope_name" : "exScope"\r\n\t}, "id": 1},\r\n\r\n\t{"jsonrpc": "2.0", "method": "element_set_attributes", "params": {\r\n\t\t"element_name" : "exOptions",\r\n\t\t"create" : true,\r\n\t\t"attributes" : {\r\n\t\t\t"progressive_rendering_max_samples" : {\r\n\t\t\t\t"type" : "Sint32",\r\n\t\t\t\t"value" : 100\r\n\t\t\t},\r\n\t\t\t"progressive_rendering_max_time" : {\r\n\t\t\t\t"type" : "Sint32",\r\n\t\t\t\t"value" : 10\r\n\t\t\t}\r\n\t\t}\r\n\t}, "id": 2},\r\n\r\n\t{"jsonrpc": "2.0", "method": "render", "params": {\r\n\t\t"scene_name" : "exScene",\r\n\t\t"renderer" : "iray",\r\n\t\t"render_context_options" : {\r\n\t\t\t"scheduler_mode" : {\r\n\t\t\t\t"type" : "String",\r\n\t\t\t\t"value" : "batch"\r\n\t\t\t}\r\n\t\t}\r\n\t}, "id": 3},\r\n\r\n\t{"jsonrpc": "2.0", "method": "delete_scope", "params": {\r\n\t\t"scope_name" : "exScope"\r\n\t}, "id": 4}\r\n]\r\n<\/pre>\n
The first command in our batch must be the use_scope<\/em> command so that the other commands can “see” the scene we created. Without calling this everything we created will be invisible to the other commands. We then set two new attributes on our options element to control when rendering will terminate, if either of these conditions is met rendering will finish. So in our case it will render either 100 iterations or for 10 seconds, which ever comes first.<\/p>\n
We then make a call to the render<\/em> command and provide a special render_context_options<\/em> parameter where we set the Iray scheduler_mode<\/em> to batch<\/em>. This causes Iray to render continuously until the termination conditions are met and only return after that. Usually you might want to render in stages so you can retrieve intermediate images but here we will just render to the end and return the completed image. To the right we can see the completed image once again, you can click this one to enlarge and view a higher resolution version.<\/p>\n<\/div><\/div>
\"Final<\/a><\/p>\n
Final Result (Cilck to Enlarge)<\/p>\n<\/div>\n<\/div><\/div><\/div>\n
Finally after rendering we call delete_scope<\/em> to remove the scene we made and everything associated with it. This cleans up the database and frees memory for other users and tasks. Of course if we wanted to perform further actions on the scene we would omit this command.<\/p>\n
Summary<\/h3>\n
In this article we have covered all of the steps necessary to create \u00a0simple scene entirely in code without any pre-existing geometry elements. You have learned about many key RealityServer commands which are needed to perform common operations as well as how to combine them in useful ways. With this experience you can, with the aid of the RealityServer Command Documentation create much more complex scenes and manipulate other scenes you might load from disk. Think about where you could use dynamic scene creation in your next RealityServer project. Contact us<\/a> if you want more details or would like to request an evaluation of RealityServer.<\/p>\n","protected":false},"excerpt":{"rendered":"
In this article I am going to show you how to create a simple 3D scene, completely from scratch using RealityServer. You will learn about the anatomy of a RealityServer scene and the different components that go into making it up, including options, groups, instances, cameras, geometry and environment lighting. While the scene will be […]<\/p>\n","protected":false},"author":2,"featured_media":1465,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"spay_email":"","jetpack_publicize_message":"Creating a Simple 3D Scene Programmatically with RealityServer","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true},"categories":[15,30],"tags":[26,14,27],"jetpack_featured_media_url":"https:\/\/www.migenius.com\/migenius\/wp-content\/uploads\/2016\/06\/scene_creation_feature_image.jpg","_links":{"self":[{"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/posts\/1455"}],"collection":[{"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/comments?post=1455"}],"version-history":[{"count":14,"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/posts\/1455\/revisions"}],"predecessor-version":[{"id":1475,"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/posts\/1455\/revisions\/1475"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/media\/1465"}],"wp:attachment":[{"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/media?parent=1455"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/categories?post=1455"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.migenius.com\/wp-json\/wp\/v2\/tags?post=1455"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}