## On this page

  

 

 # ADR 3D Viewer Web Component

 Last update: 16.07.2025 

**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\<a class="el" href="namespace_a_n_s_y_s.xhtml" title="GLTFWriter API Documentation.">ANSYS</a> 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: `<a href="http://localhost:8000/ansys251/nexus/test/viewer_test.html">http://localhost:8000/ansys251/nexus/test/viewer_test.html</a>`

## 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.

<a class="anchor" id="renderer-options"></a>

### 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:

&lt;ansys-adr-viewer renderer_options='{"foo": "hello"}'&gt; &lt;/ansys-adr-viewer&gt;



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 &lt;ansys-adr-viewer&gt; element. In practice, code similar to the following may be used to access these methods (assuming instantiation as per the earlier example):

&lt;script&gt; 

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

 let image = viewer.renderImage();

 if (image) document.getElementById("img_target").src = image;

&lt;/script&gt; 



### 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*
    
    &lt;script&gt; 
    
     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});
    
    &lt;/script&gt;

## Events

The component is designed to communicate intrinsic status changes via custom JavaScript events.   
 Events are scoped to the &lt;ansys-adr-viewer&gt; 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:

&lt;script&gt; 

 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); 

&lt;/script&gt; 



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\]