Knowledge Base | What's New | Contact Us |

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:

  1. include IcmJS source code.
  2. create container element (usually 'div')
  3. 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:
      
              // Create ActiveIcmJS inside container with id="con"
              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
        • name: string containing name for 3D object (usually is used for MOL or PDB format)
        • onload: callback function which will be called after the load process is finished.
        • data: any object containing data which will be passed as an argument for the callback above
    • 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

      Arguments:
      • urlToIcmScript: url containing path to ICM script
      • onLoadCallBack: function to be called when script is loaded and executed.

    • Example:
      
              act.CallScript( "http://domain.org/_macro", function () {
                  // script loading is done at that point
                  // Let's read some data
                  act.OpenProject("http://www.rcsb.org/pdb/files/4rws.pdb.gz", {
                      // object is loaded at that point
                      act.RunCommands("cool a_");
                    }
                  )
              } );
              
  • GetShellVar( string icmVarName )

    Converts the icm variable with icmVarName into an appropriate JavaScript type and returns it

      Arguments:
      • icmVarName: name of icm shell variable

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


Copyright © 2018 Molsoft LLC.
All rights reserved.
Terms of Use
Privacy Policy