Integration

How to launch Weasis from any environments

Here we present how to launch Weasis with associated images from any context either using weasis-pacs-connector or ViewerHub as its successor, or by building your own connector. The launch of the application is based on the weasis protocol available since Version3.5.3.

Using weasis-pacs-connector or ViewerHub allows a high degree of integration and facilitates connection to a PACS. Here are some of the advantages:

  • Automatically build a manifest according to a configuration with a PACS
  • The initial URL starts with HTTP and is then redirected to weasis:// (useful when custom URI scheme is not allowed by wiki, blog platforms, etc.)
  • Efficiently manages to build the manifest simultaneously with the start of Weasis, optimizing loading time
  • Easily handles secure manifest requests and manages tokens for the DICOMWeb services

However, it is also possible:

These integrations provide flexibility to meet the specific needs of healthcare environments, ensuring seamless integration.

Note

Requires Weasis installed on the system with the native installer.

Use weasis-pacs-connector

For connecting to dcm4chee web interface, follow the instructions in Installing Weasis in DCM4CHEE. Otherwise, refer to the documentation of weasis-pacs-connector.

Standard workflow when connecting Weasis to a PACS, RIS, EMR, EPR or any web interface:

PACSLauncherDICOMQueryWeasisConfig(Configurationoftheuserpreferencesandthelauncherparameters)XMLmanifestBuilder(asynchronoustask, startinstep2andreturndirectlyanURLwithanIDorder)2.manifestbuilderURL3.URLredirectionintoweasisprotocol(weasis://parameters)DownloadManager(ReadXMLmanifest)1.Request(URLwithUIDs,includeInvokeImageDisplayIHEProfile)6.GetDICOMfilesbyWADO5.GetthemanifestWeasisweasis-pacs-connectorClient(oranywebordesktopapplications)dcm4cheewebui4.Executeweasisprotocol

Note

The schema above shows that the queries to the PACS are made at the same time as the viewer starts. This makes it possible to optimize the launch by simultaneously launching weasis and building the manifest.

Tip

weasis-pacs-connector services allow either to build a manifest from a PACS via DICOM C-Find or to upload the manifest by http POST.

Build your own connector

This documentation describes how to create your own connector without weasis-pacs-connector and with different DICOM archive types. The weasis protocol allows you to build URIs to launch Weasis according to different configurations and allows to load DICOM files locally or remotely.

Here are examples with XML manifests or with DICOMWeb RESTful services.

Build an XML manifest

Use $dicom:get to load a XML manifest returned by your service. 

$dicom:get -w "https://myservice/manifest?studyUID=2.16.756.5.5.100.397184556.14391.1373576413.1508"

Build an XML file containing the UIDs of the images which will be retrieved from Weasis. There is XLS to validate the content of xml. This output file can be either compressed in gzip or uncompressed. Here is an example: 

<?xml version="1.0" encoding="UTF-8" ?>
<manifest xmlns="http://www.weasis.org/xsd/2.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <arcQuery additionnalParameters="" arcId="1001" baseUrl="http://archive-weasis.rhcloud.com/archive/wado" requireOnlySOPInstanceUID="false">
        <Patient PatientID="H13885_9M" PatientName="TEST NON SQUARE PIXELS" PatientSex="F">
            <Study AccessionNumber="" ReferringPhysicianName="" StudyDate="20130711" StudyDescription="TEST NON SQUARE PIXELS" StudyID="PKD" StudyInstanceUID="2.16.756.5.5.100.397184556.14391.1373576413.1508" StudyTime="170013">
                <Series Modality="US" SeriesDescription="NON SQUARE PIXELS: PIXEL ASPECT RATIO" SeriesInstanceUID="1.2.40.0.13.1.1.87878503032592846377547034671833520632" SeriesNumber="2">
                    <Instance InstanceNumber="107" SOPInstanceUID="1.2.40.0.13.1.1.126082073005720329436273995268222863740"/>
                </Series>
                <Series Modality="MR" SeriesDescription="NON SQUARE PIXELS: PIXEL SPACING" SeriesInstanceUID="2.16.756.5.5.100.397184556.7220.1373578035.1" SeriesNumber="40001">
                    <Instance InstanceNumber="1" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578035.1.0"/>
                    <Instance InstanceNumber="2" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578035.1.1"/>
                    <Instance InstanceNumber="3" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578035.1.2"/>
                    <Instance InstanceNumber="4" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578035.1.3"/>
                </Series>
                <Series Modality="MR" SeriesDescription="NON SQUARE PIXELS: PIXEL SPACING" SeriesInstanceUID="2.16.756.5.5.100.397184556.7220.1373578664.2" SeriesNumber="50001">
                    <Instance InstanceNumber="1" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578664.2.0"/>
                    <Instance InstanceNumber="2" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578664.2.1"/>
                    <Instance InstanceNumber="3" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578664.2.2"/>
                    <Instance InstanceNumber="4" SOPInstanceUID="2.16.756.5.5.100.397184556.7220.1373578664.2.3"/>
                </Series>
            </Study>
        </Patient>
    </arcQuery>
</manifest>
Note

Important Parameters (except mandatory parameters defined in xsd):

  • PatientBirthDate helps to identify a patient.
  • StudyDate, StudyTime, Modality, SeriesNumber and InstanceNumber help to sort data before downloading images.
  • SeriesDescription and StudyDescription allow immediately displaying the descriptions before downloading the images.

Tip

From Weasis 2.5 it is possible to have multiple archives (allows several arcQuery tags) and the presentations tag which contains the image annotations.

Build an XML manifest (no WADO server)

This example requires only a WEB server. Weasis will download DICOM files by URLs.

Use $dicom:get to load a XML manifest containing direct links Launch 

$dicom:get -w "https://nroduit.github.io/demo-archive/Lumbar/mf.xml"

Note

Required Parameters:

  • DirectDownloadFile defines the URL of the DICOM file to download (the final URL is the combination of wadoURL + DirectDownloadFile)
  • DirectDownloadThumbnail defines the URL of the JPEG file representing the series (the final URL is the combination of wadoURL + DirectDownloadThumbnail)
  • See in the previous note above.

Download directly with DICOMWeb RESTful services

This integration requires a PACS/VNA with DICOMweb services (QUERY/RETRIEVE) where the requests are managed directly by Weasis. Here are some of the advantages:

  • Straightforward integration
  • Do not require to install weasis-pacs-connector
  • Allow passing token directly in headers (not in the URL)

The following configurations allow images to be loaded by initiating the request from a WEB context. However, it is possible to access DICOMWeb services by initiating the request directly from the Weasis import.

Use $dicom:rs to load DICOM files. Here are some configuration examples of DICOMweb applications:

dcm4chee-arc-light

This configuration requires at least dcm4chee-arc-light 5.22.2 and Weasis 3.6.0. To activate Weasis in dcm4chee-arc-light user interface, you need to add the four following properties in the web portal from the left menu Configuration > Devices > dcm4chee-arc > Extensions > Edit extension > Child Objects > Web Applications > DCM4CHEE 

IID_PATIENT_URL=weasis://$dicom:rs --url "{{qidoBaseURL}}{{qidoBasePath}}" -r "patientID={{patientID}}" --query-ext "&includedefaults=false" -H "Authorization: Bearer {{access_token}}"
IID_STUDY_URL=weasis://$dicom:rs --url "{{qidoBaseURL}}{{qidoBasePath}}" -r "studyUID={{studyUID}}" --query-ext "&includedefaults=false" -H "Authorization: Bearer {{access_token}}"
IID_URL_TARGET=_self

The properties can also be passed directly to the docker-compose.env file: 

IID_PATIENT_URL=weasis://$dicom:rs --url "{{qidoBaseURL}}{{qidoBasePath}}" -r "patientID={{patientID}}" --query-ext "\&includedefaults=false" -H "Authorization: Bearer {{access_token}}"
IID_STUDY_URL=weasis://$dicom:rs --url "{{qidoBaseURL}}{{qidoBasePath}}" -r "studyUID={{studyUID}}" --query-ext "\&includedefaults=false" -H "Authorization: Bearer {{access_token}}"
IID_URL_TARGET=_self

Finally, refresh the page for having the viewer button.

Warning

Configuration notes:

  • See configuration for versions before 5.22.2.
  • From 5.24.0 {{qidoBaseURL}} must be replaced by your base URL (e.g. https://pacs2.test.com:8443)
  • The character ‘&’ must be escaped in the Docker environment variables.
  • The Authorization header is not required for unsecure service.
  • URL with HTTPS requires a real valid certificate; otherwise, the certificate must be imported into the Weasis Java keystore. For testing purposes in secure mode, you can use the HTTP URL if it is mapped in the OIDC client of keycloack (–url “http://:8080/dcm4chee-arc/aets/DCM4CHEE/rs”).
Note

Known issue: Weasis cannot open the images because of the token length which is cut by IE and Chrome only under Windows. It is working with Firefox on Windows.

Orthanc WEB Server

https://www.orthanc-server.com/static.php?page=dicomweb

$dicom:rs --url "https://demo.orthanc-server.com/dicom-web" -r "patientID=ozp00SjY2xG"
Launch

Currently, the DICOMWeb service of Orthanc doesn’t support:

  • Thumbnail service is not implemented.

Google Cloud Healthcare API

https://cloud.google.com/healthcare/docs/how-tos/dicomweb

$weasis:config pro="dicom.qido.query.multi.params true" $dicom:rs --url "https://healthcare.googleapis.com/v1beta1/projects/chc-nih-chest-xray/locations/us-central1/datasets/nih-chest-xray/dicomStores/nih-chest-xray/dicomWeb" -r "studyUID=1.3.6.1.4.1.11129.5.5.184301693334578016850836775758484230512396" -H "Authorization: Bearer <your-token>"

Currently, the DICOMWeb service for getting thumbnails doesn’t work in the Google API.

Note

<your-token> must be replaced by a valid token.

DICOMcloud (for Azure cloud)

https://github.com/DICOMcloud/DICOMcloud

$dicom:rs --url "https://dicomcloud.azurewebsites.net/api" -r "studyUID=1.3.6.1.4.1.14519.5.2.1.4429.7055.198257099234774234268879426857"
Launch
Note

The demo server is no longer accessible.

Currently, the DICOMWeb service of DICOMcloud doesn’t support:

  • Thumbnail service is not implemented.

Kheops

https://kheops.online

$dicom:rs --url "https://demo.kheops.online/api" -r "studyUID=1.3.6.1.4.1.14519.5.2.1.4429.7055.198257099234774234268879426857" -H "Authorization: Bearer <your-token>"
Note

<your-token> must be replaced by a valid token.

Amazon HealthImaging

https://aws.amazon.com/health/health-imaging/

Prefer to use dicomweb-proxy to manage the token and the URL of the DICOMWeb service. See Weasis configuration at the end of this page.