Beginners Guide

Beginners Guide for the F.A.S.T. Cloud SDK

The following section provides an introductory guide for the F.A.S.T. Cloud SDK. While this is one of the longer sections, it is recommended that this section is reviewed prior to writing your first application since it provides a solid foundation of the overall framework and will guide you in selecting the best approach for the integration.

Basic HelloFovia Application -- 3D

F.A.S.T. WebAppBuilder

Click on a local copy of http://localhost:8088/apps/hellofovia/hellofovia5.html to open up the basic application.  This renders the demo dataset with the bone preset and uses default mouse operations and touch gestures adapters that work on any browser or mobile device.  Below are the minimal number of lines of HTML and JavaScript required to add live volume rendering to any web page, similar design patterns are used in many examples.

HTML

<html>
    <script src="/foviaAPI.js"></script>
    <script src="/apps/hellofovia/hellofovia.js"></script>   
    <canvas id="fovia"></canvas>
</html>


The first line references the minimized Cloud SDK client-side API.  The second line is the example  JavaScript app shown below.  The third defines an HTML canvas element with an ID of "fovia", which is referenced below in the JavaScript.

JavaScript

/// <reference path="../../foviaAPI.d.ts"/>
// simple 5 lines example to get an interactive 3D imaage on screen
Fovia.FoviaAPI.requestServerConnection(function (err) {
    Fovia.ServerContext.loadDICOMDir("data/democases/DICOM2").then(function (volumeDataContext) {
        var foviaViewport = new Fovia.UI.HTMLViewport3D("fovia", window.innerWidth, window.innerHeight);
        foviaViewport.init(volumeDataContext, Fovia.RenderType.parallel).then(function () {
            foviaViewport.renderFinal();
        });
    });
});


Fovia.FoviaAPI.requestServerConnnection initiates a connection between the client and server.  When this succeeds, it invokes the supplied callback function specified in the next set of lines.  First,  loadDICOMDir  loads the default dataset (located in a path relative to the foviaserver directory).  Upon successful data loading, the volumeDataContext is returned in its callback function.  This object also includes the DICOM tags associated with this volume, which is printed in the console.  Next, a synchronous call to the constructor of Fovia.UI.HTMLViewport3D that is associated with an HTML5 Canvas (or IMG) element ID "fovia".  After construction, an asynchronous call is made to init that initializes and renders the dataset with the supplied volumeDataContext. The last line triggers a renderFinal operation, which internally updates the canvas with the new pixels.

This example has been simplified with no error checking, error handling will be described in a subsequent section.

Basic HelloFovia Application -- 2D

F.A.S.T. WebAppBuilder

Click on a local copy of http://localhost:8088/apps/hellofovia/2d.html to open up the basic 2D application.  This renders an axial view of  the demo dataset and uses default mouse operations and touch gestures adapters that work on any browser or mobile device.  Below are the minimal number of lines of HTML and JavaScript required to add live volume rendering to any web page.

HTML


<html>
    <script src="/foviaAPI.js"></script>
    <script src="/apps/hellofovia/2d.js"></script>   
    <canvas id="fovia"></canvas>
</html>


The first line references the minimized Cloud SDK client-side API.  The second line is the example  JavaScript app shown below.  The third defines an HTML canvas element with an ID of "fovia", which is referenced below in the JavaScript.

JavaScript

/// <reference path="../../foviaAPI.d.ts"/>
// request server connection, once successfully established, load a demo dataset
Fovia.FoviaAPI.requestServerConnection(function (err) {
    Fovia.ServerContext.scanDICOMDir("data/democases/DICOM2").then(function (scanDirResults) {
        // obtain a list of seriesDataContext objects for the first study found
        var seriesList = scanDirResults.findStudy(0);
        console.log(seriesList);
        // create a 2D viewport using the full browser window (synchronous call)
        var viewport = new Fovia.UI.HTMLViewport2D("fovia", window.innerWidth, window.innerHeight);
        // initialize the viewport with the first series (there is only one for th is study),
        //  and once this is complete, trigger a renderFinal to generate the image
        viewport.init(seriesList[0].dicomSeries).then(function () {
            viewport.renderFinal();
        });
    });
});


Fovia.FoviaAPI.requestServerConnnection initiates a connection between the client and server.  When this succeeds, it invokes the supplied callback function specified in the next set of lines.  First,  scanDICOMDir loads the default dataset (located in a path relative to the foviaserver directory).  Upon successful data loading, the scanDirResults is returned which contains a complete breakdown of all studies, series, and image objects found within the directory.  Using findStudy, a  list of seriesDataContext objects can be retrieved using either a studyInstanceUID or a specific ID from within scanDirResults.  The seriesDataContext will include a subset of the DICOM tags for all images in the series.  The next line is a synchronous call to the constructor of Fovia.UI.HTMLViewport2D that is associated with an HTML5 Canvas (or IMG) element ID "fovia".  Next comes an asynchronous call to init that initializes and renders the dataset with the supplied seriesDataContext. The last line triggers a renderFinal operation, which internally updates the canvas with the new pixels.  For a complete explanation for the details of the scanDirResults, please review the Data Loading section.

This example has been simplified with no error checking, error handling will be described in a subsequent section. 

API Signature

The majority of  JavaScript API methods are invoked in an asynchronous manner to ensure that the browser is never blocked.  The Fovia API offers two design patterns for invoking of asynchronous which include the original JavaScript convention where the last parameter is the callback function, and the the modern approach of using Promises (.then(function(data) {}) .catch(function(err) {}).  While Promises is now a standard part of modern browsers, during the client initialization of the Cloud SDK, a check is made to see if Promises is available, and if not, a polyfill is defined to ensure this design pattern is available across all older browsers.

There are several benefit of using Promises, which include the ability to utilize default parameters and the ability to execute multiple asynchronous commands at the same time, and wait for all to complete using Promise.all as shown in the mpr.js example.  Without this, one would need a nested sequence of callbacks.  While the API supports both approaches, all examples utilize Promises since it is easier to read and works across all browsers.

While all examples utilize Promises, click on a local copy of helloFoviaNoPromise for an example to demonstrate how to invoke the API using the original asynchronous JavaScript calling convention.  Documented source code is found inside ./foviaserver/public/apps/hellofovia/nopromise.js

TypeScript / JavaScript Compatibility

The Cloud SDK API is 100% JavaScript ES5 compatible, and works on older browsers, including IE11.  All examples use HTML Canvas tags,  although the API does support the IMG tag and could be used.   Internally, the F.A.S.T. Cloud SDK is implemented using TypeScript, which get compiled into ES5 compatible JavaScript.  There are many benefits of TypeScript, including type checking, classes, and the ability to utilize many of the ES6 capabilities (such as Lambda functions) that are converted into ES6 compatible code.  Regardless if you choose to use TypeScript, you should always include the ./foviaserver/public/foviaAPI.d.ts type definition file at the top of all your JavaScript files so you development tools, including Microsoft Visual Studio Code and WebStorm  can still utilize the IntelliSense capabilities.

If you choose to use TypeScript, you will automatically get type checking that is provided by the Fovia API.   Click on a local copy of helloFoviaTypeScript for an example to demonstrate the use of TypeScript.  Documented source code is found inside ./foviaserver/public/apps/hellofovia/typescript.ts

Also, the F.A.S.T. Cloud App Builder   utilizes the Angular framework and is written in TypeScript. 

Error Handling

In order to keep the examples more streamlined and easier to understand, only a minimal amount of error handling is implemented.  Please consult the API documentation for an explanation of all the error codes returned.  For the original asynchronous JavaScript calling convention, the first parameter in the callback function contains the return code.  Code should compare against Fovia.ReturnCode.ok to check for an error condition.  If using Promises, the error code is returned as its first argument.  The simple HelloFovia example has been expanded to include complete error handling in a localy copy of helloFoviaFoviaComplete example app.  Documented source code is found inside ./foviaserver/public/apps/hellofovia/hellofoviaComplete.js

App Deployment

Cloud SDK provides default web application configuration settings defined by the <url> in ./foviaserver/config/configuration.xml.  The "urls" tag contain strings (relative file paths) that are appended to ./foviaserver/public directory and Cloud SDK binds the URL to the specified directory.   Please see the System and Network Configuration Settings section for more details.

Event Logging / Debugging

For development purposes, it may be useful to use the full (non-minimized) version of the foviaAPI.js.  Open up the directory foviaserver/public and save the original minimized fovia.API.js and replace it with the full version.  Be sure to restore the original minimized version prior to releasing your product.

While event logging is more of an advanced concept, understanding JavaScript debugging capabilities as you start your integration will be well worth your time.  At a minimum, ensure that the browser console window is open to capture any possible warning messages generated from the F.A.S.T. Cloud SDK.  Alternatively, you can install a browser plug, such as JavaScript Error Notifier for Chrome that pops up a dialog for any warning message.

While the standard JavaScript console.log will print out messages to the console, alternatively, you may utilize the Fovia.Logger package that sends both server and client logging messages to both the console and server log file.  Basic logging functionality is configured in a similar manner as log4j, that provides different levels of debugging (debug, info, warn, error) to console and server log file (./foviaserver/log/foviaServer_ddmmyyyy_hhmmss.log file. )

By default both server and client logging is set to the warn level.  To change to the info level, invoke Fovia.Logger.setDebugLevel(Fovia.Logger.level.info).  An info message will be sent to both browser and log file with this line:  Fovia.Logger.info("this is an info message")