ADR 3D Viewer Web Component

Note: This component is a work in progress and this documentation is incomplete/preliminary.

The Ansys ADR Viewer is a web component capable of rendering 3D geometry in a web page using different rendering configurations. The component can render in the browser using WebGL or remote over VNC (e.g. accessing EnSight or EnVision remote instances). This component is automatically made available using the websocketserver_cli (the component is served under /ansys251/nexus in that configuration).

Instantiation

A simple example of using the component in a web page:

<head> 
  <script src="/ansys251/nexus/viewer-loader.js"></script> 
</head> 
<body> 
  <div> 
    <ansys-adr-viewer 
      id="Viewer" 
      src="/ansys251/nexus/test/viewer_test.avz" 
      proxy_img="/ansys251/nexus/images/ANSYS_icon.png" 
      active=true>
    </ansys-adr-viewer>
  </div> 
</body> 

If there is an Ansys installation located at: C:\Program Files\ANSYS Inc\v251 one can run an example with:

cd C:\Program Files\ANSYS Inc\v251\CEI\nexus251

..\bin\cpython -m http.server 8000

And then browse to the URL: http://localhost:8000/ansys251/nexus/test/viewer_test.html

Properties

The web component element supports several properties:

active: If this is true, the 3D view will be active. If false, the proxy image is displayed (if no proxy image is specified, a "blank" launch image will be presented).
aspect-ratio: the viewer does not support explicit width/height specification and will be sized to fill the parent element with one exception. If 'aspect-ratio' is set, the height will be the (dynamic) width divided by the aspect-ratio value. If 'aspect-ratio' is set to the string 'proxy', the aspect ratio of the proxy image will be used.
guid: a string property that is a unique identifier for the component instance. This defaults to a pseudo-guid that is unique only vs other ansys-nexus-viewer components in the same web page. This property may be set when the element is instantiated but cannot be changed afterward.
src: URL to the source 3D geometry. Validity varies by renderer type. The 'webgl' renderer supports '.avz', '.dsco' and '.scdoc' files. The 'three' renderer supports '.glb' files. The 'envnc' renderer supports '.evsn'. A read/write property.
src_ext: In some situations, src may be a data URI. In this situation, the component cannot determine the actual file format. Setting this property to the natural filename extension allows a data URI to be used with src. For example: setting src_ext='avz' will allow an AVZ data URI to be passed to src.
proxy-img: URL to a PNG image that should be used as the proxy image when the 3D component is not active.
renderer: the back-end renderer to use. 'webgl' is the default and can support AVZ, SCDOC and DSCO format geometry. 'three' selects a render that supports geometry in the GLB file format. 'envnc' is supported in conjunction with websocketserver_cli local session configurations. This property may only be specified when the element is created.
renderer_options: a read-only property specified as a json string containing renderer specific options. Options are generally specific to a given renderer. Details may be found here Renderer Options.
parts: a read-only property that returns a list of the part names present in the instance. This property will change when the src changes and, depending on the nature of the geometry source may change organically.

Renderer Options

Each renderer may support a collection of renderer specific options. These generally allow for the customization of the renderer behavior and display. The supported options are listed here. Note that the element renderer_options property is a JSON format string. In this documentation, the properties in the resulting object are lists. For example, a property named foo would be specified to have the value 'hello' as:

<ansys-adr-viewer renderer_options='{"foo": "hello"}'> </ansys-adr-viewer>

Generally, renderers will ignore renderer_options they do not recognize and the options cannot be changed once the element has been realized.

"webgl" Specific Options

There are a number of "webgl" features that can be disabled using renderer_options. By default (no renderer_options specified) the following are enabled: showFit, showClip, showFull. If an empty renderer_options is specified (renderer_options='{}'), all the 'show' options will be enabled by default and one must specify which need to be disabled by setting them to false.

Option	Description
showFit	Enable the "fit" geometry option
showHighlight	Enable the body, face, edge selection modes
showClip	Enable the clipping mode
showExplode	Enable the "explode" geometry optiont
showViewport	Allow multiple viewports to be used
showFull	Enable the "fullscreen" option
showLogo	Include the Ansys logo in the render window
showAbout	Enable the "about" dialog
showOptions	Allow GUI control remapping
showMarkup	Enable annotation editting
showFileOpen	Allow the user to select and read local files

Common collections of options might include.

The default interface:

renderer_options='{"showLogo": false, "showFileOpen": false, 
                   "showHighlight": false, "showAbout": false, 
                   "showMarkup": false, "showOptions": false,
                   "showViewport": false, "showClip": true, 
                   "showExplode": false, "showFull": true, 
                   "showFit": true}'

Common interface options:

renderer_options='{"showFileOpen": false, "showOptions": false,
                   "showLogo": false, "showAbout": false, 
                   "showMarkup": false, "showViewport": false, 
                   "showHighlight": false, "showClip": false, 
                   "showExplode": false, 
                   "showFull": true, "showFit": true}'

Methods

There are several methods calls that can be made on the <ansys-adr-viewer> element. In practice, code similar to the following may be used to access these methods (assuming instantiation as per the earlier example):

<script> 
  var viewer = document.getElementById("Viewer"); 
  let image = viewer.renderImage();
  if (image) document.getElementById("img_target").src = image;
</script> 

Method Details

renderImage(): returns a data URL of the RGB contents of the currently rendered image. Note: if the component is not active, this call will activate it.
setAttributes(target, name, values): Change attributes for an object. Note: this method is only implemented for SCDOC files.
- target specifies the type of object to change. The only supported value for target is "part".
- name specifies the specific name of the object to change. For a target "part", this should be a name returned in the parts property. Note: name can also be a regex expression.
- values is an object containing the new values to be set. Valid keys in the values object include:
  - visible a boolean value of true or false
  - color the base color of the object as a 32bit integer: 0xAARRGGBB AA=alpha, RR=red, GG=green, BB=blue
  - edge_color is the color of the object lines in the same format as color
getAttributes(target, name): Query the attributes for an object. Note: this method is only implemented for SCDOC files.
- target specifies the type of object to query. The only supported value for target is "part".
- name specifies the specific name of the object to query. For a target "part", this should be a name returned in the parts property.
- The return value is an object with the following keys:
  - visible a boolean value of true or false
  - color the base color of the object as a 32bit integer: 0xAARRGGBB AA=alpha, RR=red, GG=green, BB=blue
  - edge_color is the color of the object lines in the same format as color
<script>

var viewer = document.getElementById("Viewer");

let parts = viewer.parts;

console.log(viewer.getAttributes("parts", parts[0]));

// Change to transparent blue with solid black edges

viewer.setAttributes("parts", parts[0], { color: 0x80000066, edge_color: 0xff000000, visible: true});

</script>

Events

The component is designed to communicate intrinsic status changes via custom JavaScript events.
Events are scoped to the <ansys-adr-viewer> element and handlers should be attached to the viewer element itself. An example of connecting to the partlist changed event assuming instantiation via the previous example code:

<script> 
  function partlistChangedFunc(e) { 
     var obj = document.getElementById("Viewer"); 
     const new_list = obj.parts; 
     // Event handler code goes here...
  } 
 
  var viewer = document.getElementById("Viewer"); 
  viewer.addEventListener("parts-changed", partlistChangedFunc); 
</script> 

In general, events do not contain significant data payloads, relying on properties to contain the changed state values.

Event Details

There are a number of available events. Many are in common over all the renderers, but not all.

Event	Trigger	Renderer	Details
active-changed	'active' changes	all	{active: bool}
src-changed	'src' changes	all	{src:url, ext:filename_ext}
parts-changed	'parts' changes	webgl,envnc	{}
proxy-img-changed	'proxy-img' changes Note: not the actual aspect ratio, just the property	all	{proxy_image:url}
aspect-ratio-changed	'aspect-ratio' changes	all	{aspect_ratio: float}
part-attributes-changed	Emitted when setAttributes() is called.	SCDOC	{parts:[names], changed:[attrnames]}
gltfviewer-spaceclaim-showhover	tooltip changes	webgl SCDOC datafile	{tip:tiptext}
gltfviewer-spaceclaim-showfacepoint	a point is picked on a face/edge/body	webgl SCDOC datafile	{x:float,y:float,z:float}
gltfviewer-spaceclaim-pick	new entity is selected (face/edge/body) The viewer must be in picking mode.	webgl SCDOC datafile	see below

gltfviewer-spaceclaim-pick details:

name: part name
path: complete "path" to the pick target
type: SELECTION_NONE|SELECTION_EDGE|SELECTION_FACE|SELECTION_BODY

Additional fields if type==SELECTION_EDGE or type==SELECTION_FACE:

min: [xmin, ymin, zmin]
max: [xmax, ymax, zmax]
vertices: [[x,y,z], ...]

Additional fields if type==SELECTION_BODY:

min: [xmin, ymin, zmin]
max: [xmax, ymax, zmax]

Post-processing tools 2025 R1