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
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.
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
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.
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
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
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")
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
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
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.jsApp 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")