Documentation Center

Viz Engine Administrator Guide

Version 5.0 | Published December 20, 2022 ©

Viz Console

The Viz Console window is mainly used for debugging purposes, to display information about the running Engine or connected Graphic Hub, and for manually sending commands directly to the Engine. The Viz Console shows the commands that are used in communication between the Viz Engine Renderer and other components, such as Viz Artist, External Control Applications, plug-ins, and scripts.

images/download/attachments/85913475/v4_gs_console.png

For an overview of the available commands, open the console window and type ? or help, then press enter. This outputs a list of the available console commands. The complete documentation for the command interface is included with the Viz installation, and can be found under <Viz Install Folder>\Documentation\CommandInterface.

IMPORTANT! The Viz Console is case sensitive.

Autocompletion Feature

Introduced in Viz Engine version 5, the console offers and autocompletion feature when sending commands directly the console. To use this, hit the TAB key on any location.

Example

Type send RENDERER and hit the CTRL+TAB Key:

images/download/attachments/85913475/image2022-5-25_9-14-5.png

All possible properties on this location are shown in blue, whereas all possible commands are shown in red.

Enums are shown in purple:

images/download/attachments/85913475/arguments_and_possible_values.png

Shortcuts

  • TAB: Steps through the list of available commands or properties.

  • SHIFT + TAB: Steps back.

  • PAGE UP and PAGE DOWN: Selects the first or last entry in the active column.

  • ARROW KEYS: Navigates through the list.

  • ENTER: Selects the highlight possible word if shown otherwise send the command.

  • ESCAPE: Aborts selection if shown, otherwise erase the command line.

  • SHIFT + ESCAPE: Redraws current editing line.

  • ARROW UP/DOWN: Shows sent commands from history.

Commands are auto converted to match correct upper or lower case. For example a main_scene is turned into MAIN_SCENE.

Issuing External Commands to Viz Engine via Console

External Control Applications, such as Viz Trio and Viz Pilot, communicate with Viz Engine through External Control commands. Viz Engine supports a wide range of such commands. Any installation of Viz Engine and Artist also come with the application Viz Send, which mimics the behavior of External Control Applications.

images/download/attachments/85913475/gs_viz_send.png

External Commands can also be sent manually to Viz Engine through the console window, using the send command. External commands range from loading a scene and taking the scene On Air, to shutting down Viz Engine. To issue a command to the Engine, open the console window and type send [COMMAND], then press enter. For example, the command VERSION can be used to display the current Viz version and build number: send VERSION CONSOLE: answer <Version: 3.8.2.55990>

Most commands also have a subset of commands. All commands in the Engine follow a specific syntax, and can be passed either properties or further commands. The general syntax structure is: [Leading flag] [Location] [Command] [Value]

Locations and commands may also have sub-locations or subsets of commands, respectively, in which case an asterisk serves as the divider between each part. Please see the examples below for a better understanding of how to address these.

  • Leading Flag: Define if Viz Engine should send a reply to the command being issued. A leading -1 indicates that no reply is required. Positive integers, including 0, serve as a command ID. This allows an external control application to match the reply to the corresponding command request, if several commands are sent simultaneously.

  • Location: The location can be the main object, configuration, an object ID, one of the object pools, a container or geometry, a key-frame, a shared memory (SHM) location, a layer, and so on. In addition, the location can be any command or property of such. In essence, anything in Viz could serve as the location for a command. As an example, a scene can be loaded into any one of the three layers in Viz; Back layer, Main layer and Front layer. The layers can be addressed by name:

    • RENDERER*MAIN_LAYER

    • RENDERER*FRONT_LAYER

    • RENDERER*BACK_LAYER
      In addition, the scene can be accessed directly by referring to the scene via its database path, UUID, REST URL or temporary object ID:

    • SCENE*SceneLocation

  • Command: The Command part of the syntax can consist of either a property or another command.

  • Value: The value for the command, which can be for example a numeric value, a location or a state.

    Tip: COMMAND_INFO is a very useful command, used to display help on any other command or subset. For example, passing the command send RENDERER COMMAND_INFO displays a list of all available properties and commands for the RENDERER command, while RENDERER*BACKGROUND displays properties and commands for the BACKGROUND sub-command of the RENDERER command.

Viz Engine can address locations in three ways, by either UUID, Path or REST:

  • UUID: Universally Unique Identifiers are always provided angle brackets, for example <1A85AC97-00AE-E74B-A236EDA262D69908>.

  • Path: The full path to the item, as seen in Viz Artist.

  • REST: In addition to the built-in Viz Engine REST Interface, Viz Engine also interprets Graphic Hub REST URLs as part of commands. Even though the commands themselves are case sensitive, the host names and UUIDs in REST URLs are not. The URLs may also contain special characters, like a forward slash.

These are all valid as locations when passing commands to Viz Engine, although they change the appearance of the command itself. Here is an example command setting an image as background image for the loaded scene, for each location method:

  • UUID: RENDERER*BACKGROUND*IMAGE*IMAGE SET IMAGE*<1A85AC97-00AE-E74B-A236EDA262D69908>

  • Path: RENDERER*BACKGROUND*IMAGE*IMAGE SET IMAGE*01_DOC_EXAMPLES/Images/Bear

  • REST: RENDERER*BACKGROUND*IMAGE*IMAGE SET IMAGE*http://GH\-SERVER:19398/image/1A85AC97\-00AE\-E74B\-A236EDA262D69908/Bear

Tip: Object IDs are temporary shortcuts created on the fly when an item is loaded into memory, and removed when unloading the item or restarting Viz. To get an objects Object ID, pass the GET command to the OBJECT_ID location of the object. For example: MAIN_SCENE*OBJECT_ID GET.

Internal Commands

For ease of use, internal commands can be set to be hidden or visible. Under certain circumstances, some plug-ins may need to send commands on every frame. This can leave the Viz Console window flooded with text, leaving it unreadable. By default, internal commands are hidden, meaning these messages do not output to the console window. To see all internal commands by default, the Viz configuration file must be manually edited, setting show_internal_commands to 1. During normal operation, however, it would usually suffice to temporarily activate the output of internal commands to the console, by clicking the images/download/thumbnails/85913475/v4_console.png (show commands) icon in the Viz Artist or Viz Engine GUI. This also makes the console window stay on top, meaning it is not hidden behind other full-screen applications, such as Viz Artist or an Engine in On Air Mode.