RealityServer Features

Outlining

The default render loop handler has the ability to draw outlines of objects in the render. This can be used, for example, to highlight an object that is being edited.

A normal render. A normal render.
An outline render. An outline render.

Once enabled the handler keeps track of the camera and any specified instances and if they change it automatically regenerates the outline so it stays in sync with the scene.

The render loop sample application contains an example of how to perform outlining. Simply click on any object in the scene to have it outlined.

Enabling

Outlining is enabled by setting the outline render handler parameter. At it's simplest this is just a color and the name of the instance to outline.

Outline Handler Properties
Property Key Property Value Description
outline Outline definition string A string defining the outlining to perform, or the empty string to disable outlining.

Example: Outline the instance named cube in red.

{
        "method": "render_loop_set_parameter",
        "params": {
            "render_loop_name": "my_render_loop",
            "key": "outline",
            "value": "1,0,0;cube",
        }
}

Outline Definition

The outline definition string consists of a color and between 1 and 3 lists of scene instances. Each item is semicolor separated. Note that , ; and \ can be escaped in instance names using the \ character.

Type definitions

  • Color - A comma separated RGB triple, each value is a floating point number. Optionally a forth integer can be provided which specifies the thickness of the outline as a radius.
  • Instance list - A comma separated list of 0 or more instance names.

Outline definition

Outline_color;Outline_instances;Watch_instances;Disable_instances

  • Outline_color (Color) - The color to draw the outline in.
  • Outline_instances (Instance list) - The instance names to outline, must have at least 1 item.
  • Watch_instances (Instance list) - If supplied these instances are watched by the handler. If any of them move the outline is regenerated. Note that the Outline_instances are automatically added to this list
  • Disable_instances (Instance list) - If supplied these instances are disabled when rendering outlines. This can be used to ignore obscuring object.

Example: Outline cube and icosahedron in teal:

    "0,0.5019,0.5019;cube,icosahedron"

Example: Outline cube and icosahedron in amber, watch tetrahedron for changes:

    "1,0.749,0;cube,icosahedron;tetrahedron"

Example: Outline watch_face in puce, disable watch_glass so it doesn't obscure the outline:

    "0.4471,0.1843,0.2157;watch_face;;watch_glass"

Example: Outline hour_hand in goldenrod, watch minute_hand and second_hand for changes as they can obscure hour_hand, disable watch_glass so it doesn't obscure the outline:

    "0.8549,0.6471,0.1255;watch_face;minute_hand,second_hand;watch_glass"

Example: Outline cube and icosahedron in teal and a thickness radius of 2:

    "0,0.5019,0.5019,2;cube,icosahedron"

Opaque Rendering

Opaque rendering for outlining is enabled by setting the opaque_outlines render handler parameter to true. This allows objects with cutout materials to be outlined at the object bounds rather than at the cutout perimeter.

Opaque Outline Rendering Properties
Property Key Property Value Description
opaque_outlines false A boolean defining whether to use opaque rendering when rendering outlines.

Example: Enable opaque outline rendering.

{
        "method": "render_loop_set_parameter",
        "params": {
            "render_loop_name": "my_render_loop",
            "key": "opaque_outlines",
            "value": true,
        }
}

Disabling the ground plane

When using a dome environment you may wish to disable the ground plane when rendering outlines. The ground plane can be disabled in outline rendering by setting the disable_ground_for_outlines render handler parameter to true. This prevents the ground plane from obscuring object outlines.

Disable Ground Plane for Outlines Properties
Property Key Property Value Description
disable_ground_for_outlines false A boolean defining whether the ground plane should be enabled when rendering outlines when using a dome environment.

Example: Disable ground plane when rendering outlines.

{
        "method": "render_loop_set_parameter",
        "params": {
            "render_loop_name": "my_render_loop",
            "key": "disable_ground_for_outlines",
            "value": true,
        }
}

Forcing an update

If required, an outline update can be forced by setting the update_outlines parameter to true. This will cause new outlines to be generated and rendered. This parameter can only be written to, attempting to retrieve this value will result in an error.

Outline Update Properties
Property Key Property Value Description
update_outlines false A boolean defining whether outlines should be regenerated with the next render.

Example: Enable opaque outline rendering.

{
        "method": "render_loop_set_parameter",
        "params": {
            "render_loop_name": "my_render_loop",
            "key": "update_outlines",
            "value": true,
        }
}