dcmjs

dcmjs

JavaScript implementation of DICOM manipulation. This code is an outgrowth of several efforts to implement web applications for medical imaging. the package should also work fine on node.

CI

Note: this code is a work-in-progress

This is a community effort so please help improve support for a wide range of DICOM data and use cases.

See live examples here

Goals

Overall the code should:

Architectural goals include:

Parts of DICOM that dcmjs *will* focus on:

Parts of DICOM that dcmjs *will not* focus on:

Usage

In Browser

<script type="text/javascript" src="https://unpkg.com/dcmjs"></script>

In Node

// To install latest _stable_ release
npm install --save dcmjs

// To install latest code merged to master
npm install --save dcmjs@dev

For Developers

git clone https://github.com/dcmjs-org/dcmjs
cd dcmjs
npm install
npm run build
npm test

For Maintainers and Contributors

Publish new version automatically from commit:

Use the following “Commit Message Format” when drafting commit messages. If you’re merging a 3rd party’s PR, you have the ability to override the supplied commit messages by doing a “Squash & Merge”:

Note: Be wary of BREAKING_CHANGE in commit message descriptions, as this can force a major version bump.

Be sure to use lower case for the first letter of your semantic commit message, so use fix not Fix or feat not Feat, have a space after the : and make the PR github review title follow the SAME rules. It is the PR review title that determins the final commit message and will be used for semantic detection.

Note: a new package version will be published only if the commit comes from a PR.

Optional Tooling

It is advised to use the git-cz, i.e.:

npm install -g git-cz

git-cz --non-interactive --type=fix --subject="commit message"

More info at git-cz.

DICOM Dictionary

The dcmjs library includes DICOM data dictionaries that map DICOM tags to their metadata (VR, VM, etc.). To optimize load performance, the library uses a pre-compiled “fast dictionary” format.

Dictionary Files

Updating the Dictionary

When DICOM standards are updated or new tags need to be added:

  1. Generate the dictionary from DICOM standards (downloads latest PS3.6 and PS3.7 XML from dicom.nema.org): 
    npm run generate-dictionary

    This creates/updates generate/dictionary.js with the latest tag definitions.

  2. Pack the dictionary into optimized format: 
    npm run pack-dictionary

    This generates the optimized src/dictionary.fast.js used at runtime.

Why the Fast Dictionary?

The fast dictionary was introduced to significantly improve library load performance. The original dictionary format required complex runtime processing during module initialization, which added substantial overhead, especially in applications that frequently import dcmjs.

Performance Benchmark Results (Bun):

Old dictionary (generate/dictionary.mjs): 181.16 ms
New dictionary (src/dictionary.fast.js):    19.04 ms
Performance improvement: 9.52x faster

ESM main (dcmjs.es.js):         112.01 ms
ESM private (loadPrivateTags):    0.01 ms
ESM total:                      112.01 ms

UMD (dcmjs.js):                  72.11 ms

The fast dictionary reduces initial load time by over 9x, making it especially beneficial for:

Community Participation

Use this repository’s issues page to report any bugs. Please follow SSCCE guidelines when submitting issues.

Use github pull requests to make contributions.

Unit Tests

Tests are written using the Jest testing framework and live in the test/ folder. Test file names must end with .test.js.

Pull requests should either update existing tests or add new tests in order to ensure good test coverage of the changes being made.

To run all tests use npm run test. To only run specific tests use Jest’s .only feature. If you’re using VS Code, an extension such as firsttris.vscode-jest-runner can be used to step through specific tests in the debugger.

Read all about unit testing best practices here.

Status

Currently dcmjs is an early-stage development experiment, but already has valuable functionality.

Implemented

In development

TODO

History

Support

The developers gratefully acknowledge their research support:

Logging

This library uses loglevel for logging. By default, the log level is set to “warn”. You can change the log level by setting the LOG_LEVEL environment variable or by using the setLevel method in your code.

This site is open source. Improve this page.