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 by building your own connector. The launch of the application is based on the weasis protocol available since version 3.5. However, it is still possible to use weasis 3.5 with Java Webstart (but only with Java 8 to 10), see the old documentation.

Using weasis-pacs-connector 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:// (as weasis:// is not allowed by wiki, blog…)
  • Manages to build the manifest simultaneously with the start of Weasis
  • The URL returns a manifest ID which can be requested only once (and must be consumed within 5 min)

However, it is possible to build your own connector for particular integrations or when a DICOMWeb service is available.

Requires Weasis 3.5 (or superior) installed on the system with a 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(asynchronoustaskstartinstep2andreturndirectlyanURLwithanIDorder)2.manifestbuilderURL3.URLredirectionintoweasisprotocol(weasis://parameters)DownloadManager(ReadXMLmanifest)1.Request(URLwithUIDs,includeInvokeImageDisplayIHEProfile)6.GetDICOMfilesbyWADO5.GetthemanifestWeasisweasis-pacs-connectorClient(oranywebordesktopapplications)dcm4cheewebui4.Executeweasisprotocol

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 creating the manifest.

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

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 to immediately display the descriptions before downloading the images.

From Weasis 2.5 it is possible to have multiple archives (allows to have 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/samples/Lumbar/mf.xml

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)

Use $dicom:rs to load DICOM files. Here are some configurations of open source systems:

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

Configuration notes:

  • See configuration for versions before 5.22.2.
  • 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”).

Finally, refresh the page for having the viewer button.

Orthanc WEB Server

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

$dicom:rs --url "https://demo.orthanc-server.com/dicom-web" -r "patientID=5Yp0E" --accept-ext=";"

Launch

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

  • transfer-syntax=* doesn’t work (always get uncompressed image). Once this issue will be fixes --accept-ext=";" can be removed.
  • 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.

<your-token> must be replaced by the hostname of your dcm4che installation.

DICOMcloud (for Azure cloud)

https://github.com/DICOMcloud/DICOMcloud

$dicom:rs --url "https://dicomcloud.azurewebsites.net/api" -r "studyUID=1.2.840.113619.2.25.1.1762157631.873231884.123" -r "studyUID=1.3.6.1.4.1.5962.99.1.2280943358.716200484.1363785608958.3.0"

Launch

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

  • Thumbnail service is not implemented.