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 Version3.5.3.

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 (Loading time optimization)
• The URL returns a manifest ID which can be requested only once (and must be consumed within 5 min)

However, it is also possible

• To build your own connector for particular integrations
• To let Weasis querying DICOMWeb services directly.

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:

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>

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"

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.

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"

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.

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"

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

• Thumbnail service is not implemented.

Preferences

ViewerHub (is a separate project that will be available soon) is a tool designed for managing server-side Weasis preferences across all native client installations. The preferences are defined in each release package (bin-dist/weasis/conf within weasis-native.zip) and can be modified either through the ViewerHub web portal or via the Weasis protocol with the pro parameter.

Some server-side preferences are applied by Weasis only during the initial launch, as they can later be adjusted in the Weasis user interface. On the other hand, certain server-side preferences are utilized by Weasis during every launch and cannot be modified through the User Interface (client-side).

Changing Preferences in Weasis

Client-Side Preferences

Local preferences can be modified in the following ways:

• Through the Weasis User Interface: Navigate to File > Preferences.
• Using the Weasis Protocol: Use the weasis:config command with the pro parameter.

Server-Side Preferences

Server-side preferences can be updated using any of the following methods:

• Through the ViewerHub Web Portal: Manage preferences directly via the web portal for all users, for user group or for a specific hostname.
• By Extending the Configuration File: Create a new JSON file to extend the base.json configuration.

Priority order for loading a property

Here is the priority order to set a property:

1. Java System property providing from parameters of weasis:config or the launching URI)
2. Property defined in weasis/conf/xxx.json
3. The default value of the property (see table below)

Example to change language property (It will work only during the first launch of Weasis on a user session, otherwise delete ${user.home}/.weasis/preferences/).

1. If you are using weasis-pacs-connector, add the property locale.lang.code:

   http://localhost:8080/weasis-pacs-connector/weasis?patientID=9702672&pro="locale.lang.code%20fr_CH"

2. Add the property in weasis/conf/xxx.json:

   locale.lang.code=fr_CH

3. The default value is “en_US”

List of Preferences

The preferences listed below are extracted from the base.json file, which is located in the source code.

The properties are grouped into categories (note: not all categories are shown in the list below), and each property includes the following details:

1. Property Key: The name of the property, used as a key by the viewer.
2. Default Value: The property’s default value, provided after the arrow. If it is marked as Null, the property is not set by default.
3. First Badge: The JavaType of the property, indicating its type in Java (String, Integer, Boolean, etc.).
4. Second Badge: Represents the Type, defining how the viewer handles the property:
   • F: Processed only during the viewer’s initial launch as it can be adjusted in the client-side preferences.
   • A: Always processed by the viewer.
   • AP: Always processed by the viewer but only from base.json or other .json files.
5. Description: A brief explanation of the property, provided on the second line.

Dicom Category

• weasis.aet   Null string A
  Calling AETitle for DICOM send and Dicomizer publish. ? null means displaying the DICOM calling node combobox otherwise the combo is not displayed and the value is directly used
• weasis.dicom.root.uid   2.25 string A
  Set values for dicom root UID when creating DICOM objects (KO or PR). See company list at https://www.iana.org/assignments/enterprise-numbers
• weasis.download.immediately   true boolean F
  Start to download series immediately
• download.concurrent.series   3 int A
  Controls the number of series downloaded simultaneously
• download.concurrent.series.images   4 int A
  The number of concurrently downloaded images within a series

General Category

• weasis.theme   org.weasis.launcher.FlatWeasisTheme string F
  FaltLaf Look and feel, see https://www.formdev.com/flatlaf/themes/
• weasis.confirm.closing   false boolean F
  Show a message of confirmation when closing the application
• locale.lang.code   en string F
  Specifies the language code (see Java Locale: https://www.oracle.com/java/technologies/javase/jdk20-suported-locales.html). Default value is "en".
• locale.format.code   system string F
  Uses the operating system's locale (on the client-side) with "system". For other values refer to Java Locale: https://www.oracle.com/java/technologies/javase/jdk20-suported-locales.html

Launch Category

• felix.native.processor.alias.arm_le   armv7a string A
  Processor alias for 32-bit arm native libraries
• weasis.clean.previous.version   false boolean A
  If true, the bundle cache is cleared when the weasis version has changed from the previous launch
• weasis.main.ui   weasis-base-ui string A
  Application main user interface bundle. Mandatory with the default launcher.
• weasis.name   Weasis string AP
  Change the name of the application everywhere in UI
• weasis.profile   default string AP
  Application profile: when no profile name is provided, the value is "default". It allows having a custom preferences' directory on the client side (will not share preferences with other Weasis instances)
• weasis.user   Null string AP
  Defines a user name to store its own preferences. Null value will be the system user.
• weasis.pref.store.local.session   Null string AP
  Store user preferences when weasis.user is not specified (only with remote preferences service)
• flatlaf.uiScale   Null string F
  Specifies a custom scale factor used to scale the user interface. Allowed values: e.g. 1.5, 1.5x, 150% or 144dpi (96dpi is 100%)
• weasis.resources.url   ${dollar}{weasis.codebase.url}/resources.zip string A
  Application resources (logo, presets, LUTs, dicom annotations configuration...) "resources.zip" is downloaded again only when the last modified date has changed
• weasis.show.disclaimer   true boolean A
  Show a disclaimer at the first launch of Weasis (requires to be accepted to start the application)
• weasis.show.release   true boolean A
  Show a message when the release has changed
• weasis.update.release   true boolean A
  Show a message when a new release is available
• weasis.portable.dicom.directory   dicom,DICOM,IMAGES,images string A
  For loading automatically DICOMs in the portable Weasis distribution (CD/DVD). Comma-separated directories relative to the Weasis executable file.

Log Category

• felix.log.level   1 int A
  Set the logging levels for OSGI framework 0=None / 1(default)=Error / 2=Warning / 3=Information / 4=Debug
• org.apache.sling.commons.log.level   INFO string F
  Application logging level. This may be any of the defined logging levels TRACE, DEBUG, INFO, WARN, ERROR
• org.apache.sling.commons.log.file.activate   false boolean F
  Activation of rolling log files
• org.apache.sling.commons.log.file.number   20 int F
  The max number of rolling log files
• org.apache.sling.commons.log.file.size   10MB string F
  The max size of a rolling log file
• org.apache.sling.commons.log.pattern   %d{dd.MM.yyyy HH:mm:ss.SSS} *%-5level* [%thread] %logger{36}: %msg%ex{3}%n string F
  Log pattern: {0} The timestamp of type java.util.Date, {1} the log marker, {2} the name of the current thread, {3} the name of the logger, {4} the debug level and {5} the actual debug message.
• org.apache.sling.commons.log.stack.limit   3 int F
  Defines the maximum number of lines for stack trace (0 => NONE, -1 => ALL). Default value is 3
• audit.log   false boolean A
  Audit log for usage statistics in Weasis

Ui Category

• weasis.import.images   true boolean A
  Show the import image toolbar and menu
• weasis.import.dicom   true boolean A
  Show the DICOM import menu and dialog
• weasis.import.dicom.qr   true boolean A
  Show the DICOM Q/R page in the DICOM Export dialog
• weasis.export.dicom   true boolean A
  Show the DICOM export menu and dialog
• weasis.export.dicom.send   true boolean A
  Show the send page in the DICOM Export dialog
• weasis.toolbar.mouse.buttons   7170 int A
  Show all mouse buttons. Sum of LEFT=1024 + MIDDLE=2048 + RIGHT=4096 + SCROLL=2. Show all:7170 and show none:0.
• weasis.all.cinetoolbar.visible   false boolean A
  Show all the cine toolbars
• weasis.all.keyobjecttoolbar.visible   false boolean A
  Show all the key object toolbars
• weasis-dicom-viewer2d.all.rotationtoolbar.visible   false boolean A
  Show the rotation toolbars in DICOM 2D viewer
• weasis.contextmenu.lutShape   false boolean A
  Show LUT Shape in the contextual menu
• weasis.contextmenu.lut   false boolean A
  Show LUT in the contextual menu
• weasis.contextmenu.filter   false boolean A
  Show Filter in the contextual menu
• weasis.plugins.license   true boolean A
  Show license activation in Help menu

Viewer Category

• weasis.color.wl.apply   true boolean F
  Allow applying Window/Level on color images
• weasis.level.inverse   true boolean F
  Inverse level direction (moving the cursor down to increase brightness
• weasis.apply.latest.pr   false boolean F
  Apply by default the most recent Presentation State to the related image
• weasis.force.3d   false boolean A
  Force to detect a graphic card at every launch
• weasis.toolbar.mouse.left   winLevel string F
  Left mouse button action, possible values: pan|winLevel|sequence|zoom|rotation|measure|drawings|contextMenu|crosshair|none
• weasis.toolbar.mouse.middle   pan string F
  Middle mouse button action, possible values: pan|winLevel|sequence|zoom|rotation|measure|drawings|contextMenu|crosshair|none
• weasis.toolbar.mouse.right   contextMenu string F
  Right mouse button action, possible values: pan|winLevel|sequence|zoom|rotation|measure|drawings|contextMenu|crosshair|none
• weasis.toolbar.mouse.wheel   sequence string F
  Mouse wheel action, possible values: sequence|zoom|rotation|none

Customize resources

The default resources are located:

• With ViewerHub you can upload a new package “resources.zip” for a specific release.
• For the installed distribution in installedPath/app/resources

How to add DICOM nodes or DICOM printers at the server-side

• From the graphical user interface, configure the DICOM printers from File > Print > DICOM Print or DICOM nodes from File > Preferences > Dicom node list
• Go to the folder ${user.home}/.weasis/data/weasis-dicom-explorer
• Copy the desired configuration files: dicomNodes.xml, dicomPrinterNodes.xml, dicomWebNodes.xml and dicomCallingNodes.xml
• Paste at the root path of resources. For web distribution, unzip, place files and zip again.
• The new configurations should appear for all the users as non-editable configurations in Weasis

Build Plugins

How to build and install a plugin

This page provides a guide on creating new Weasis plugins and explains how to integrate them into the distributions. For details on configuring the development environment, refer to this guidelines page.

Types of Plugins in Weasis

The following list describes the types of plugins, the interfaces they implement and the factories they use:

1. Media Viewer or Editor
   • Represents the main central panel and implements either ViewerPlugin or ImageViewerPlugin.
   • The factory for this type implements SeriesViewerFactory.
   • For DICOM special modalities, you can use DicomSpecialElementFactory to associate a viewer to a specific DICOM object.
2. Toolbar Associated with a Viewer
   • Implements the Toolbar or DynamicToolbar interface.
   • The factory for this type implements InsertableFactory
3. Tool Associated with a Viewer
   • Represents the right panel and implements DockableTool.
   • The factory for this type implements InsertableFactory.
4. Data Explorer
   • The explorer model implements DataExplorerModel.
   • The explorer view implements DataExplorerView.
   • The factory for this type implements DataExplorerViewFactory.
5. Import Data into an Explorer
   • Adds a new page into the DICOM Import UI with ImportDicom.
   • The factory for this type implements DicomImportFactory.
6. Export Data from an Explorer
   • Adds a new page into the DICOM Export UI with ExportDicom
   • The factory for this type implements DicomExportFactory.
7. Media Codec
   • Implements the Codec interface to decode and encode media files related to a file extension or a mime type.
8. Preferences
   • Implements PreferencesPageFactory to add a new page in the Preferences dialog.
9. UI Aggregator
   • Represents the bundle for the application’s main user interface which aggregates various interface components.
   • The Maven artifact for this bundle must be defined in the base.json file (e.g., code:weasis.main.ui value:weasis-base-ui).

Building Plugins Using Maven Archetype

1. To add the Weasis archetypes to your local Maven repository, go to the Weasis/archetype directory and execute the following command:

      mvn install

2. Navigate to the target folder, which should be the parent folder of the new plugin project, and execute the following command to create your plugin:

      mvn archetype:generate -DarchetypeCatalog=local

3. When prompted, enter the number of one of the archetypes. Currently, the following archetypes are available:
   • weasis-plugin-base-viewer-archetype: Example of a toolbar and tool for a non-DICOM viewer.
   • weasis-plugin-dicom-viewer-archetype: Example of a toolbar and tool for a DICOM viewer.
4. Modify the generated project as needed.
   • In the pom.xml file, ensure the <relativePath> tag corresponds to the location of your Weasis source folder. By default, the value is <relativePath>../Weasis/weasis-parent/pom.xml</relativePath> (In this scenario, the plugin resides in the same parent folder as the Weasis source code).
   • When the relative path is set correctly, <version>${revision}${changelist}</version> in the pom.xml file will automatically be updated to the latest version of the Weasis source.
   • For easier version management in the pom.xml, you can remove <version> at the project level to inherit it from the parent.
5. Build the plugin by executing the following command in the plugin project directory:

      mvn clean install

Integrating Plugins into Weasis Distributions

Once the plugin is built, it can be integrated into the Weasis distributions either locally or remotely.

Testing the Plugin

To test the plugin with an installed version of Weasis without making any changes to the installed directory, create a JSON file that extends the configuration specified in base.json.

1. Create a new json file (e.g., myplugin.json) with the following content:

   {
     "weasisPreferences": [
       {
         "code": "org.osgi.framework.startlevel.beginning",
         "value": "550"
       },
       {
         "code": "felix.auto.start.500",
         "value": "file:///git/myplugin/target/myplugin-4.5.2.jar",
         "description": "Myplugin - a viewer for ..."
       }
     ]
   }

2. Update the content of myplugin.json as required:
   • Ensure the plugin start level (above 500) is lower than the OSGi beginning level (above 550). Avoid using values below this range to prevent conflicts with other plugins.
   • For easier testing, use an absolute JAR path that matches your local plugin directory. Use a URI format for the path like:
     ​

     Windows Linux macOS

       file:///D:/git/myplugin/target/myplugin-4.5.2.jar
     

       file:///git/myplugin/target/myplugin-4.5.2.jar
     

       file:///git/myplugin/target/myplugin-4.5.2.jar
     

3. Launch Weasis with your configuration:
   • Use the following parameter to extend the configuration (adapt the path to your local file):
     ​

     Windows Linux macOS

       $weasis:config pro="felix.extended.config.properties file:///D:/git/myplugin/myplugin.json"
     

       $weasis:config pro="felix.extended.config.properties file:///git/myplugin/myplugin.json"
     

       $weasis:config pro="felix.extended.config.properties file:///git/myplugin/myplugin.json"
     

   • Build a valid URI with the above parameter (see How to build an URI) and launch Weasis from the command on a terminal:Construct a valid URI using the parameter mentioned above (refer to How to build a URI)) and launch Weasis from the terminal using a command:
     ​

     Windows Linux macOS

       start weasis://%24weasis%3Aconfig%20pro%3D%22felix.extended.config.properties%20file%3A%2F%2F%2FD%3A%2Fgit%2Fmyplugin%2Fmyplugin.json%22
     

       xdg-open weasis://%24weasis%3Aconfig%20pro%3D%22felix.extended.config.properties%20file%3A%2F%2F%2Fgit%2Fmyplugin%2Fmyplugin.json%22
     

       open weasis://%24weasis%3Aconfig%20pro%3D%22felix.extended.config.properties%20file%3A%2F%2F%2Fgit%2Fmyplugin%2Fmyplugin.json%22
     

Using ViewerHub

This feature will be available soon. It will allow you to manage the plugins and their configurations directly from the ViewerHub web portal.

Build OSGi Services

All the plugin type described in the list above are OSGi services that are registered and aggregated in the GUI. Building the plugin from the Maven archetype will configure the OSGi service automatically. For adding new OSGi services, here is the procedure:

1. Create a class that implements the Insertable interface and represents a visual component. For example:

   public class MyPrefView extends AbstractItemDialogPage {
   
      public MyPrefView() {
          super("My Preferences", 100); // Provide a name and the page position
          initGUI();
      }
   
      private void initGUI() {
          // Add a basic JLabel to the preference panel for demonstration
          add(new JLabel("Welcome to My Preferences!"));
      }
   
      @Override
      public void closeAdditionalWindow() {
          // Handle any cleanup or saving preferences when closing
      }
   
      @Override
      public void resetToDefaultValues() {
          // Reset preferences to default values
      }
   }

2. Create a class that implements one of the plugin factories and include the annotations @Component and the @Service parameter. For example:

   @org.osgi.service.component.annotations.Component(service = PreferencesPageFactory.class)
   public class MyViewerPrefFactory implements PreferencesPageFactory {
   
       @Override
       public AbstractItemDialogPage createInstance(Hashtable<String, Object> properties) {
       return new MyPrefView();
       }
       
       @Override
       public boolean isComponentCreatedByThisFactory(Insertable component) {
       return component instanceof MyPrefView;
       }
   }

   Tip

   For more details on annotations, refer to the Apache Felix SCR Annotations documentation.