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.

Base preferences

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
• weasis.dicom.explorer.filter.mode   TEXT string F
  Default series filter mode in the DICOM explorer. Possible values: TEXT (full text), DATE (study date), MODALITY
• weasis.dicom.seg.hide.all   false boolean F
  If true, no segmentation is displayed when loaded; the user must enable them in the Segmentation tool or with the segmentation button in the view
• weasis.dicom.seg.hide.keywords   table removal, tabletop, couch, patient support, bed removal string F
  Comma-separated keywords to hide segmentations by default (case, spaces, underscores and hyphens are ignored when matching)
• weasis.import.dicom.network.cache   true boolean F
  Copy DICOM files imported from a network share (SMB/NFS mount, UNC path) or an optical disc into the local cache, so that images are read from the slow medium only once
• 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
• weasis.rt.dvh.recalculate.enable   true boolean F
  Enables experimental DVH (re)calculation in the RT plugin (derived from dicompyler, not clinically validated). When false (default), only DVHs stored in RTDOSE files are displayed.

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
• weasis.auth.back.port   0 int A
  Define the port for the authentication callback. 0 means random port

Launch Category

• weasis.clean.previous.version   true boolean A
  If true, the bundle cache is cleared when the weasis version has changed from the previous launch
• weasis.resource.stats.clean.previous.version   true boolean A
  If true, the measured resource statistics (peaks, uptime and events) are 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)
• weasis.pref.sync.documents   false boolean F
  Mirror the user documents (window presets, color maps, masking, measurement profiles) to the remote preference service. Keep it off until the service stores and returns such documents
• 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.export.annotations   false boolean A
  Show the Export Annotations button in the toolbar
• 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-dicom-viewer2d.all.redactiontoolbar.visible   false boolean A
  Show the redaction 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

Dicomizer preferences

Dicom Category

• weasis.acquire.dest.host   Null string A
  Hostname of DICOM send destination for Dicomizer. If no value, the list of DICOM nodes for storage is displayed.
• weasis.acquire.dest.aet   DCM4CHEE string A
  AETitle of DICOM send destination for Dicomizer
• weasis.acquire.dest.port   11112 int A
  Port of DICOM send destination for Dicomizer
• weasis.acquire.video.max.size   1024 int A
  Maximum size in MB of a video file that can be imported into the Dicomizer. A video file larger than this value is rejected with a message. A value of 0 or less disables the limit.

Metadata Category

• weasis.acquire.meta.global.display   PatientID,PatientName,PatientBirthDate,PatientSex,AccessionNumber,StudyDescription string A
  Comma-separated list of patient and study tags which are displayed in UI. When a required tag has no value, it will be displayed.
• weasis.acquire.meta.global.edit   StudyDescription string A
  Comma-separated list of patient and study tags which are editable in UI. When a required tag has no value, it will be editable.
• weasis.acquire.meta.global.required   PatientID,PatientName,AccessionNumber,StudyDescription string A
  Comma-separated list of patient and study tags which are required to publish an image
• weasis.acquire.meta.series.display   Modality,OperatorsName,ReferringPhysicianName,SeriesDescription string A
  Comma-separated list of series tags which are displayed in UI. When a required tag has no value, it will be displayed.
• weasis.acquire.meta.series.edit   ReferringPhysicianName,SeriesDescription string A
  Comma-separated list of series tags which are editable in UI. When a required tag has no value, it will be editable.
• weasis.acquire.meta.series.required   Modality,SeriesDescription string A
  Comma-separated list of series tags which are required to publish an image
• weasis.acquire.meta.image.display   ImageComments,ContentDate,ContentTime,AnatomicRegion string A
  Comma-separated list of image tags which are displayed in UI. When a required tag has no value, it will be displayed.
• weasis.acquire.meta.image.edit   ImageComments,ContentDate,ContentTime,AnatomicRegion string A
  Comma-separated list of image tags which are editable in UI. When a required tag has no value, it will be editable.
• weasis.acquire.meta.image.required   ContentDate string A
  Comma-separated list of image tags which are required to publish an image
• weasis.acquire.meta.study.description   Pictures of follow-up,Pictures of observation,Pictures preoperative,Pictures intraoperative,Pictures postoperative string A
  Comma-separated list of study description elements (to obtain a selection in a combo box). Empty value will be an editable text field
• weasis.acquire.meta.series.description   Null string A
  Comma-separated list of series description elements (to obtain a selection in a combo box). Empty value will be an editable text field

Ui Category

• weasis-base-viewer2d.all.rotationtoolbar.enable   false boolean A
  Show the rotation toolbar with base 2D viewer
• weasis-base-viewer2d.all.importtoolbar.enable   false boolean A
  Show the import toolbar with base 2D viewer
• weasis-base-viewer2d.all.minitool.enable   false string A
  Show the mini tool with base 2D viewer
• weasis-base-viewer2d.all.imagetool.enable   false boolean A
  Show Image Tools with base 2D viewer
• weasis-base-viewer2d.all.measuretool.enable   false boolean A
  Application
• weasis.toolbar.layout.button   false boolean A
  Show the layout toolbar
• weasis.toolbar.synch.button   false boolean A
  Show the synch toolbar

Configuration documents

A site ships its configuration as JSON documents in the config/ folder of the resources package since v4.8.0: resources.zip, uploaded in ViewerHub for a release and a group, or app/resources/config/ of a local installation. One document, one file:

Three layers, one rule

Every document is merged from three layers: the built-in document shipped with Weasis, the site document of config/, and the user document. The entries are merged by id:

• A later layer replaces the whole entry of the same id and keeps its position in the list; new ids are appended in document order.
• "hidden": true removes the entry from the lists. Redefine a built-in id with hidden to take it away from every user.
• "locked": true on a site entry forbids the user layer from replacing or hiding it. Only the site document can lock.
• "extends": "<id>" starts an entry from another entry of the same document, or of a lower layer, and gives only the fields that change. A field replaces the whole field of the base, nested objects included; extends, id and locked are never inherited.

Ids are <layer>.<kind>.<slug>, prefixed weasis. (built-in), site. or user.; an entry without an id gets one derived from what identifies it (the AE title, host and port of a DICOM node, the URL of a DICOMweb node, the name of a search template). Every document is a JSON object with "schema": 1 and an array of entries whose name depends on the document (presets, maps, nodes, methods, templates, modalities, launchers); a bare array is accepted when reading.

In the preference pages, a site entry is shown as read-only with (site) or (site, locked) after its name, and a user entry that overrides a site or built-in entry offers Reset to the site … / Reset to the built-in … in place of Delete. The Reload configuration files button at the bottom of the preferences dialog reads the site and user documents again without restarting Weasis. A Scope line under the pages that declare it says whether their settings follow your profile, belong to this workstation or come from your site.

Legacy XML files and migration

Until Weasis 5.2, the XML files placed at the root of the resources package before 4.8 — dicomNodes.xml, dicomCallingNodes.xml, dicomPrinterNodes.xml, dicomWebNodes.xml, authenticationNodes.xml, searchParameters.xml, attributes-view.xml, series-splitting-rules.xml — are still read when config/ holds no JSON document of the same kind; when both exist, the JSON wins. The shipped package carries config/attributesView.json and config/seriesSplittingRules.example.json, the built-in splitting rules as a starting point: rename it to seriesSplittingRules.json to activate it.

On the user side, the XML files of a 4.7 installation (DICOM nodes, printers, DICOMweb nodes, authentication methods, search templates) are converted once into their JSON documents at the first start of 4.8 and left untouched. Going back to 4.7 finds them as they were; the changes made in 4.8 are not carried back.

Secrets and remote preferences

Secrets never go into the user documents: the client secret of an authentication method and the values of the custom headers of a DICOMweb node are written empty in the document and kept in auth-secrets.json of the preferences folder, readable by its owner only and never exported.

The user documents are not sent to the ViewerHub preference service in 4.8.0: the property weasis.pref.sync.documents (default false) keeps that mirror off until the service stores and returns such documents.

Add DICOM nodes, printers or DICOMweb nodes for a site

1. Configure the nodes from the graphical user interface: DICOM nodes and DICOMweb nodes from File > Preferences > DICOM node list, DICOM printers from File > Print > DICOM Print.
2. Go to the folder ${user.home}/.weasis/data/weasis-dicom-explorer and copy the desired documents: dicomNodes.json, dicomPrinterNodes.json, dicomWebNodes.json, dicomCallingNodes.json (and authentication.json for the methods a DICOMweb node refers to).
3. Rename the ids from user. to site., add "locked": true to the entries the users must not replace, and fill in the header values of the DICOMweb nodes, which the user document leaves empty.
4. Paste them into the config/ folder of the resources package. For a web distribution, unzip resources.zip, add the files and zip it again.
5. The nodes appear for every user as (site) entries, read-only.

A DICOM node (dicomNodes.json, same shape for the calling nodes and the printers):

{
  "schema": 1,
  "nodes": [
    {
      "id": "site.node.pacs",
      "type": "DICOM",
      "description": "Main PACS",
      "aeTitle": "PACS",
      "hostname": "pacs.example.org",
      "port": 11112,
      "usageType": "BOTH",
      "tsuid": "EXPLICIT_VR_LE",
      "locked": true
    }
  ]
}

usageType is RETRIEVE, STORAGE or BOTH; tsuid is the transfer syntax asked for a retrieve, left out to keep the original one. A DICOMweb node (dicomWebNodes.json) gives the service instead of the AE; authMethod is the uid of a method of authentication.json:

{
  "schema": 1,
  "nodes": [
    {
      "id": "site.node.dicomweb",
      "type": "WEB",
      "description": "DICOMweb archive",
      "url": "https://pacs.example.org/dicomweb",
      "webType": "DICOMWEB",
      "authMethod": "d5f0c1e2-…",
      "headers": {"X-Api-Key": "…"}
    }
  ]
}

webType is DICOMWEB (all RESTful services), QIDORS, WADORS, STOWRS or WADO (WADO-URI).

Search templates

searchTemplates.json holds the templates of the Query/Retrieve dialog; the tags are DICOM keywords and period is one of the periods of the dialog (ALL, TODAY, YESTERDAY…):

{
  "schema": 1,
  "templates": [
    {
      "id": "site.search.ct-today",
      "name": "CT of the day",
      "period": "TODAY",
      "params": [
        {"tag": "ModalitiesInStudy", "values": ["CT"]}
      ]
    }
  ]
}

Viewer annotations

attributesView.json sets, per modality, the attributes drawn in the four corners of a view. The entry id is the modality (DEFAULT, CT, MG…), extends starts from another modality, and each corner — topLeft, topRight, bottomLeft, bottomRight — is a list of lines numbered from 1 to 7; a corner given here replaces the whole corner of the base. A line tries its tags in order until one has a value, and format renders it: $V is the value, $V:l$25$ limits it to 25 characters, $V:f$#,##0.##$ applies a Java decimal pattern.

{
  "schema": 1,
  "modalities": [
    {
      "id": "MG",
      "extends": "DEFAULT",
      "bottomRight": [
        {"line": 2, "tags": ["SeriesNumber"], "format": "Series Nb: $V"},
        {"line": 3, "tags": ["FrameLaterality", "ImageLaterality", "Laterality"], "format": "Laterality: $V"},
        {"line": 7, "tags": ["ViewPosition"], "format": "Position: $V:l$25$"}
      ]
    }
  ]
}

Series splitting rules

seriesSplittingRules.json sets, per modality, the attributes whose change splits a series into several views: splittingTags for single-frame images and multiframeSplittingTags for the frames of a multi-frame image. An item is {"tag": "Keyword"}, with an optional condition that restricts the split: allOf or anyOf over leaves {"tag", "operator", "negate", "ignoreCase", "values"} — operator is equals or contains — or nested groups.

{
  "schema": 1,
  "modalities": [
    {
      "id": "CT",
      "extends": "DEFAULT",
      "splittingTags": [
        {"tag": "ImageType"},
        {"tag": "ConvolutionKernel"},
        {"tag": "ImageOrientationPlane",
         "condition": {"allOf": [
           {"tag": "ImageType", "operator": "contains", "negate": true, "ignoreCase": true, "values": ["PROJECTION"]}
         ]}}
      ]
    }
  ]
}