Step-by-Step Tutorial: Integrating Weasis with Orthanc PACS Integrating a web-based DICOM viewer with a picture archiving and communication system (PACS) is a common requirement for modern medical imaging workflows. Orthanc is an open-source, lightweight PACS, while Weasis is a powerful, cross-platform DICOM viewer. Combining them creates a highly efficient, web-accessible imaging workstation.
This tutorial provides a complete guide to connecting Weasis with Orthanc using standard web protocols. Prerequisites
Before beginning the integration, ensure you have the following components installed and running:
Orthanc PACS Server: Installed and accessible via its HTTP REST API (default port 8042).
Orthanc Web Viewer Plugin: Enabled within your Orthanc installation.
Weasis Viewer: The application packages or web-distribution files.
Java Runtime Environment (JRE): Required on client machines to launch Weasis via Java Web Start (JNLP) or native wrappers.
Administrative Access: Rights to modify the orthanc.json configuration file. Step 1: Configure Orthanc for Web Viewer Integration
Orthanc utilizes plugins to extend its core functionality. To allow Weasis to query and retrieve images, you must configure Orthanc to recognize web viewer requests. Locate your orthanc.json configuration file.
Open the file in a text editor and ensure the Web Viewer plugin is enabled:
{ “Plugins” : [ “/usr/share/orthanc/plugins” ], “WebViewer” : { “Enable” : true } } Use code with caution.
Enable DICOM web protocols (DICOMweb) if you plan to use WADO-RS or QIDO-RS, which Weasis supports for high-performance streaming:
{ “DicomWeb” : { “Enable” : true, “Root” : “/dicom-web/” } } Use code with caution.
Restart the Orthanc service to apply the configuration changes. Step 2: Set Up the Weasis Connector
Weasis launches from web browsers using a protocol handler or a configuration link (URL syntax). To connect it to Orthanc, you need a connector script or plugin that translates Orthanc study IDs into a Weasis-readable XML manifest.
The most robust method utilizes the official Weasis Orthanc plugin or a custom reverse proxy setup. Option A: Using the Weasis Orthanc Plugin
Download the compiled Weasis plugin compatible with your Orthanc version.
Place the plugin library (.so for Linux or .dll for Windows) into the Orthanc plugins directory.
Update your orthanc.json to include the Weasis configurations:
{ “Weasis” : { “Enable” : true, “Url” : “http://localhost:8080/weasis-pacs-connector” } } Use code with caution. Option B: Using WADO-URI Launch Links
If you prefer a lightweight approach without dedicated plugins, you can invoke Weasis via its native URL scheme by passing Orthanc’s WADO endpoints directly. Step 3: Configure Client-Side Launching
Weasis relies on the weasis:// protocol scheme to launch from a standard web browser like Chrome, Edge, or Firefox. Construct the launch URL using the following format:
weasis://$dicom:wado –url “http:// Use code with caution.
Embed this link into your custom clinical portal, electronic health record (EHR), or the Orthanc Explorer user interface.
When a user clicks the link, the browser prompts them to open the Weasis launcher, which downloads and displays the specified study. Step 4: Verify the Integration
To ensure the integration is functioning correctly, perform a validation check:
Open the Orthanc Explorer web interface (http://localhost:8042/app/explorer.html). Select a patient and navigate to a specific imaging study.
Click your newly integrated Weasis launch button or paste your constructed weasis:// URL into the browser search bar.
Confirm that the Weasis splash screen appears, downloads the DICOM series, and displays the images with full diagnostic tools. Troubleshooting Common Issues Viewer Fails to Launch
Cause: The client machine lacks the Weasis native bundle or protocol registration.
Solution: Download and run the Weasis desktop installer on the client machine to register the weasis:// URL protocol. Images Do Not Load (Blank Screen)
Cause: Cross-Origin Resource Sharing (CORS) restrictions block the request.
Solution: Configure Orthanc or your frontend reverse proxy (such as Nginx or Apache) to allow CORS headers from the originating web domain. Slow Loading Times
Cause: Large datasets transferring over standard HTTP instead of optimized DICOMweb streams.
Solution: Verify that the Orthanc DICOMweb plugin is active and ensure Weasis is explicitly configured to use wado-rs instead of legacy wado-uri. If you want, I can:
Provide the Nginx reverse proxy configuration for secure access Give you a JavaScript snippet to automate link generation
Explain how to configure user authentication / tokens for security
Leave a Reply