diff --git a/README.md b/README.md index f9a7703b..b61eeb63 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,183 @@ -[![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![MIT License][license-image]][license-url] [![Build Status][travis-image]][travis-url] +[![NPM version][npm-version-image]][npm-url] +[![NPM downloads][npm-downloads-image]][npm-url] +[![MIT License][license-image]][license-url] +[![Build Status][travis-image]][travis-url] [![Coverage Status][coverage-image]][coverage-url] -cornerstone WADO Image Loader -============================= - -A [cornerstone](https://github.com/cornerstonejs/cornerstone) Image Loader for DICOM P10 instances over -HTTP (WADO-URI) or DICOMWeb (WADO-RS). This can be used to integrate cornerstone with WADO-URI -servers, DICOMWeb servers or any other HTTP based server that returns DICOM P10 instances - (e.g. [Orthanc](http://www.orthanc-server.com/) or custom servers) - -Troubleshooting ---------------- - -Having problems viewing your images with cornerstonWADOImageLoader? Check out the -[troubleshooting guide](https://github.com/cornerstonejs/cornerstoneWADOImageLoader/wiki/troubleshooting). - -Live Examples ---------------- +# cornerstone WADO Image Loader + +A [cornerstone](https://github.com/cornerstonejs/cornerstone) Image Loader for +DICOM P10 instances over HTTP (WADO-URI) or DICOMWeb (WADO-RS). This can be used +to integrate cornerstone with WADO-URI servers, DICOMWeb servers or any other +HTTP based server that returns DICOM P10 instances (e.g. +[Orthanc](http://www.orthanc-server.com/) or custom servers) + +## Key Features + +- Implements a + [cornerstone ImageLoader](https://github.com/cornerstonejs/cornerstone/wiki/ImageLoader) + for DICOM P10 Instances via a HTTP get request. + - Can be used with a WADO-URI server + - Can be used with Orthanc's file endpoint + - Can be used with any server that returns DICOM P10 instances via HTTP GET +- Implements a + [cornerstone ImageLoader](https://github.com/cornerstonejs/cornerstone/wiki/ImageLoader) + for WADO-RS (DICOMWeb) +- Supports many popular transfer syntaxes and photometric interpretations + [see full list](https://github.com/cornerstonejs/cornerstoneWADOImageLoader/blob/master/docs/TransferSyntaxes.md) + and [codec](docs/Codecs.md) for more information. +- Framework to execute CPU intensive tasks in [web workers](docs/WebWorkers.md) + - Used for image decoding + - Can be used for your own CPU intensive tasks (e.g. image processing) + +## Live Examples [Click here for a live example of this library in use!](http://rawgithub.com/cornerstonejs/cornerstoneWADOImageLoader/master/examples/index.html) You can also see it in action with the [cornerstoneDemo application](https://github.com/chafey/cornerstoneDemo). -Install -------- +## Install Get the distributed unminimized file: -* [cornerstoneWADOImageLoader.js](https://unpkg.com/cornerstone-wado-image-loader/dist/cornerstoneWADOImageLoader.js) +- [cornerstoneWADOImageLoader.js](https://unpkg.com/cornerstone-wado-image-loader/dist/cornerstoneWADOImageLoader.js) or the distributed minimized file: -* [cornerstoneWADOImageLoader.min.js](https://unpkg.com/cornerstone-wado-image-loader/dist/cornerstoneWADOImageLoader.min.js) +- [cornerstoneWADOImageLoader.min.js](https://unpkg.com/cornerstone-wado-image-loader/dist/cornerstoneWADOImageLoader.min.js) -Usage -------- +## Usage -The cornerstoneWADOImageLoader depends on the following external libraries which should be loaded before cornerstoneWADOImageLoader.js: +The cornerstoneWADOImageLoader depends on the following external libraries which +should be loaded before cornerstoneWADOImageLoader.js: - -1. [dicomParser](https://github.com/cornerstonejs/dicomParser) +1. [dicomParser](https://github.com/cornerstonejs/dicomParser) 2. [cornerstone](https://github.com/cornerstonejs/cornerstone) -*New in 1.0.0*: Specify the cornerstone instance you want to register the loader with. +_New in 1.0.0_: Specify the cornerstone instance you want to register the loader +with. -````javascript +```javascript cornerstoneWADOImageLoader.external.cornerstone = cornerstone; -```` +``` Have your code configure the web worker framework: ```javascript - var config = { - maxWebWorkers: navigator.hardwareConcurrency || 1, - startWebWorkersOnDemand : true, - }; - cornerstoneWADOImageLoader.webWorkerManager.initialize(config); +var config = { + maxWebWorkers: navigator.hardwareConcurrency || 1, + startWebWorkersOnDemand: true, +}; +cornerstoneWADOImageLoader.webWorkerManager.initialize(config); ``` -See the [web workers](docs/WebWorkers.md) documentation for more details on configuring. - -Key Features ------------- - -* Implements a [cornerstone ImageLoader](https://github.com/cornerstonejs/cornerstone/wiki/ImageLoader) for DICOM P10 Instances via a HTTP get request. - * Can be used with a WADO-URI server - * Can be used with Orthanc's file endpoint - * Can be used with any server that returns DICOM P10 instances via HTTP GET -* Implements a [cornerstone ImageLoader](https://github.com/cornerstonejs/cornerstone/wiki/ImageLoader) for WADO-RS (DICOMWeb) -* Supports many popular transfer syntaxes and photometric interpretations [see full list](https://github.com/cornerstonejs/cornerstoneWADOImageLoader/blob/master/docs/TransferSyntaxes.md) and [codec](docs/Codecs.md) for more information. -* Framework to execute CPU intensive tasks in [web workers](docs/WebWorkers.md) - * Used for image decoding - * Can be used for your own CPU intensive tasks (e.g. image processing) - -Backlog -------- - -* Support for images with pixel padding -* Support for high bit (e.g. mask out burned in overlays) -* Free up DICOM P10 instance after decoding to reduce memory consumption -* Add support for compressed images to WADO-RS loader -* Look at using EMSCRIPTEN based build of IJG for JPEG -* Consolidate all EMSCRIPTEN codecs into one build to cut down on memory use and startup times -* Add support for bulk data items to WADO-RS Loader -* Add events to webWorkerManager so its activity can be monitored -* Add support for issuing progress events from web worker tasks - -FAQ -=== +See the [web workers](docs/WebWorkers.md) documentation for more details on +configuring. + +## Upgrade to CWIL v4.x + +Cornerstone-WADO-Image-Loader (CWIL) v4.0.x has been released, which adds +support for using WebAssembly (WASM) builds of each codec. This significantly +improves image decoding performance and enables us to load codec at runtime when +needed dynamically, which reduces the build time and complexity. + +In addition, we have improved the image loading performance in CWIL v4.x. In +previous versions of CWIL, image loading includes fetching AND decoding an image +before returning a promise completion, preventing more requests from being made +until the queue is empty. This limitation has been fixed in CWIL v4, which +separates image retrieval and decoding into two steps. Now after an image is +retrieved, a new request is sent to the server immediately. + +| | Improvement | +| ------------------- | -------------------------------------------------- | +| CWIL Bundle Size | 30x smaller (3.0 MB vs 87 kb with dynamic import) | +| JPEG Baseline Codec | 4.5x faster (2.87 ms for 512x512 16 bit CT Slice) | +| JPEG 2000 Codec | 1.8x faster (41.02 ms for 512x512 16 bit CT Slice) | + +### Steps to upgrade + +#### Dynamic Import + +In v4.x, we have added dynamic importing support for the codecs as needed. To be +able to use such feature, instead of + +```js +import cornerstoneWADOImageLoader from 'cornerstone-wado-image-loader'; +``` + +you need to do: + +```js +import cornerstoneWADOImageLoader from 'cornerstone-wado-image-loader/dist/dynamic-import/cornerstoneWADOImageLoader.min.js'; +``` + +This way, codecs are loaded dynamically when needed. You have another option to +create an alias in the webpack config file as we do +[here](https://github.com/OHIF/Viewers/blob/33307d3cd28599cbb4d7189560afdd7f65033ab8/platform/viewer/.webpack/webpack.pwa.js#L65) +for OHIF Viewer. + +```js +resolve: { + alias: { + 'cornerstone-wado-image-loader': + 'cornerstone-wado-image-loader/dist/dynamic-import/cornerstoneWADOImageLoader.min.js', + }, +}, +``` + +In addition WASM builds of the codec files should be made available in the build +folder. We use `CopyWebpackPlugin` to copy the WASM files to the build folder. +See +[here](https://github.com/OHIF/Viewers/blob/33307d3cd28599cbb4d7189560afdd7f65033ab8/platform/viewer/.webpack/webpack.pwa.js#L100) +for how we do it in OHIF Viewer. + +```js + plugins: [ + new CopyWebpackPlugin([ + { + from: + '../../../node_modules/cornerstone-wado-image-loader/dist/dynamic-import', + to: DIST_DIR, + }, + ]), +``` + +Note 1: You need to give the correct path in the `CopyWebpackPlugin`, the above +path is relative to the `node_modules` folder in the OHIF Viewer. + +Note 2: For other http servers like IIS, you need to configure it to serve WASM +files with the correct MIME type. + +## Troubleshooting + +Having problems viewing your images with cornerstonWADOImageLoader? Check out +the +[troubleshooting guide](https://github.com/cornerstonejs/cornerstoneWADOImageLoader/wiki/troubleshooting). + +## Backlog + +- Support for images with pixel padding +- Support for high bit (e.g. mask out burned in overlays) +- Free up DICOM P10 instance after decoding to reduce memory consumption +- Add support for compressed images to WADO-RS loader +- Look at using EMSCRIPTEN based build of IJG for JPEG +- Consolidate all EMSCRIPTEN codecs into one build to cut down on memory use and + startup times +- Add support for bulk data items to WADO-RS Loader +- Add events to webWorkerManager so its activity can be monitored +- Add support for issuing progress events from web worker tasks + +# FAQ _Why is this a separate library from cornerstone?_ -Mainly to avoid adding a dependency to cornerstone for the DICOM parsing library. While cornerstone is -intended to be used to display medical images that are stored in DICOM, cornerstone aims to simplify -the use of medical imaging and therefore tries to hide some of the complexity that exists within -DICOM. It is also desirable to support display of non DICOM images so a DICOM independent image model -makes sense. +Mainly to avoid adding a dependency to cornerstone for the DICOM parsing +library. While cornerstone is intended to be used to display medical images that +are stored in DICOM, cornerstone aims to simplify the use of medical imaging and +therefore tries to hide some of the complexity that exists within DICOM. It is +also desirable to support display of non DICOM images so a DICOM independent +image model makes sense. _How do I build this library myself?_ @@ -110,8 +191,8 @@ _How do I create imageIds that work with this image loader?_ See the documentation [here](docs/ImageIds.md) -Copyright -============ +# Copyright + Copyright 2016 Chris Hafey [chafey@gmail.com](mailto:chafey@gmail.com) + +``` + +```