Configuration#

webvis uses three types of configuration options and provides methods with different scopes to change these settings. The category which a setting belongs to is determined by which part of webvis it affects. The configuration options that webvis provides are categorized into:

context settings (see SettingStrings) affecting everything depending on a webvis context.
viewer settings (see ViewerSettingStrings) affecting everything a viewer displays.
UI settings (see UISetting) affecting the webvis UI components.

Some mechanisms to manage settings support all of these categories, while others are intended for use with a specific category. Your decision of what configuration mechanism to choose should be guided by what setting you want to change and how far-reaching you want your configuration to be. The following configuration mechanisms are listed in the order of interpretation, so a setting configured by a latter mechanism overrides a former one:

mechanism	scope	context settings	viewer settings	UI settings
helm chart (values.yaml)	instance	✔️	✔️	✔️
app-side `webvis.config.json`	application	✔️	✔️	✔️
`webvis-config` component	document	✔️	✔️	✔️
URL parameter	document	✔️	✔️	✔️
`SettingsAPI.changeSetting`	webvis context and all viewers of a context	✔️	✔️	❌
`ViewerAPI.changeSetting`	webvis viewer	❌	✔️	❌
`webvisUI.setSetting`	webvis UI	❌	❌	✔️

Configuration files#

There are two locations webvis uses to retrieve configuration resources over the network. In both cases, the name of the resource is webvis.config.json:

A resource called webvis.config.json is retrieved relative to the location of the script file webvis.js. instant3Dhub generates this file based on the webvis.settings configuration in the instant3Dhub helm chart’s values.yaml. You can find the current configuration in the i3dhub-config-webvis ConfigMap deployed on your cluster.
A resource called webvis.config.json is retrieved relative to the location of the current document’s location. This configuration allows you a per-application customization scoped only to documents in the same path as the configuration file.

Example of configuring a language instance-wide through a helm release:

# Within helm/values.yaml:
webvis:
  settings:
    language: de

Example of configuring a language for your application (webvis.config.json served next to your application document):

{
    "language": "de"
}

Using the Configuration component#

The configuration component is part of the webvis UI. When a webvis UI element is initialized, it uses the first element with the tag name ẁebvis-config to read configuration from. This element’s ìnnerText must be JSON-formatted and can contain the same content as the configuration files listed above. This configuration applies to all contexts of your application.

Example:

<webvis-config>
  {
     "language": "de"
  }
</webvis-config>

Using URL Parameters#

All configuration values that are either of type boolean or type string can be set through specifying a URL parameter with the same key you would use in a configuration file and a value:

Set variables of type boolean:
- Using a parameter without a value sets a setting to true, e.g. http://example.org/myapp.html?silhouetteEffect.
- Setting a configuration value to false is done explicitly, e.g. http://example.org/myapp.html?xrEnabled=false.
Set a variable of type string explicitly, e.g. http://example.org/myapp.html?notificationLogLevels=ERROR.

A small number of settings might be unavailable for configuration through this method for security reasons. Currently, this only includes allowAnnotationsFromUntrustedSource.

Using the APIs#

The SettingsAPI can be used to set and reset settings on particular webvis contexts dynamically at runtime:

webvis.getContext().changeSetting(webvis.SettingStrings.SESSION_MEMBER_NAME, "myName"); // Set the name when connecting to a session on this context

Besides context settings, viewer settings can be changed by the SettingsAPI:

webvis.getContext().changeSetting(webvis.ViewerSettingStrings.GIZMOS_ENABLED, false); // Disables displaying gizmos on all viewers of this context

If you want to change the configuration of a specific viewer, use the ViewerAPI to do so:

const myViewer = await document.querySelector("#myWebvisElement").requestViewer();
myViewer.changeSetting(webvis.ViewerSettingStrings.GIZMOS_ENABLED, false); // Disables displaying gizmos on myViewer

UI settings can be configured through the global webvisUI element:

webvisUI.setSetting(webvisUI.UISetting.CONTEXT_MENU_ENABLED, false); // Disables the context menu

The reset methods SettingsAPI.resetSetting, ViewerAPI.resetSetting, or webvisUI.resetSetting reset a given setting to its default value. Using SettingsAPI.resetSetting with an entry from ViewerSettingStrings will reset the setting to the default value on all viewers of the context. The default value is the value a setting has when no other configuration, regardless what configuration mechanism is used, is specified.

Using HTML Attributes#

The webvis-full element allows for two additional attributes, src and autoplay. These attributes provide the capability to specify a model which should be loaded initially and to enable it right after its addition. For more information, please see the webvis tutorial.

Importing a configuration#

You can import a configuration using the function importConfig taking a key-value-based configuration object as a parameter:

const config =
{
    coordSys : "-yz",
    language : "de"
};
context.importConfig(config);