RealityServer Features

File Import Tutorial

This example shows a use case that would typically involve at least two round trip requests to the server. Here we are importing a part from an arbitrary file and inserting it into a scene. The issue is that we we need to know the name of the root group of the imported part to be able to instance it in our current scene. Therefore we need a first command to import the part and return the root group and a second batch to instance it and add it to our scene root group. Using smart_batch This can all be done in one command. The full command and response are showing below then each individual command is broken down below.

Example: Part import.

{
    "id": 1,
    "method": "smart_batch",
    "params": {
        "environment": {
            "scene_name": "my_scene",
            "part_file": "scenes/parts/XJ3043.mi",
            "part_transform": {
                        "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                        "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                        "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                        "wx": 2, "wy": -3, "wz": -10, "ww": 1
            }
        },
        "continue_on_error": false,
        "commands": [
            {
                "name": "get_scene",
                "params": {
                    "scene_name": "${scene_name}"
                },
                "id": "scene"
            },
            {
                "name": "import_scene",
                "params": {
                    "scene_name": "${part_file}_scene",
                    "filename": "${part_file}",
                    "block": true,
                    "import_options" : {
                        "prefix": "${part_file}::"
                    }
                },
                "id": "imported_part"
            },
            {
                "name": "echo",
                "params" : {
                    "input": "${part_file}_instance"
                },
                "id": "part_instance"
            },
            {
                "name": "create_element",
                "params" : {
                    "element_name": "${part_instance}",
                    "element_type": "Instance"
                }
            },
            {
                "name": "instance_attach",
                "params" : {
                    "instance_name": "${part_instance}",
                    "item_name": "${imported_part.rootgroup}"
                }
            },
            {
                "name": "instance_set_world_to_obj",
                "params" : {
                    "instance_name": "${part_instance}",
                    "transform": "${part_transform}"
                }
            },
            {
                "name": "element_set_attribute",
                "params" : {
                    "element_name": "${part_instance}",
                    "attribute_name": "visible",
                    "attribute_value": true,
                    "attribute_type": "Boolean",
                    "create": true
                }
            },
            {
                "name": "group_attach",
                "params" : {
                    "group_name": "${scene.root_group}",
                    "item_name": "${part_instance}"
                }
            }
        ]
    }
}

Example: Part import response.

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "environment": {
            "part_file": "scenes/parts/XJ3043.mi",
            "part_instance": "scenes/parts/XJ3043.mi_instance",
            "part_transform":  {
                        "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                        "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                        "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                        "wx": 2, "wy": -3, "wz": -10, "ww": 1
            },
            "imported_part": {
                "camera": "scenes/parts/XJ3043.mi::cam",
                "camera_instance": "scenes/parts/XJ3043.mi::cam_inst",
                "imported_elements": [],
                "messages": [],
                "options": "scenes/parts/XJ3043.mi::opt",
                "rootgroup": "scenes/parts/XJ3043.mi::rootgroup"
            },
            "scene": {
                "camera_instance": "cam_inst",
                "options": "opt",
                "root_group": "rootgroup"
                },
            "scene_name": "my_scene"
        },
        "has_sub_error_response": false,
        "responses": [
            {
                "result": {
                    "camera_instance": "cam_inst",
                    "options": "opt",
                    "root_group": "rootgroup"
                }
            },
            {
                "result": {
                    "camera": "scenes/parts/XJ3043.mi::cam",
                    "camera_instance": "scenes/parts/XJ3043.mi::cam_inst",
                    "imported_elements": [],
                    "messages": [],
                    "options": "scenes/parts/XJ3043.mi::opt",
                    "rootgroup": "scenes/parts/XJ3043.mi::rootgroup"
                }
            },
            {
                "result": "scenes/parts/XJ3043.mi_instance"
            },
            {
                "result": {}
            },
            {
                "result": {}
            },
            {
                "result": {}
            },
            {
                "result": {}
            },
            {
                "result": 5
            }
        ]
    }
}    

1. get_scene

The first command gets the information for the scene we are importing into. The name of this is given in the scene_name environment variable and we store the result in the environment as scene.

Command

{
    "name": "get_scene",
    "params": {
        "scene_name": "${scene_name}"
    },
    "id": "scene"
}

Environment variable set

"scene": {
    "camera_instance": "cam_inst",
    "options": "opt",
    "root_group": "rootgroup"
}

2. import_scene

Here we import the part whose filename is given in part_file. We import it as a full scene to take advantage of RealityServer's scene caching mechanism and apply a prefix to namespace the scene's content to prevent conflicts. These names are all derived from the part filename. The result is stored in imported_part so we can later access the root group.

Command

{
    "name": "import_scene",
    "params": {
        "scene_name": "${part_file}_scene",
        "filename": "${part_file}",
        "block": true,
        "import_options" : {
            "prefix": "${part_file}::"
        }
    },
    "id": "imported_part"
}

Environment variable set

"imported_part": {
    "camera": "scenes/parts/XJ3043.mi::cam",
    "camera_instance": "scenes/parts/XJ3043.mi::cam_inst",
    "imported_elements": [],
    "messages": [],
    "options": "scenes/parts/XJ3043.mi::opt",
    "rootgroup": "scenes/parts/XJ3043.mi::rootgroup"
}

3. echo

We need a name to use for the instance of the part. Given this will be used in multiple commands we use the echo command to return a string and store it in the environment. We could have simply used ${part_file}_instance directly in all commands however this is method safer and has the advantage that the client can use part_instance from the returned environment if it needs to further manipulate the instance later.

Command

{
    "name": "echo",
    "params" : {
        "input": "${part_file}_instance"
    },
    "id": "part_instance"
}

Environment variable set

"part_instance": "scenes/parts/XJ3043.mi_instance"

4. create_element

Creates the instance named ${part_instance}.

Command

{
    "name": "create_element",
    "params" : {
        "element_name": "${part_instance}",
        "element_type": "Instance"
    }
}

5. instance_attach

Attaches the root group of the imported path to ${part_instance}.

Command

{
    "name": "instance_attach",
    "params" : {
        "instance_name": "${part_instance}",
        "item_name": "${imported_part.rootgroup}"
    }
}

6. instance_set_world_to_obj

Sets the transform of ${part_instance} to the provided transform.

Command

{
    "name": "instance_set_world_to_obj",
    "params" : {
        "instance_name": "${part_instance}",
        "transform": "${part_transform}"
    }
}

7. element_set_attribute

Make ${part_instance} visible just in case it's child elements don't have visible set.

Command

{
    "name": "element_set_attribute",
    "params" : {
        "element_name": "${part_instance}",
        "attribute_name": "visible",
        "attribute_value": true,
        "attribute_type": "Boolean",
        "create": true
    }
}

8. group_attach

Finally, we attach ${part_instance} to the root group of our scene.

Command

{
    "name": "group_attach",
    "params" : {
        "group_name": "${scene.root_group}",
        "item_name": "${part_instance}"
    }
}