ImageLoader

An ImageLoader is a Javascript plugin that is responsible for taking an ImageId for an image and returning the corresponding pixel data for that image to cornerstone. Since loading images usually requires a call to a server, the API for image loading needs to be asynchronous. The trend in Javascript for handling asynchronous operations is via the Promises/A+ Specification which is implemented by a number of libraries. See this page for some information regarding Promises/A+ libraries. Cornerstone will therefore assume that image loaders return a promise which cornerstone will use to receive the pixel data asynchronously or an error if one occurs. Cornerstone does not require any particular promise library and it should work with any library that is compliant with the Promises/A+ Specification (as well as jQuery which isn't 100% compliant). Here is an example of an image loader that fetches pixel data using XMLHttpRequest and uses jQuery to return a promise to cornerstone:

    function loadImage(imageId) {
        // create a deferred object
        var deferred = $.Deferred();

        // Make the request for the DICOM data
        var oReq = new XMLHttpRequest();
        oReq.open("get", imageId, true);
        oReq.responseType = "arraybuffer";
        oReq.onreadystatechange = function(oEvent) {
            if (oReq.readyState === 4)
            {
                if (oReq.status == 200) {
                    // request succeeded, create an image object and resolve the deferred
                    // Code to parse the response and return an image object omitted.....
                    var image = createImageObject(oReq.response);
                    // return the image object by resolving the deferred
                    deferred.resolve(image);
                }
                else {
                    // an error occurred, return an object describing the error by rejecting
                    // the deferred
                    deferred.reject({error: oReq.statusText});
                }
            }
        };
        oReq.send();

        // return the pending deferred object to cornerstone so it can setup callbacks to be 
        // invoked asynchronously for the success/resolve and failure/reject scenarios.
        return deferred;
    }

An Image Loader is responsible for return an Image object corresponding with the ImageId cornerstone passes to its loadImage function when it resolves the promise. An image loader registers itself for a given URL scheme using the registerImageLoader() API:

    // register the url scheme 'myCustomLoader' with our loadImage function
    cornerstone.registerImageLoader('myCustomLoader', loadImage);

General flow:

• ImageLoaders register themselves with cornerstone to load specific ImageId URL schemes
• The application requests to load an image using the loadImage() api. Cornerstone delegates the request to load the image to the ImageLoader registered with the url scheme of the imageId passed to loadImage().
• The ImageLoader will return a promise which it will resolve with the corresponding Image Object once it has obtained the pixel data. Obtaining the pixel data may may require a call to a remote server using XMLHTTPRequest, decompression of the pixel data (e.g. jpeg 2000) and conversion of the pixel data into the format that cornerstone understands (e.g. RGB vs YBR).

While pixel data is usually obtained from a server, that doesn't always have to be the case. The live examples actually use an ImageLoader plugin to serve up images without requiring a server at all. In this case, the images are base64 encoded and stored in the ImageLoader plugin itself. The plugin simply converts the base64 pixel data into an array of pixels. Alternatively, one could write an image loader that generates derived images on the client side. For example, you could implement MPR functionality this way.

Consider using the cornerstone WADO Image Loader or the cornerstone Web Image Loader. A WADO-RS image loader is expected in the near future as well.