viewports-core

ViewPorts-Core for dicom viewer

Usage no npm install needed!

<script type="module">
  import viewportsCore from 'https://cdn.skypack.dev/viewports-core';
</script>

README

Installation and usage

The easiest way to use viewportsCore is to install it from npm.

npm install viewports-core

Functionality of framework you can achieve using viewportsCore object.

To create simple viewer first of all you should create html file like this:

<!--index.html file-->
<style>
    #viewer {
        width: 100%;
        height: 100%;
    }
</style>
...
<body>
    <div id="viewer"></div>
</body>

Then use it in your app:

viewportsCore.create(`viewer`, {});

Features

Here you will find description about viewportsCore features.

Layout

To create viewports layout use this function:

viewportsCore.create(containerId, properties);

Parameters description:

  • containerId - ID of HTML DOM element where will be store viewports.
  • properties - object which setup parameters of viewports (not required). Possible options:
    • position - this object describes absolute position of viewports layout. Default value: {top: 0, right: 0, bottom: 0, left: 0}.
    • layout - this object defines layout of viewports. Default value: {columns: 1, rows: 1}.
    • enabledScrollBetweenSeries - this parameter allows scrolling between series. Default value: false.
    • autoOpenImageType - parameter defines which way to use for the study auto open. Possible values: none, first, always. Default values: none.
    • features - this parameter enables features which is described in the object as parameter. This is for presentation states, key object, patient history.

To delete viewport by container id:

viewportsCore.deleteViewportByContainerId(containerId);

Parameters description:

  • containerId - Id of DOM element were viewport is stored (For example: container-1-1).

To delete all viewports:

viewportsCore.deleteAllViewports();

Data loading

Receive and store study data you can use this function (Study will load in active viewport):

viewportsCore.loadStudyWithHIS(studyUid, seriesUid, instanceUid);

Parameters description:

  • studyUid - study unique identification (string).
  • seriesUid - series unique identification (string). Optional parameter, if not provided - first series from study is loaded.
  • instanceUid - instance unique identification (string). Optional parameter, if not provided - first instance from series is loaded.

Load few studies in one call:

viewportsCore.loadStudiesWithHIS(studiesToLoad);

Example:

const studiesToLoad = [
    {
        studyUid: '1.2.840.113619.2.55.3.4271045733.996.1449464144.595',
        seriesUid: '1.2.840.113619.2.55.3.4271045733.996.1449464144.156',
        instanceUid: '1.2.840.113619.2.55.3.4271045733.996.1449464144.111', 
        containerId: 'container-1-1', 
        callback: (viewport) => {viewport.applyInvert(true)}
    },
    {
        studyUid: '1.2.840.113619.2.55.3.4271045733.996.1449464144.595', 
        containerId: 'container-1-2', 
        callback: (viewport, study) => {console.log(study)}
    },
];

Parameters description:

  • studyUid - study unique identification (string).
  • seriesUid - series unique identification (string). Optional parameter, if not provided - first series from study is loaded.
  • instanceUid - instance unique identification (string). Optional parameter, if not provided - first instance from series is loaded.
  • containerId - ID of HTML DOM element where will be store viewports.
  • callback- loaded study callback (function). Callback parameters are:
    • viewport - current viewport data where study is loaded.
    • study - loaded study data object.

Use this function to load instance in specific container:

viewportsCore.layout.loadInstanceToContainer(instanceUid, viewportColumn, viewportRow);

Parameters description:

  • instanceUid - instance unique identification (string).
  • viewportColumn - number of column.
  • viewportRow - number of row.

Actions with layout

Supported layout types: 1x1, 1x2, 1x3, 2x1, 2x2, 2x3, 3x1, 3x2, 3x3 To change layout of viewports uses this:

viewportsCore.setLayout(columns, rows);

To get active viewport container:

viewportsCore.layout.getActiveContainerId();

To remove selected active viewport container:

viewportsCore.layout.removeActiveViewportContainer();

Actions with measurements

Measurements id: none, ruler, angle, polyline, oval, volume, VTI, cobb angle, roi;

viewportsCore.getActiveViewport().deleteMeasurements();
viewportsCore.setActiveMeasurementId(`ruler`);
viewportsCore.getActiveMeasurementId();

viewportsCore.enableAngleBetweenIntersectingRulers();
viewportsCore.disableAngleBetweenIntersectingRulers();
viewportsCore.isEnableAngleBetweenIntersectingRulers();

viewportsCore.enableIntensity();
viewportsCore.disableIntensity();
viewportsCore.isEnableIntensity();

Binding mouse button

To bind function on mouse button you need to give number of 1|2|3 and function name of VIEWPORT_FUNCTIONS constant.

VIEWPORT_FUNCTIONS = {
    NONE: 0,
    WL: 1,
    ZOOM: 2,
    PAN: 3,
    SCROLL: 4,
    MEASURE: 5,
    ROTATE: 6,
    CROSSHAIR: 8,
};

viewportsCore.setMouseButtonFunction(1|2|3, VIEWPORT_FUNCTIONS.WL);

Synchronization

To enable synchronization you need to use this:

viewportsCore.enableSync(yourCallback);

Disable:

viewportsCore.disableSync(yourCallback);

For example:

viewportsCore.enableSync((functionName, parameters) => console.log(functionName, parameters));
  • functionName have these event names: image-position-changed, zoom-changed, container-size-changed.
  • parameters have function arguments and containerId. Example of parameters:
    • image-position-changed: {"imagePosition": {"x": 0.03176011108489626, "y": 0.09775284633952291}, "containerId": "container-1-1"};
    • zoom-changed: {"scale": 1.2529411185263977, "point": { "x": 253.15625", "y": 389}, "containerId": "container-1-1"};
    • container-size-changed: {"width": 531, "height": 883, "scale": 1.037109375, "containerId": "container-1-1"}.

On these events you can manipulate sync functionality.

This function can add desired containers to the list:

viewportsCore.addToSync(containersId);
  • containersId - array of strings. Example: (['container-1-1', 'container-1-2']).

Function to remove containers from the list:

viewportsCore.removeFromSync(containersId);
  • containersId - array of strings. Example: (['container-1-1', 'container-1-2']).

Get all containers from the list:

viewportsCore.getLockedViewportContainers();

When sync is enabled you can use zoom function on locked containers:

viewportsCore.applyZoomForLockedViews(containerId, scale, point);
  • containerId - container id from which zoom operation was performed (to ignore provided container).
  • scale - scale number.
  • point - point object with x and y coordinates. For example: {x: 242, y: 236}.

When sync is enabled you can use pan function on locked containers:

viewportsCore.applyPanForLockedViews(containerId, positionX, positionY);
  • containerId - container id from which pan operation was performed (to ignore provided container).
  • positionX - position x coordinates.
  • positionY - position y coordinates.

Landmark

To enable event which is triggered on landmark creation, use this:

viewportsCore.landmarksController.enable(yourCallback);

Disable:

viewportsCore.landmarksController.disable(yourCallback);

For example:

viewportsCore.landmarksController.enable((landmarkData) => console.log(landmarkData));
  • landmarkData - object contains information about added landmark. Landmark information:
    • studyUid: study unique identification (string);
    • frameOfReferenceUid: frame of reference unique identification (string);
    • points: 3 landmark points array with x, y, z coordinates. Array example: [[-7.2, 1.8, -2.5], [-6.5, -1.5, -282.5], [5.5, 8.3, -29.5]].

To enable landmark tool and start drawing landmark, use this:

viewportsCore.landmarksController.createLandmark();

Function to create landmark in viewports by stored landmark data:

viewportsCore.landmarksController.addLandmark(landmarkData);
  • landmarkData - object with landmark data information:
    • studyUid: study unique identification (string);
    • frameOfReferenceUid: frame of reference unique identification (string);
    • points: 3 landmark points array with x, y, z coordinates. Array example: [[-7.2, 1.8, -2.5], [-6.5, -1.5, -282.5], [5.5, 8.3, -29.5]].

Function to remove created or added landmark:

viewportsCore.landmarksController.removeLandmark(referenceUid);
  • referenceUid - frame of reference uid.

Function to get landmark data by frame of reference uid:

viewportsCore.landmarksController.getLandmarkData(referenceUid);
  • referenceUid - frame of reference uid.

MPR actions

Orientations: CORONAL, AXIAL, SAGITTAL.

viewportsCore.changeActiveViewportOrientation(`CORONAL`);

Fusion

Fusion with Hot Iron palette.

viewportsCore.getActiveViewport().enableFusion(seriesId);

Window leveling actions

viewportsCore.getActiveViewport().applyWL(w,l);
viewportsCore.getActiveViewport().applyDefaultWL();
viewportsCore.getActiveViewport().applyAutoWL();
viewportsCore.getActiveViewport().applyInvert(true|false);
viewportsCore.getActiveViewport().isInverted();

Transformations of view

viewportsCore.getActiveViewport().applyRightRotation();
viewportsCore.getActiveViewport().applyLeftRotation();
viewportsCore.getActiveViewport().applyHorizontalFlip();
viewportsCore.getActiveViewport().applyVerticalFlip();
viewportsCore.getActiveViewport().applyTransformationCleanup();

Zoom operations

viewportsCore.getActiveViewport().applyFitToScreen();
viewportsCore.getActiveViewport().applyOriginalResolution();
viewportsCore.applyZoom(containerId, scale, point);
  • containerId - container id string.
  • scale - scale number.
  • point - point object with x and y coordinates. For example: {x: 242, y: 236}.

Pan operations

viewportsCore.applyPan(containerId, positionX, positionY);
  • containerId - container id string.
  • positionX - position x coordinates.
  • positionY - position y coordinates.

Reference lines

viewportsCore.enableReferenceLines();
viewportsCore.disableReferenceLines();
viewportsCore.isEnableReferenceLines();

viewportsCore.getActiveViewport().resetRender();
viewportsCore.resetAllViewportsRenders();

Study cache

viewportsCore.cacheStudy(viewportsCore.getActiveViewportStudy().uid, storageId);

Main data objects

Study object

To get study data use this command:

viewportsCore.getStudy(studyUid, storageId);

Series object

To get series data use this command:

viewportsCore.getSeries(seriesUid);

Instance object

To get instance data use this command:

viewportsCore.getInstance(instanceUid);

Events

To register event use:

viewportsCore.registerEvent(`event-constant`, callback);

To remove:

viewportsCore.removeEvent(`event-constant`, callback);

Selected viewport container event

Event constant: selected-viewport-container.

To use the event:

viewportsCore.registerEvent(`selected-viewport-container`, (containerId) => console.log(containerId));

Callback parameter:

  • containerId - selected viewport container id.

Rotate instance event

Event constant: image-rotation-changed.

To use the event:

viewportsCore.registerEvent(`image-rotation-changed`, ({angle, containerId}) => console.log(angle, containerId));

Callback parameter:

  • angle - instance rotation angle.
  • containerId - selected viewport container id.

Pan instance event

Event constant: image-position-changed.

To use the event:

viewportsCore.registerEvent(`image-position-changed`, ({imagePosition, containerId}) => console.log(imagePosition, containerId));

Callback parameter:

  • imagePosition - instance position coordinates.
  • containerId - selected viewport container id.

Zoom instance event

Event constant: zoom-changed.

To use the event:

viewportsCore.registerEvent(`zoom-changed`, ({scale, point, containerId}) => console.log(scale, point, containerId));

Callback parameter:

  • scale - scale size.
  • point - the point coordinates from which to zoom in or out.
  • containerId - selected viewport container id.

Delete viewports event

Event gives callback when the viewport is deleted and also gives callback when the viewport disappears on layout change.

Event constant: container-cleaned.

To use the event:

viewportsCore.registerEvent(`container-cleaned`, (container) => console.log(container));

Callback parameter:

  • container - object with container information:
    • containerId - container id from which viewport will be cleaned;
    • viewportId - cleaned viewport id.