Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feat/optional codecs, HTJ2K support #391

Open
wants to merge 11 commits into
base: master
Choose a base branch
from
16 changes: 9 additions & 7 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,15 @@
// ===

"editor.formatOnSave": true,
"eslint.autoFixOnSave": true,
"eslint.run": "onSave",
"eslint.validate": [
{ "language": "javascript", "autoFix": true },
{ "language": "javascriptreact", "autoFix": true }
],
"prettier.disableLanguages": [],
"eslint.validate": ["javascript", "javascriptreact"],
// "eslint.validate": [
// { "language": "javascript", "autoFix": true },
// { "language": "javascriptreact", "autoFix": true }
// ],
"prettier.endOfLine": "lf",
"workbench.colorCustomizations": {}
"workbench.colorCustomizations": {},
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
}
}
139 changes: 73 additions & 66 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,102 +1,109 @@
[![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
=============================
# 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)
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
---------------
## Troubleshooting

Having problems viewing your images with cornerstonWADOImageLoader? Check out the
Having problems viewing your images with cornerstonWADOImageLoader? Check out
the
[troubleshooting guide](https://github.com/cornerstonejs/cornerstoneWADOImageLoader/wiki/troubleshooting).

Live Examples
---------------
## 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.

## 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

_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?_

Expand All @@ -110,8 +117,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 [[email protected]](mailto:[email protected])

<!--
Expand Down
22 changes: 22 additions & 0 deletions codecs/openjphjs-wasm.js

Large diffs are not rendered by default.

25 changes: 24 additions & 1 deletion config/webpack/webpack-base.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ module.exports = {
entry: {
cornerstoneWADOImageLoader: './imageLoader/index.js',
cornerstoneWADOImageLoaderWebWorker: './webWorker/index.worker.js',
decodeJpegBaseline: './shared/decoders/decodeJPEGBaseline.js',
decodeJpeg2000: './shared/decoders/decodeJPEG2000.js',
decodeJpegLS: './shared/decoders/decodeJPEGLS.js',
decodeJpegLossless: './shared/decoders/decodeJPEGLossless.js',
decodeHtj2k: './shared/decoders/decodeHTJ2K.js',
allDecoders: './shared/decoders/allExternalDecoders.js',
},
target: 'web',
output: {
Expand All @@ -30,9 +36,26 @@ module.exports = {
root: 'dicomParser',
},
},
devServer: {
writeToDisk: false,
},
module: {
noParse: [/(codecs)/],
rules: [
// {
// test: /\.wasm$/,
// type:
// 'javascript/auto' /** this disables webpacks default handling of wasm */,
// use: [
// {
// loader: 'file-loader',
// options: {
// // name: 'wasm/[name].[ext]',
// // publicPath: '/dist/',
// },
// },
// ],
// },
{
enforce: 'pre',
test: /\.js$/,
Expand All @@ -46,7 +69,7 @@ module.exports = {
test: /\.worker\.js$/,
use: {
loader: 'worker-loader',
options: { inline: true, fallback: false },
options: { inline: 'no-fallback' },
},
},
/*{
Expand Down
98 changes: 60 additions & 38 deletions docs/Codecs.md
Original file line number Diff line number Diff line change
@@ -1,56 +1,78 @@
Codecs
======
# Codecs

The cornnerstoneWADOImageLoader uses the following third party libraries to decode the
various ways DICOM images are compressed:
The cornerstoneWADOImageLoader uses the following third party libraries to
decode the various ways DICOM images are compressed:

1) [OpenJPEG.js](https://github.com/cornerstonejs/openjpeg) for JPEG2000 images. Based on the [OpenJPEG](http://www.openjpeg.org/) library
1. [OpenJPEG.js](https://github.com/cornerstonejs/openjpeg) for JPEG2000 images.
Based on the [OpenJPEG](http://www.openjpeg.org/) library

2) [OHIF/image-JPEG2000](https://github.com/OHIF/image-JPEG2000) For JPEG2000 Images. Based on the [PDF.js](https://mozilla.github.io/pdf.js/) library
2. [OHIF/image-JPEG2000](https://github.com/OHIF/image-JPEG2000) For JPEG2000
Images. Based on the [PDF.js](https://mozilla.github.io/pdf.js/) library

3) [CharLS.js]() for JPEG-LS images. Based on the [CharLS]() library
3. [CharLS.js]() for JPEG-LS images. Based on the [CharLS]() library

4) [JPEGLossless Decoder JS](https://github.com/rii-mango/JPEGLosslessDecoderJS) for JPEG Lossless images.
4. [JPEGLossless Decoder JS](https://github.com/rii-mango/JPEGLosslessDecoderJS)
for JPEG Lossless images.

5) [JPEG Lossy]() for JPEG Lossy images. Based on notmasteryet with changes contributed by [gSquared](https://github.com/g-squared)
5. [JPEG Lossy]() for JPEG Lossy images. Based on notmasteryet with changes
contributed by [gSquared](https://github.com/g-squared)

6) [pako.js]() for deflate based images.
6. [pako.js]() for deflate based images.

JPEG2000
--------
The OpenJPEG based codec is the default codec for JPEG2000 images. This codec is the default because the OpenJPEG
library is in wide use, activily supported and believed to be able to decode most of if not all JPEG2000 images
found in medical imaging. The PDF.js library is not recommended as it has
[known issues](https://github.com/OHIF/image-JPEG2000/issues) that nobody is fixing and
not actively supported. The performance of the PDF.js library may be better on some browsers or with some types of
images, here are some benchmarks:
7. [OpenJPHjs](https://github.com/chafey/openjphjs) for HTJ2K images.

Images from ftp://medical.nema.org/MEDICAL/Dicom/DataSets/WG04/compsamples_j2k.tar
## Loading Codecs

iMac Retina 5k Late 2014 4GHz Intel Core i7 Chrome 50.0.2661.102 (64 bit)
To load codecs, use the `decodeConfig.decoderPaths` option in the configuration.
To include all codecs (larger bundle size), use `dist/allDecoders.min.js`.

Available codecs:

- Little endian (enabled by default)
- Big endian (enabled by default)
- RLE (enabled by default)
- HTJ2K (`decodeHtj2k.min.js`)
- JPEG2000 (`decodeJpeg2000.min.js`)
- JPEG baseline (`decodeJpegBaseline.min.js`)
- JPEG Lossless (`decodeJpegLossless.min.js`)
- JPEG LS (`decodeJPEGLS.min.js`)

## JPEG2000

| Image | OpenJPEG | PDF.js |
| --------------| ------------- | -------- |
| NM1_J2KR | 233 ms | 103 ms |
| CT1_J2KR | 424 ms | 147 ms |
| RG1_J2KR | 6058 ms | 2311 ms |
| MG1_J2KR | 19312 ms | 7380 ms |
The OpenJPEG based codec is the default codec for JPEG2000 images. This codec is
the default because the OpenJPEG library is in wide use, activily supported and
believed to be able to decode most of if not all JPEG2000 images found in
medical imaging. The PDF.js library is not recommended as it has
[known issues](https://github.com/OHIF/image-JPEG2000/issues) that nobody is
fixing and not actively supported. The performance of the PDF.js library may be
better on some browsers or with some types of images, here are some benchmarks:

Images from
ftp://medical.nema.org/MEDICAL/Dicom/DataSets/WG04/compsamples_j2k.tar

iMac Retina 5k Late 2014 4GHz Intel Core i7 Chrome 50.0.2661.102 (64 bit)

| Image | OpenJPEG | PDF.js |
| -------- | -------- | ------- |
| NM1_J2KR | 233 ms | 103 ms |
| CT1_J2KR | 424 ms | 147 ms |
| RG1_J2KR | 6058 ms | 2311 ms |
| MG1_J2KR | 19312 ms | 7380 ms |

iMac Retina 5k Late 2014 4GHz Intel Core i7 FireFox 46.0.1

| Image | OpenJPEG | PDF.js |
| --------------| ------------- | -------- |
| NM1_J2KR | 240 ms | 102 ms |
| CT1_J2KR | 185 ms | 91 ms |
| RG1_J2KR | 3445 ms | 1594 ms |
| MG1_J2KR | 10295 ms | 14207 ms |
| Image | OpenJPEG | PDF.js |
| -------- | -------- | -------- |
| NM1_J2KR | 240 ms | 102 ms |
| CT1_J2KR | 185 ms | 91 ms |
| RG1_J2KR | 3445 ms | 1594 ms |
| MG1_J2KR | 10295 ms | 14207 ms |

iMac Retina 5k Late 2014 4GHz Intel Core i7 Safari 9.1.1

| Image | OpenJPEG | PDF.js |
| --------------| ------------- | -------- |
| NM1_J2KR | 64 ms | 56 ms |
| CT1_J2KR | 115 ms | 94 ms |
| RG1_J2KR | 2367 ms | 1567 ms |
| MG1_J2KR | 6496 ms | 18547 ms |
| Image | OpenJPEG | PDF.js |
| -------- | -------- | -------- |
| NM1_J2KR | 64 ms | 56 ms |
| CT1_J2KR | 115 ms | 94 ms |
| RG1_J2KR | 2367 ms | 1567 ms |
| MG1_J2KR | 6496 ms | 18547 ms |
Loading