Molsoft ActiveIcm for JavaScript (IcmJS) technical manual

Introduction to the Molsoft IcmJS

| IcmJS Webinar Recording |
IcmJS (Formerly known as ActiveIcmJS) is a JavaScript/HTML5 version of the ActiveICM plugin. Since early 2015 Chrome no longer supports NPAPI plugins because of security and compatibility issues (other browsers may follow too) Molsoft released JavaScript/HTML5 version which does not require any plugin or browser extension and runs inside any modern browser. It uses low-level subset of JavaScript (asm.js) technology which runs extremely fast (only 2-4 times slower than native code).

This makes it a perfect tool for data sharing and publishing.

Quick Start

The simplest way to embed a 3D object into your web page is shown in the HTML code below: There are three basic steps:

include IcmJS source code.
create container element (usually 'div')
create JavaScript function with special name 'onLoadActiveIcm' where initialization code needs to be placed.


<html>
<head>
<script src="lib/acticm.js"> </script>
</head>

<body>
<h2>IcmJS Demo Page</h2>

<div id="con" style="width: 800px; height: 600px; border: 2px solid #ABABAB">
</div>

<script>
function onLoadActiveIcm()
{
act = new ActiveIcmJS("con");
act.projectFile = "myproject.icb"; // or pdb, mol
}

</script>
</body>
</html>

Technology

We use emscripten compiler to compile C/C++ code into highly optimizable, low-level subset of JavaScript called asm.js. Most modern browsers will recognize asm.js, compile, optimize and run at near native speed.

Another part was to port OpenGL calls into WebGL subset. We implemented efficient run-time layer which translates normal OpenGL functions into WebGL compatible calls. That allows us to keep the same code-base and bring highest quality 3D graphics inside the browser almost without any restrictions.

JavaScript API

Module.ActiveIcm object

Module.ActiveIcm is a JavaScript object which implements single ICM shell and graphics window. You may have multiple IcmJS object on the same web page.

Methods:

Constructor( string parentContainerId)
- Arguments:
  - parentContainerId : id of the container object (string)
- Return value: created ActiveIcmJS object
- Example:
```
var act = new ActiveIcmJS("con");
```

OpenProject( string urlToFile, object options )
Opens ICB,PDB or MOL file from the specified URL
- Arguments:
  - urlToFile: relative or absolute path to the project. Currently supported formats are: ICB,PDB,MOL.
  - options: a JavaScript object with possible optional fields
- Return value: none
- Notes on asynchronous nature of the OpenProject:
  All JavaScript calls which load data are asynchronous which means that function returns immediately while the download is left in the background. If you want to perform some post processing after the load is finished you need to provide a callback function in the options object.
- Example:
```
var act.OpenProject( "1xbb_test.icb",
{
onload: function () {
act.RunCommands("color background white");
act.RunCommands("display atom label");
}
}
)
```

RunCommands( string icmCommands )
Runs any icm script
- Arguments:
  - icmCommands: icm code to run.
- Return value: none
- Example:
```
act.RunCommands("display cpk a_H");
```
IMPORTANT: You cannot use 'read' command in the ICM sciript which called from ActiveIcmJS. You should use ~OpenProject method instead.

RunCommandsValue( string icmCommands )
The same as above but the last expression is returned
- Return value: result of the last expression from the ICM shell converted into JavaScript.
- Example:
```
var randomFromIcm = act.RunCommandsValue("Random()");
```
CallScript( string urlToIcmScript, function onLoadCallBack )
Loads and runs remote script into the shell. Can be useful to load a set of macros
- Example:
```
act.CallScript( "http://domain.org/_macro", function () {


act.OpenProject("http://www.rcsb.org/pdb/files/4rws.pdb.gz", {

act.RunCommands("cool a_");
}
)
} );
```
GetShellVar( string icmVarName )
Converts the icm variable with icmVarName into an appropriate JavaScript type and returns it
- Example:
```
act.GetShellVar("i_out");
act.GetShellVar("c_out");
```

Properties:

version (~~string,~~readonly)
holds ActiveIcmJS version
projectFile (~~string,~~read/write)
Holds current project file.
Example:
```
act.projectFile = "myfile.icb"
```
nofActiveDownloads (~~integer, readonly)
holds number of active downloads
nofSlides (~~integer, readonly)
holds number of slides in the current project
currentSlide (~~integer, read/write)
holds current slide
anaglyphStereo (~~boolean, read/write)
toggles anaglyph stereo mode
rockView (~~integer, read/write)
toggles rocking mode
webglContext (~~integer, readonly)
returns WebGL context handle. Zero means no context was created
sequenceViewVisible (~~boolean, read/write)
toggles visiblity of sequence view
searchBarVisible (~~boolean, read/write)
toggles visiblity of top search bar
tableViewVisible (~~boolean, read/write)
toggles visiblity of table view
onDisplayChange (~~function, read/write )
Holds display state change callback.
onLoadProject (~~function, read/write)
Holds global load project callback.