Weasis is a multipurpose standalone and web-based DICOM viewer with a highly modular architecture. It is a very popular clinical viewer used in healthcare by hospitals, health networks, multicenter research trials, and patients.
It has been designed to meet several expectations of clinical information systems and their future evolution regarding medical imaging: providing web-based access to radiological images, as well as covering a considerable number of DICOM types and offering multimedia capabilities.
Here are the main features:
Display all kinds of DICOM files (including multi-frame, enhanced, MPEG-2, MPEG-4, MIME Encapsulation, SR, PR, KOS, AU, RT and ECG)
Viewer for common image formats (TIFF, BMP, GIF, JPEG, PNG, RAS, HDR, and PNM)
Feel free to update this content, just click the Edit button displayed on top right of each page, and pullrequest it.
Info
Your modification will be deployed automatically when merged.
Documentation website
This current documentation has been statically generated with Hugo with a simple command: hugo – source code is available at GitHub.
Subsections of Weasis DICOM medical viewer
Getting Started
Try Weasis now
Please see this page for a complete list of downloads and if you would like an automatic update of Weasis according to your system.
Since version 4, only the distribution with a native installer is maintained to ensure a better user experience in terms of installation, configuration and compatibility. This distribution also allows launching Weasis from a web context using the weasis protocol.
For more information on GLIBC versions regarding the life cycle of the different Linux distributions, see this page.
Note
To manage Weasis version at the server side, it is possible to install the Weasis web package which will upgrade the native installation at the client side (it works for minor releases by updating all the plug-ins except the launcher).
The different possibilities for integrating Weasis with other systems are described here.
Tip
Join the google group (Choose Email to read this group) to stay informed about new releases and updates.
The package management systems above can limit certain functionalities because they work in sandbox mode, especially for Flatpak (see Fedora issue) and Snap (see removable media issue).
The Snap package installation uses a <user.home>/snap/weasis/current/.weasis directory instead of the <user.home>/.weasis directory for all other installations.
This page describes how installing Weasis to be the default web viewer of dcm4chee-arc-light web interface. See How to launch Weasis from any environments to integrate Weasis into your own user interface.
Weasis is launched from the dcm4chee administrative web interface with the weasis protocol, as shown in the pictures below.
For a simpler and faster installation without server components, please follow these instructions; no need to consider the following points on this page. Otherwise if you need more advanced configurations then follow these steps:
Install dcm4chee, if not already done (Installation with Docker is straightforward).
Go here and download these following files:
Warning
Download issue: Some browsers (like Internet Explorer) may rename war files to zip. If so, use the Save As option when downloading and change the name back to war.
From weasis-pacs-connector folder:
[weasis-pacs-connector.war] Requires at least the version 7.1.2
From the folder with the latest version number (Optional if you want to run only the native version installed on the client system):
Add the .war files using the “Add” button (Choose Upload a new deployment or select Replace when the file already exists)
Note
Alternatively one may deploy .war files using JBoss Command Line Interface Console.
Configure weasis-pacs-connector (This step is optional if you just want to keep the default configuration).
The default configuration is stored in two files inside weasis-pacs-connector.war. To override the default configuration:
Edit the configuration as needed. For example, dcm4chee may be running on a different computer than Weasis, or the AE Title of dcm4chee may have been changed. If so, edit weasis-pacs-connector.properties or dicom-dcm4chee-arc.properties (Change pacs.host, pacs.port, and pacs.aet).
Copy weasis-pacs-connector.properties and dicom-dcm4chee-arc.properties into $WILDFLY_HOME/standalone/configuration (where $WILDFLY_HOME is the path of the running Wildfly).
With the docker installation use the docker copy command ($ docker cp …)
Tip
Instead of copying the files into $WILDFLY_HOME/standalone/configuration, JBoss Command Line Interface Console can be used to override files in the war. Add the two configuration files with the deployment-overlay command:
For applying the new configuration, from the management console “Disable” weasis-pacs-connector.war and then “Enable”
To activate Weasis in the dcm4chee-arc-light user interface (see the matrix of the required versions in the table below):
you need to add attributes by either editing docker-compose.env (from 5.22.0) or from the left menu Configuration > Devices > dcm4chee-arc > Extensions > Edit extension > Child Objects > Web Applications > DCM4CHEE (add &cdb to the URL if weasis.war has not been deployed on the server-side):
Configure the URL for having a view button for the patient or study level.
From dcm4chee-arc-light 5.10.2 to 5.19.0 the left menu Configuration > Devices > dcm4chee-arc > Extensions > Archive Device
From dcm4chee-arc-light 5.19.1 the left menu Configuration > Devices > dcm4chee-arc > Extensions > Edit extension > Child Objects > Web Applications > DCM4CHEE
From dcm4chee-arc-light 5.22.0 by editing docker-compose.env (It allows you to directly apply the properties when deploying, then the can be edited in the web portal). Note: the character ‘&’ must be escaped (e.g. IID_STUDY_URL=../../weasis-pacs-connector/weasis?studyUID={{studyUID}}\&access_token={{access_token}})
Note
URL parameters
access_token is necessary in secure mode (secured RESTful services) from dcm4chee-arc-light 5.15.1
_self avoids to open a new empty window in the web browser
cdbcdb parameter to override the URL of the Weasis web context to null (when you want only the native local version or when weasis.war has not be deployed with weasis-pacs-connector)
Absolute path: The values above starting by “../” are the default relative path when weasis-pacs-connector is installed in the same JBoss as dcm4chee. Otherwise replace the relative URL by an absolute value, ex: http://<your-host>:<port>/weasis-pacs-connector/...
* Running only the local native version of Weasis (when not connected to a remote version - weasis.war -)
Weasis Web Protocol
The web protocol allows launching Weasis in a web context from a specific URI scheme: weasis://parameters
Warning
Requires Weasis 3.5 (or superior) installed on the system with a native installer.
How to use the weasis protocol
From a web page, just make a link starting with weasis:// (see below How to build an URI)
Note
Some web frameworks such as the wiki or the URL field of some browsers only support the standard protocols (http, ftp…). To solve this problem, it is necessary to use a URL redirection starting with http like the one proposed in weasis-pacs-connector: http://<your-host>:8080/weasis-pacs-connector/weasis?patientID=TESTS
open weasis://%24dicom%3Aget+-w+%22https%3A%2F%2Fnroduit.github.io%2Fdemo-archive%2FLumbar%2Fmf.xml%22
Tip
When first used in a browser, a popup appears to confirm the opening of the weasis protocol. On Windows, it is possible to make sure that this message never appears by adding a browser policy which allows the URI weasis://* - With IE/Edge the policy is applied by the native installer. - With Chrome the policy is applied by the native installer (Windows and Linux), see how to manage URLWhitelist (d).
How to build an URI
The URI scheme “weasis://” allows you to launch Weasis from the system’s URI handler while the URI path allows you to build Weasis commands.
weasis-pacs-connector will help to build dynamically the manifest (the references of the images to be loaded) and the launch parameters (user, profile, plugins…). It will also manage user preferences.
To build an URI (weasis://path) without weasis-pacs-connector, you must choose one or more commands, encode the commands, and add the scheme weasis:// as prefix. Here is an example of loading an image:
To load multiple remote images, it is recommended to use a manifest listing the references of the images to be loaded. The easiest way to dynamically build this manifest is to use weasis-pacs-connector. However, it is possible to build it differently with the following instructions.
Examples to load images
If you use weasis-pacs-connector, please refer to Launch Weasis.
Use $dicom:get to load a static XML manifest containing direct links (without WADO server)
Launch
The command for modifying the configuration at launch is $weasis:config which can have different arguments:
cdb is the Weasis web context (The URL of weasis.war). If the value is null, the weasis version installed from the native installer is used. In the weasis-pacs-connector configuration, the default value is defined by weasis.base.url.
cdb-ext is the extension web context of Weasis (The URL of weasis-ext.war containing additionnal plugins). In the weasis-pacs-connector configuration, the default value is defined by weasis.ext.url.
arg is an argument for the launcher. The value must start by $, like arg="$dicom:close –all" (Note: the value can also be directly in the base URI, outside $weasis:config). Single-valued argument but can be specified multiple times.
pro is a property for the launcher containing a key and a value separate by a space. Single-valued property but can be specified multiple times.
auth is the web authorization parameter
wcfg is the URL the remote Weasis configuration service.
Here are some examples that modify the launcher properties without using weasis-pacs-connector:
Configuration for launching Weasis Dicomizer
Launch
Change the user, by default is the one of the current system session. The local preferences are associated to a user.
Launch
$weasis:config pro="weasis.user user2"
Building Weasis
These instructions describe how to build Weasis directly from the Git repository on any platform. For building Weasis from an IDE, see Weasis plug-in development guidelines.
Prerequisites
JDK 22 or higher
Maven 3.5.3 or higher
If your computer is behind a proxy server, configure maven.
Git
Getting the Source
In order to clone the repository, first install GIT and either clone using a graphical GIT client or directly from the command line using the command:
git clone https://github.com/nroduit/Weasis.git
Building all Plug-ins
Go in the Weasis directory, compile and install all the plug-ins in the local Maven repository:
mvn clean install
Package weasis-native.zip (located in target/native-dist/), since Version4.0.0 :
-P compressXZ: Option for compressing the packages in xz, only from Weasis 3.6.0. The compression pack200 is not supported anymore (removed from Java 14), before 3.6.0 the profile was -P pack200.
Tip
-P purgeI18nPackage: Option to delete the translation package in the local maven repository (active by default). To disable this option, add - before the profile:
For production, version must not be SNAPSHOT (otherwise packages will not be kept in cache). So to remove SNAPASHOT or to make your own release (for avoiding package mix-up in cache), modify the changelist property. From the Weasis root folder, execute:
However, it is possible to run a local script package-weasis.sh on most systems but without guarantee because the system must have a correct configuration of several tools (see jpackage prerequisites).
Get weasis-native.zip, unzip the archive and then go to the root folder with a bash prompt.
In the commands above, adapt the --jdk value to your local JDK path.
For building only the native binaries (without installer), add the parameter --no-installer
In order to see the use of the script and its options, run:
./build/script/package-weasis.sh --help
Tip
On Windows the bash script must be executed with Git Bash or Cygwin. Avoid having spaces in the input and output paths.
Guidelines
Weasis Plug-in Development
This page describes the necessary configurations to be able to debug Weasis using an IDE. For developers who want to create new plug-ins, you can visit How to build and install a plug-in.
We recommend the use of IntelliJ IDEA because the following instructions are based on it. Nevertheless, it is possible to use other IDEs by configuring weasis-launcher with similar instructions described in Add a launcher.
Prerequisites
Install IntelliJ IDEA (Community or Ultimate Edition 2024.1 or higher)
Use JDK 22 or higher and set the language level to 22 - Unamed variables and patterns in _File > Project Structure… > .
In File > Settings… > Plugins install google-java-format plugin from Marketplace and enable it from google-java-format Settings
Code style and convention
Weasis uses google-java-format as coding conventions. The format can be applied by Maven through the Spotless plugin or from the IDE (by importing the IntelliJ Java Google Style file). Formatting code with an IDE is not 100% compatible with Spotless, so it is better to use the latter before submitting new commits. This guarantees identical code formatting regardless of the system or code editor used.
From IntelliJ IDEA: New > Project from Version Control…
In the Get from Version Control dialog, select the menu Repository URL and enter the following URL: https://github.com/nroduit/Weasis.git (public repository)
Building Weasis plug-ins
In the maven panel, select clean/install in Lifecycle of weasis-framework (root) to compile and to install all the plug-ins in the local Maven repository.
Tip
It is possible to use a JVM Option (e.g. -Dweasis.arch=linux-x86-64) to limit the build of native plugins only to the architecture of the current system (do not use this option when building the distribution).
For running or debugging Weasis, you need to create a launcher:
Open Run > Edit Configurations…
Create a new Application
Select weasis-launcher as a module (field starting by -cp)
Main Class: browse org.weasis.launcher.AppLauncher
Click on Modify Options
Select Add dependencies with “Provided” scope to classpath
Select Do not build before run
Select Add VM Options and enter -Xms64m -Xmx768m -Dgosh.port=17179
Working Directory: remove the current value and add %MODULE_WORKING_DIR% from the Insert Macros button
Note
As the default build task has been removed it is necessary to apply the Maven command install on modules with modified code before launching the Run or Debug mode.
Keeping the build task and delegating the build to Maven does not seem configurable for a multi-module project, see this issue.
Examples of launching parameters by entering values in the Program arguments text box
Loading DICOM files from a local path:
$dicom:get -l \"D:\images test\dicom\"
Note
Some command interpreters need to escape the quotes or double quotes required for paths or URLs. This is the case with IntelliJ IDEA or Eclipse.
For more commands at startup see also Weasis commands.
Warning
In Eclipse launcher parameters, ‘&’ within URLs needs to be escaped with a backslash.
Examples of other VM options for overriding the default Preferences
Removing the possibility of exporting DICOM: -Dweasis.export.dicom=false
Defines a new user (for getting specific preferences): -Dweasis.user=user1
Examples with specific configuration files:
For launching Weasis Dicomizer: -Dfelix.extended.config.properties=file:target/conf/dicomizer.json
Configuration from an URL: -Dfelix.extended.config.properties=https://mysite.com/weasis/conf/config.json
Note
felix.config.properties defines the location of base.json (the OSGI configuration and the list of plug-ins to install/start) felix.extended.config.properties defines the location of a json file (extends/overrides base.json)
Internationalization
Translation files are hosted and managed on the Transifex website. Get an account and help to translate to your language! If your language is missing, just head over to Transifex and request a new language.
Warning
Text length: The translations for many languages frequently exceed the length of the corresponding English source. It could be a problem for the layout of graphical components (e.g. buttons). Some elements have a character limit on the translation tool.
Tip
Special characters: Some characters representing values (%d, %s), newline (\n) and HTML tags must not be translated. For other translating recommendations, see Transifex help
For special words or particular contexts look at the “Instructions” text box (gives explanations or definitions).
Building Weasis-i18n
weasis-i18n is the internationalization project (i18n) of Weasis. As a separate project, it can have its own release cycle. The OSGi fragments of plug-ins contain only the translation files which are merged during runtime to the matching module of the application.
That means the translation packages can be deployed at any time, it does not need to follow the Weasis life cycle. With remote packages, the plug-in translation will be updated by Weasis only if the timestamp number has changed. This timestamp is set during the build phase described below.
Info
Additional projects to obtain a full translation of Weasis:
The java-swing-dialogs translations must be updated manually in the weasis-launcher module and docking-frames translations must be packaged witin the library.
Prerequisites
JDK 11 or higher
Maven 3 or higher
If your computer is behind a proxy server, configure maven.
Git or directly download the source code from GitHub
Getting the Source
To clone the repository, first install GIT and either clone using a graphical GIT client (such as Tortoise Git) or directly from the command line using the command:
The distribution files are located in the weasis-i18n-dist/target/dist folder.
Apply the translations
The translation package can be built manually as described below or it is automatically built every 24 hours and can be downloaded from here. When Building Weasis, the last package is downloaded automatically.
In order to update Weasis with new translations, unzip weasis-i18n.zip and either:
Replace the files in the “bundle-i18n” folder where Weasis is installed (not possible when Weasis is distributed from an application store or the Mac signed package).
Note
weasis-launcher-i18n cannot be updated dynamically as the launcher is not an OSGi module. It must be imported manually into the Weasis source (weasis-launcher).
Weasis has a modular architecture based on OSGi: the dynamic module system for Java. It uses the Apache Felix OSGi framework which is an open source implementation of the OSGi specification.
The following schemas show the main different plug-in types (bundle in OSGi language) and their relationships. Viewer, Viewer Tool Pane, Tool Bar, Data Explorer and Codec bundles are registered dynamically by the Declarative Services (a way to push or to consume services in OSGi environment).
For each bundle, translation files are packaging in a separated bundle ending by “i18n” called a bundle fragment (OSGi concept) which is merged during runtime to the application. In this way, translation can be handled separately and they are automatically loaded by the application when they are available.
Some Codec bundles also have bundle fragments. Those fragments contain native libraries (JNI wrapping). The Weasis launcher enables downloading and loading only the native binaries related to the running platform.
Go the next view when layout has more than one view
Shift + Tab
Go the previous view when layout has more than one view
Alt + Arrows
Move image of 5 pixels (since
v4.2.1
)
Alt + Shift + Arrows
Move image of 10 pixels (since
v4.2.1
)
Ctrl + Plus (+)
Zoom in (since
v4.2.1
)
Ctrl + Minus (-)
Zoom out (since
v4.2.1
)
Ctrl + Enter
Set zoom to best fit (since
v4.2.1
)
T
Translate (pan) the image canvas
W
Window / Level
S
Series scroll
Z
Zoom
R
Rotation
H
Crosshair: in multiview mode synchronizes the crosshair position to all the views (Note: Ctrl + click or Ctrl + Shift + click allows changing the Window / Level values)
C
Cine Start / Stop
M
Measure
D
Distance measurement
A
Angle measurement
Y
Polyline measurement
B
Textbox
Q
Context menu
Ctrl + Spacebar
Change to the next action
Ctrl + mouse drag
Accelerate the current action
Ctrl + Shift + mouse drag
Accelerate more the current action
Alt + R
90° rotation (clockwise)
Alt + L
90° rotation (counterclockwise)
Alt + F
Flip horizontally (after rotation action)
0 1 2 3…
DICOM presets
K
Toggle key image state
Spacebar
Show/Hide all the annotations (three states)
I
Show/Hide all the annotations (three states)
Escape
Reset the selected view
P
Print view(s) with the operating system printer
Right-click
Open the contextual menu for more options
Double click
Toggle fullscreen
Drag files/directories (from the OS file manager)
Open DICOMs files
DICOM explorer
Shortcut
Action
Ctrl + click on the thumbnail
Select multiple series
Click on a thumbnail and then Shift + click on another one
Select all series between
Ctrl + A
Select all the series
Home or Page Up
Select the first series
End or Page Down
Select the last series
Up Arrow
Select previous series
Down Arrow
Select next series
Enter
Open the selected series in the default viewer
Click + drag a thumbnail in the main view
Display a series
Right-click
Open the contextual menu for more options
Drag files/directories (from the OS file manager)
Open DICOMs files
Note
Downloading Priorities: Selecting a thumbnail gives the best priority to download.
Graphics
Shortcut
Action
Click on a graphic
Select a Graphics
Click + mouse drag
In selection mode: select all the graphics inside the selection area. In drawing mode: draw the selected graphic shape.
Ctrl + A
Select all the graphics
Ctrl + D
Deselect all the graphics
Delete
Delete the selected graphics
Shift + click on a graphic
In selection mode: add or remove a graphic to the current selection. In drawing mode: force to draw on another graphic (without shift the graphic is selected).
Double click
Stop adding points for polyline (also available in the context menu)
Right-click
Open the contextual menu for more options
Tips and Tricks
Window / Level:
Horizontal movement of the mouse to the right will widen the window width (flatten the perceived contrast)
Vertical movement of the mouse upwards will lower the window center (increase the perceived brightness). See Preferences to inverse level direction.
Standard workflow when connecting Weasis to a PACS, RIS, EMR, EPR or any web interface:
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.
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:
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.
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
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.
Currently, the DICOMWeb service of DICOMcloud doesn’t support:
Thumbnail service is not implemented.
Preferences
The WEB distribution (weasis.war) allows delivering preferences from the server-side to the client-side. Some preferences on the server-side are used by Weasis only during the first launch because they can be changed later in the Weasis user interface. The other preferences at the server-side are used by Weasis at every launch.
Local preferences can be changed by:
The Weasis user interface: File > Preferences
The weasis protocol with the command weasis:config and the pro parameter
Preferences on the server-side can be changed by:
Replacing ext-config.properties which extends and overrides config.properties, see the tip below.
The weasis protocol with the command weasis:config and the pro parameter
Tip
How to modify ext-config.properties:
Unzip weasis.war, modify the file and zip it again.
It is also possible to change the default location of ext-config.properties with the Java property “felix.extended.config.properties” with the parameter cdb-ext of the weasis service. The ext-config.properties file can also be placed in a plugin package, see How to build and install a plug-in.
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/).
If you are using weasis-pacs-connector, add the propertylocale.lang.code:
GUI: if yes, the property can be modified in the Weasis user interface.
Type: F: only caught at the first launch of the viewer. A: always caught by the viewer. AP: always caught by the viewer but only from ext-config.properties or config.properties .
Property
Default value
GUI
Type
Description
weasis.confirm.closing
false (since
v2.0.0
)
yes
F
Show a message of confirmation when closing the application.
weasis.show.disclaimer
true
no
A
Show a disclaimer (requires to be accepted to start the application) during the first launch of Weasis.
weasis.show.release
true (since
v2.0.0
)
no
A
Show a message when the release has changed
weasis.export.dicom
true (since
v1.2.5
)
no
A
Allows exporting DICOM files.
weasis.portable.dicom.cache
true
no
A
Cache the images imported from directories defined in weasis.portable.dicom.directory. If true, it is similar to the WEB import.
org.apache.sling.commons.log.level
INFO
yes
F
Sets the logging level of the loggers. This may be any of the defined logging levels TRACE, DEBUG, INFO, WARN, ERROR.
org.apache.sling.commons.log.file.activate
false
yes
F
Activate the log file. If this property is false, log messages are written to System.out. Since Weasis 2.0.4
Formatting log messages. java.util.MessageFormat pattern supporting up to six arguments: {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.
locale.lang.code
en
yes
F
Language code (see Java Locale). If the value is “system” then the locale of the operating system will be used (client-side).
locale.format.code
system
yes
F
Format code for number and date (see Java Locale). If the value is “system” then the locale of the operating system will be used (client-side).
weasis.name
Weasis
no
AP
Change the name of the application everywhere in UI
weasis.profile
default
no
AP
Application profile, it allows having a custom preferences directory on the client side (will not shared preferences with other Weasis instances)
weasis.resources.url
${weasis.codebase.url}/resources.zip
no
A
Application resource files (logo, presets, LUTs…). “resources.zip” is downloaded again only when the last modified date has changed.
weasis.download.immediately
true
yes
F
Start to download series immediately
download.concurrent.series
3
no
A
The number of concurrent series downloads
download.concurrent.series.images
4
no
A
The number of concurrent image downloads in a series
audit.log
false
no
A
Audit log for giving statistics about usage of Weasis
Tags at the image level that are visible in Dicomizer
weasis.acquire.meta.image.edit
ImageComments, ContentDate, ContentTime
no
A
Image tags which are editable
weasis.acquire.meta.image.required
ContentDate
no
A
Image tags which are required for publication
weasis.acquire.dest.host
localhost
no
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
no
A
AETitle of DICOM send destination for Dicomizer
weasis.acquire.dest.port
11112
no
A
Port of DICOM send destination for Dicomizer
weasis.acquire.meta.study.description
Pictures of follow-up,Pictures of observation,Pictures preoperative,Pictures intraoperative,Pictures postoperative
no
A
Comma-separated list of study description elements. Comment this property to have a free text field.
weasis.acquire.meta.series.description
no
A
Comma-separated list of series description elements. Comment this property to have a free text field.
weasis.level.inverse
v2.6.0
true
yes
F
Inverse level direction (moving the cursor down to increase brightness)
weasis.apply.latest.pr
v2.6.0
false
yes
F
Apply by default the most recent Presentation State to the related image
weasis.user
v2.6.0
system user
no
A
Defines a user with its own preferences
weasis.pref.store.local.session
v3.5.3
false
no
A
Store user preferences when weasis.user is not specified (only with remote preferences service)
weasis.theme
v4.0.0
org.weasis.launcher.FlatWeasisTheme
yes
F
FlatWeasisTheme is the default dark theme. All the themes comes from FlatLaf
weasis.theme.${system}
v4.0.0
org.weasis.launcher.FlatWeasisTheme
yes
F
Apply a default theme specific to the platform (macosx, linux, windows).
flatlaf.uiScale
v4.0.0
1.0 (or the default scale factor of the Operating System)
yes
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.update.release
v4.0.1
true
no
A
Show a message when a new release is available
Examples of properties in ext-config.properties
Changing the default theme of the user interface
# Define the theme for the first launch according to the platform (macosx, linux, windows)weasis.theme=org.weasis.launcher.FlatWeasisThemeweasis.theme.macosx=com.formdev.flatlaf.FlatIntelliJLafweasis.theme.linux=com.formdev.flatlaf.FlatDarculaLaf
Customize resources
The default resources are located:
For the web distribution in “resources.zip” at the root of weasis.war (see above how to set a new URL for resources)
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 Plug-ins
How to build and install a plug-in
This page describes how to build new Weasis plug-ins and how they can be incorporated into the distributions, see also this page for the IDE configuration.
List of plug-ins types
Media viewer or editor (main central panel that implements ViewerPlugin or ImageViewerPlugin and the factory implements SeriesViewerFactory)
Toolbar associated with a viewer (implements Toolbar)
Tool associated with a viewer (right panel that implements DockableTool)
Data Explorer (data model implements DataExplorerModel and data view implements DataExplorerView, and the factory implements DataExplorerViewFactory)
Import data into an explorer (ex. ImportDicom and the factory implements DicomImportFactory)
Export data into an explorer (ex. ExportDicom and the factory implements DicomExportFactory)
DICOM editor or viewer for special modalities (DicomSpecialElementFactory and SeriesViewerFactory), see weasis-dicom-sr
Media codec (implements Codec)
Preferences (implements PreferencesPageFactory)
UI aggregator. This is the application main user interface bundle. The maven artifact of this bundle must be defined in config.properties (ex. weasis.main.ui=weasis-base-ui)
From the folder Weasis/archetype execute: mvn install
Generate a sample project by executing the following command: mvn archetype:generate -DarchetypeCatalog=local
Select the archetype:
weasis-plugin-base-viewer-archetype (example of a toolbar and a tool for the non DICOM viewer)
weasis-plugin-dicom-viewer-archetype (example of a toolbar and a tool for the DICOM viewer)
Note
From Eclipse: File > New > Maven Project and Search for weasis archetype in catalog filter.
From Intellij: File > New Project > Maven, select the “Maven Archetype” generators and select a Weasis archetype from Default local catalog.
Tip
In the pom.xml of the new plug-in, the tag <relativePath> must be adapted to your relative path of Weasis sources.
The default value is <relativePath>../Weasis/weasis-parent/pom.xml</relativePath>
Install plug-ins
Warning
This documentation has not been updated since version 4.2.0 where the properties configuration files have been replaced by json files.
The way to add plugins will also evolve soon with the new weasis-manager component.
For the installed distribution
The file “app/conf/ext-config.properties” must be adapted and plug-ins must be placed in the directory “app/plugins”.
If you want to use another directory for a plugin on your computer, you should use one of the following properties:
On Windows: felix.auto.start.85=file:///C:/path/to/weasis-isowriter-2.6.1.jar
On linux: felix.auto.start.85=file:///home/Username/path/to/weasis-isowriter-2.6.1.jar
On macOS: felix.auto.start.85=file:///Users/Username/path/to/weasis-isowriter-2.6.1.jar
Tip
For not modifying the current ext-config.properties create a new file and add to the launcher the following VM argument:
-Dfelix.extended.config.properties="file:///your_plugin_path/myplugin-config.properties"
Place the file “weasis-isowriter-2.6.1.jar” in the directory “/weasis/plugins”
For the WEB distribution
Build a new war file containing the plug-ins and the ext-config.properties file.
Build “weasis-ext.war” with the following structure:
Using ${weasis.codebase.ext.url} allows you to keep the base URL abstract, so moving the package to another server won’t be a problem. Otherwise absolute URLs must be used. The default value of ${weasis.codebase.ext.url} is ${weasis.codebase.url}-ext.
weasis-ext is the default web context when launching Weasis, using another web context requires modifying the property weasis.ext.url, it can be done by:
For debugging a specific configuration: add to the launcher the following VM argument:
-Dfelix.extended.config.properties="http://server:port/weasis-ext/conf/ext-config.properties
All the plug-in type described in the list above are OSGi services that are registered and aggregated in the GUI. Building the plug-in from the Maven archetype will configure the OSGi service automatically. For adding new OSGi services, here is the procedure:
Create a class implementing one of the plug-in types and add at least the annotations @Component and @Service, for instance:
Add in pom.xml of the plug-in the maven-scr-plugin (to generate XML file from the Java annotations) and the property for loading any XML file in maven-bundle-plugin:
The commands listed below can be applied at start-up or in a telnet session. All the commands starting with “dcmview2d:” allow you to drive Weasis and are not adapted to be used at start-up.
Info
This page matches to Weasis 3.5.1 or higher. The syntax of usage comes from POSIX.
To obtain the list of commands, after starting Weasis, open a local telnet session of the OSGI Console and type lb for getting the list of bundles and their state or type help for getting all the available commands:
telnet localhost 17179
Trying 127.0.0.1...
Connected to localhost.localdomain.
Escape character is '^]'.
____________________________
Welcome to Apache Felix Gogo
g!
List of Weasis commands
dcmview2d:layout
g! dcmview2d:layout
Select a split-screen layout
Usage: dcmview2d:layout ( -n NUMBER | -i ID )
-n --number=NUMBER select the best matching number of views
-i --id=ID select the layout from its identifier
-? --help show help
dcmview2d:mouseLeftAction
g! dcmview2d:mouseLeftAction
Change the mouse left action
Usage: dcmview2d:mouseLeftAction COMMAND
COMMAND is (sequence|winLevel|zoom|pan|rotation|crosshair|measure|draw|contextMenu|none)
-? --help show help
dcmview2d:move
g! dcmview2d:move
Pan the selected image
Usage: dcmview2d:move -- X Y
X and Y are Integer. It is mandatory to have '--' (end of options) for negative values
-? --help show help
dcmview2d:reset
g! dcmview2d:reset
Reset image display
Usage: dcmview2d:reset (-a | COMMAND...)
COMMAND is (winLevel|zoom|pan|rotation)
-a --all reset to original display
-? --help show help
dcmview2d:scroll
g! dcmview2d:scroll
Scroll into the images of the selected series
Usage: dcmview2d:scroll ( -s NUMBER | -i NUMBER | -d NUMBER)
-s --set=NUMBER set a new value from 1 to series size
-i --increase=NUMBER increase of some amount
-d --decrease=NUMBER decrease of some amount
-? --help show help
dcmview2d:synch
g! dcmview2d:synch
Set a synchronization mode
Usage: dcmview2d:synch VALUE
VALUE is (None|Stack|Tile)
-? --help show help
dcmview2d:wl
g! dcmview2d:wl
Change the window/level values of the selected image (increase or decrease into a normalized range of 4096)
Usage: dcmview2d:wl -- WIN LEVEL
WIN and LEVEL are Integer. It is mandatory to have '--' (end of options) for negative values
-? --help show help
dcmview2d:zoom
g! dcmview2d:zoom
Change the zoom value of the selected image
Usage: dcmview2d:zoom (set VALUE | increase NUMBER | decrease NUMBER)
-s --set=VALUE [decimal value] set a new value from 0.0 to 12.0 (zoom magnitude, 0.0 => default, -200.0 => best fit, -100.0 => real size)
-i --increase=NUMBER increase of some amount
-d --decrease=NUMBER decrease of some amount
-? --help show help
dicom:get
g! dicom:get
Load DICOM files remotely or locally
Usage: dicom:get ([-l PATH]... [-w URI]... [-r URI]... [-p] [-i DATA]... [-z URI]...)
PATH is either a directory(recursive) or a file
-l --local=PATH open DICOMs from local disk
-r --remote=URI open DICOMs from an URI
-w --wado=URI open DICOMs from an XML manifest
-z --zip=URI open DICOM ZIP from an URI
-p --portable open DICOMs from configured directories at the same level of the executable
-i --iwado=DATA open DICOMs from an XML manifest (GZIP-Base64)
-? --help show help
dicom:close
g! dicom:close
Close DICOM files
Usage: dicom:close (-a | ([-y UID]... [-s UID]...))
-a --all close all the patients
-p --patient=ID close a patient from its patient ID (since v4.4.1)
-y --study=UID close a study, UID is Study Instance UID
-s --series=UID close a series, UID is Series Instance UID
-? --help show help
dicom:rs
g! dicom:rs
Load DICOM files from DICOMWeb API (QIDO/WADO-RS)
Usage: dicom:rs -u URL -r QUERYPARAMS... [-H HEADER]... [--query-header HEADER]... [--retrieve-header HEADER]... [--query-ext EXT] [--retrieve-ext EXT] [--accept-ext EXT]
-u --url=URL URL of the DICOMWeb service
-r --request=QUERYPARAMS Query params of the URL, see weasis-pacs-connector
-H --header=HEADER Pass custom header(s) to all the requests
--query-header=HEADER Pass custom header(s) to the query requests (QIDO)
--retrieve-header=HEADER Pass custom header(s) to the retrieve requests (WADO)
--query-ext=EXT Additionnal parameters for Query URL (QIDO)
--retrieve-ext=EXT Additionnal parameters for Retrieve URL (WADO)
--accept-ext=EXT Additionnal parameters for DICOM multipart/related Accept header of the retrieve URL (WADO). Default value is: transfer-syntax=*
--show-whole-study when downloading a series, show all the other series (ready for download) from the same study
-? --help show help
image:get
g! image:get
Load images remotely or locally
Usage: image:get ([-f file]... [-u url]...)
-f --file=FILE open an image from a file
-u --url=URL open an image from an URL
-? --help show help
image close
g! image:close
Close images
Usage: dicom:close (-a | ([-g UID]... [-s UID]...))
-a --all close all series
-g --group=UID close a group from its UID
-s --series=UID close an series/image from its UID
-? --help show help
weasis:info
g! weasis:info
Show information about Weasis
Usage: weasis:info (-v | -a)
-v --version show version
-a --all show weasis specifications
-? --help show help
weasis:ui
g! weasis:ui
Manage user interface
Usage: weasis:ui (-q | -v)
-q --quit shutdown Weasis
-v --visible set window on top
-? --help show help
acquire:patient
g! acquire:patient
Load Patient Context from the first argument
Usage: acquire:patient (-x | -i | -s | -u) arg
arg is an XML text in UTF8 or an url with the option '--url'
-x --xml open Patient Context from an XML data containing all DICOM Tags
-i --inbound open Patient Context from an XML data containing all DICOM Tags, decoding syntax is [Base64/GZip]
-s --iurlsafe open Patient Context from an XML data containing all DICOM Tags, decoding syntax is [Base64_URL_SAFE/GZip]
-u --url open Patient Context from an URL (XML file containing all DICOM TAGs)
-? --help show help
Depending the command line system, quotes or double quote needs to be escaped with a backslash. Ex. simple quote must be escaped in Eclipse but not in Intellij.
Weasis provides the tools to visualize and analyze images obtained from medical imaging equipment according to the DICOM standard. This free DICOM viewer is used by healthcare professionals, researchers and patients.
If you are new to Weasis, it is recommended to read this page to understand the main elements of the interface.
The tutorials are organized by topics and can be read independently.
If you find any errors or inaccuracies, just click the Edit button displayed on top right of each page, and make a pull request to submit your changes.
Subsections of Tutorials
GUI Overview
Essential aspects of the interface
The following image shows the main elements of the graphical user interface (GUI). For more detailed documentation on the various elements of the interface, click on the green or blue areas of the image.
The interface of the default DICOM workspace consists mainly of 2 parts:
The DICOM Explorer on the left (in blue). It allows you to import and export data, as well as select the series to be visualized.
Depending on the data imported, different viewer/player types (represented by a tab) are displayed in the main section (green). Menus , toolbars and tools change according to the type of viewer selected.
The selected viewer is the image above is the DICOM 2D viewer
which is the viewer opened by default.
A tab containing a multi-view layout can display images from only one patient. However, one patient can appear in several tabs.
A tab is also docked panel that can be arranged by dragging and dropping it to the desired location. This makes it possible to display 2 tabs side by side.
See also DICOM Explorer to understand how to navigate through the Patient/Study/Series/Image.
Note
Select your preferred language and regional settings in the preferences. Adapt the graphical interface to your needs by modifying the theme or the scaling factor for a better user experience on HiDPI screens.
Tip
In the View menu at the top, toolbars and tools related to the selected viewer can be shown or hidden. These display preferences are retained even after a restart. Only Explorer preferences are retained for the duration of the session.
List of other viewers/Players in the DICOM workspace
DICOM PDF viewer (default system application associated with pdf files). Same for other encapsulated documents.
DICOM Video player (default system player associated with mpg files)
List of other workspaces
Dicomizer
Explorer of standard images (based on the non-dicom-explorer.json configuration profile)
DICOM Import
How to import DICOM files
Weasis can open DICOM files from various ways and sources: drag and drop, local device, DICOM ZIP, DICOM CD/DVD, DICOM Query/Retrieve, and from commands locally or remotely.
Note
An popup error message is displayed when DICOM files cannot be read (from v4.3.0) or when a network error occurs. In the latter case a message asking to download again the missing files.
From the system file explorer
Drag and drop
Files or folders selected from the system file explorer can be opened by dragging and dropping into the central area of Weasis.
Empty central panel: Any files than ca be open by one of the viewers (e.g. standard images such as TIFF, PNG, JPEG…)
DICOM Explorer and DICOM viewers (SR, AU, MPR, 2D and 3D) in the central panel: Only DICOM files. Opens the default viewer according to the files.
File association
Dicom files can be opened by double-clicking them from the system file explorer.
Note
On Windows only the files with the extension “.dcm” are associated with Weasis. With other systems DICOM without extension are associated with Weasis.
From Weasis menu or toolbar
From the main menu, open File > Import > DICOM or from the first import button in the toolbar.
In order to import DICOM CD/DVD go the main menu, open File > Import > DICOM CD or from the second import button in the toolbar.
Local Device
Files and/or folders: list of selected items or unique path
Search recursively: when this option is activated the import takes into account the subdirectories
Open in new tab: behavior to automatically open the images of a patient when loading DICOM files
DICOM ZIP
Select: browse a DICOM zip file. When the archive file is encrypted, a password prompt is displayed.
Open in new tab: behavior to automatically open the images of a patient when loading DICOM files
DICOMDIR
It may be from a DICOM CD/DVD or a folder containing a DICOMDIR
Path: browse a folder containing a DICOMDIR
Detect CD-ROM: try to load a DICOM CD/DVD
Copy images into the local temporary directory: useful for slow reading device like CD-ROM
DICOM Query/Retrieve
On DICOM Source tab:
Archive: select the archive to query
With DICOM nodes: classic DIMSE C-Find with C-Move, C-Get or WADO-URI for retrieving DICOM files
With DICOMWeb nodes: QIDO and WADO-RS for retrieving DICOM files (no other options are required)
Retrieve (only with DICOM archive): the protocol to retrieve the images
C-MOVE: the classic DIMSE protocol (accepts all sop classes, not recommended for WEB)
C-GET: transfer syntaxes are negotiated by each sop classes according to a configuration file
WADO-URI: required a WADO server (C-Find + WADO retrieve)
Calling Node (only with DICOM archive): select the adapted calling DICOM node
More options: allows you to open the preferences to configure the DICOM nodes
On Search Criteria tab:
Select a pre-registered item (bottom right of the Search Criteria panel) or Fill the search criteria. Criteria can be saved and reuse later, since Version4.1.0 the item selected in the combo box is automatically applied the next time this window is opened (the default value is Empty).
Adjust the limit to the maximum number of exams in the response. Set the limit to 0 to avoid this constraint. For DICOMWeb the limit is the number of elements on a page, and you can go to the next page with the spinner buttons.
Click on Search
Select the exams you want to import
Start importing and close the window
Note
The progression of downloaded images for a series and the ability to pause the download of a series is only possible with DICOMWeb nodes and with the combination (DICOM C-FIND + WADO-URI).
Resuming the download of a series by clicking on the green play button or from the contextual menu.
Tip
When a query is too long, try to click on the Clear button in Search Criteria in order to cancel the request.
With a DICOMWeb node, a login from a web browser can be required (e.g. login to your Google account). If something goes wrong Weasis may freeze for at least 1 minute waiting for the authorization code.
This page explains how to configure a remote archive in DICOMWeb and then use this DICOMWeb node to retrieve exams remotely. However, it is also possible, without any prior configuration, to launch Weasis from a web context by passing it some parameters to retrieve images in DICOMWeb.
From the main menu, open File > Preferences (Alt + P) and select DICOM node list.
Currently, the DICOMWeb service of Orthanc doesn’t support the thumbnail service.
Create a new DICOMWeb node with the following URL (example with the demo server without authentication):
https://demo.orthanc-server.com/dicom-web
dcm4chee-arc-light
Kheops
DICOM Export
How to export DICOM files
Exporting the selected view
From the toolbar icon
or from the main menu File > Export > Exporting view export the selected view either to the clipboard or to image file (PNG, TIF, JPG, JPEG2000).
Current view
Export the view as it is (size and overlay).
Anonymize: It allows you to remove identifying information in overlay.
Original Image
Export the view according to the original image with some options.
Size: Change the image size in percent
Preserve 16-bit per channel: Option to preserve the pixel depth (e.g. 16-bit in PNG/JPEG 2000/TIFF, double values in TIFF). When this option is applied, the pixel values will match with the Modality LUT values (e.g. Hounsfield values). Exporting in JPEG Lossy is only possible when unchecked for 8-bit image.
In order to open the DICOM export window click on toolbar icon
or from the main menu File > Export > DICOM
Local Device
Select Local Device item
Choose the exporting options
Transcoding: It allows you to change the DICOM transfer syntax. Use this option only if you understand well what you are doing.
Generate new unique identifiers: Create new UIDs for some attributes. Within an export, the consistency between all the UIDs and their references is preserved.
Include DICOMDIR: Create DICOMDIR file
DICOM CD folders: Add a directory to be compliant with DICOM CD
Keep directory names: Preserve the name in the directory hierarchy (not compliant with DICOMDIR)
Select the patient/study/series/instance to export. Note: series created by Weasis have a flag “NEW”
Export the selection and close the Window
Tip
When opening the Export DICOM window, the checkbox of the study selected in the viewer (surrounded by an orange line) is automatically checked and open series have a full-line selection.
In order to help with series selection, place the cursor on a series line, and you’ll see a tooltip displaying its thumbnail.
Note
When DICOM data is exported in a native image format (JPG, PNG, JPEG 2000 or TIFF), only the images are transformed (see original image options) and the encapsulated files (video, audio and PDF) are extracted.
Multiframe images are exported by adding a number to the end of the file name.
DICOM Send
Select DICOM Send item
Select the destination node (either a DICOM node or a DICOMWeb node)
Select the patient/study/series/instance to export. Note: series created by Weasis have a flag “NEW”
Send the selection to the destination and close the Window
CD/DVD Image
Select the CD/DVD Image item
Choose the exporting options
Transcoding: It allows you to change the DICOM transfer syntax. Use this option only if you understand well what you are doing.
Generate new unique identifiers: Create new UIDs for some attributes. For an export, the consistency between UIDs and their references is preserved.
Add JPEG images allows extracting the images and the encapsulated files (video, audio and PDF) into a JPEG folder
Add Weasis allows embedding the viewer into the iso image. This option is only possible on Windows x86-64 (for exporting and running). Running the viewer directly on a CD/DVD ca be quite slow. To avoid that you can install the ISO on a USB stick or read the CD with a locally installed viewer as described in README.html.
Select the patient/study/series/instance to export
You can navigate through the Patient/Study/Series/Image structure using only keyboard shortcuts. For example:
Open an image and, if necessary, select the view to focus on. If the layout has more than one view, you can move across the views with Tab and Shift + Tab. The view surrounded by an orange line is the focused view.
Navigate through images within a series with Up and Down
Navigate through series within a study with Left and Right
Navigate through studies within a patient with Ctrl + Left and Ctrl + Right
Navigate through patients with Ctrl + Up and Ctrl + Down (follow the order in the patient’s combo box and select the last tab if a patient has several tabs already open). To navigate open tabs, use Ctrl + Tab and Ctrl + Shift + Tab.
Patient Level
Weasis allows multi-patient display. By default, when images are imported a tab with the patient’s name opens in the main area.
A tab containing a multi-view layout can only display images from a single patient.
Changing patients can be done either through the first combobox in the DICOM Explorer (see image above) or by selecting a tab in the main area.
In the combobox the patients are sorted in alphabetical order regardless of case and according to the regional setting.
Studies and Series are displayed within the same patient when the metadata Patient Name and Patient ID are the same. Otherwise, new patients are displayed.
Study Level
A study contains one or more series (thumbnails) belonging to a patient. A line representing the study surrounds its series (see image above).
By default, the studies are sorted by reverse chronology order (since Version4.1.0 “Study data sorting” can be changed in the menu “File > Preferences > DICOM > DICOM Explorer”). If there is no study date then the studies are sorted alphabetically according to the Study Description.
By default, all the studies are displayed, however you can choose to display only one of them from the study combobox.
Series Level
A series is represented by a thumbnail that contains a certain number of images (number displayed at the bottom left).
According to predefined rules, some series are separated into sub-series also represented by a thumbnail with a number preceded by ‘#’ in the upper right corner. Series splitting is necessary for the consistency of some tools such as the MPR, cross-lines and synchronization of series. However, sometimes separation is not desired, and sub-series can be re-merged using the context menu.
The sorting of the series is done by the serial number and if this last one is not present then in a chronological way by the date of the series or other dates.
To open new series:
Drag and drop a thumbnail in the main area (if the series is dropped in a view of the same patient then the series is replaced otherwise a new tab is created).
Double click or navigate with the up/down arrow key and press return on a selected thumbnail (if a view of the same patient exists then the series in the view surrounded by an orange line is replaced)
Select one or more thumbnails and choose an action from the “2D DICOM Viewer” context menu:
Open: Opens the series in the most appropriate layout (replaces the series if the patient’s tab already exists)
Open in new tab: Opens the series in the most appropriate layout in a new tab.
Open in screen: Opens the series in the most appropriate layout in a specific screen.
Add: Adds the series to the current patient’s layout if exists.
Preferences
From the main menu “File > Preferences > DICOM > DICOM Explorer”:
Thumbnail size: defines the width of the thumbnails and adjusts the panel accordingly (Default: 144). It is recommended to restart the application after this change.
Study data sorting: allows sorting the studies by chronological order or inversely chronological (Default: reverse chronology order). Since Version4.1.0.
Open in new tab: behavior to automatically open the images of a patient when using WADO or WADO-RS (Default: All the patients)
Download all series immediately: allows starting the download of the series immediately when using WADO or WADO-RS (Default: true). If unchecked then you must click on the play button on each series or globally at the bottom of the thumbnail list.
DICOM 2D Viewer
Displaying DICOM images
The 2D viewer is the default viewer when opening a DICOM series containing images.
Open the 2D viewer
The 2D view can be opened with
in the toolbar or by right-clicking on the thumbnail in the DICOM explorer.
The rulers K show a real size when it can be calculated from the DICOM file. When a text M above the calibration is displayed, it gives information about the calibration type. Here are some examples:
At detector: The calibration of the projection radiographic image is done at the detector level
Magnified: The calibration of the projection radiographic image is corrected using the magnification factor (e.g. mammography, see the image above)
Used fiducials: The calibration is based on fiducials (e.g. manual calibration with a ruler in the image)
At scanner: The calibration comes from a media which has been digitized (e.g. film digitizer)
Toolbars A
Viewer Main Bar
Select the preferred actions for the three mouse buttons and the mouse wheel:
Mouse left button: The default value is Window/Level. Action can also be changed from the context menu F and the key shortcuts.
Mouse right button: The default value is Context Menu
Mouse wheel: The default value is Series Scroll
Mouse middle button: The default value is Pan
Where the possible actions are:
Pan: Move the image position. T key to select the action. Alt + Arrows keys to pan when another action is selected.
Window/Level: Change the contrast of the image. W key to select the action.
Series Scroll: Scroll through the images of the current series. S key to select the action.
Zoom: Zoom in/out the image. Z key to select the action.
Rotation: Rotate the image with a free angle. R key to select the action.
Measure: Draw a graphic for measuring something. M key to select the action.
Draw: Draw a graphic for annotating. G key to select the action.
Context Menu: Display the context menu. Q key to select the action.
Crosshair: 3D cursor. H key to select the action. Ctrl + click or Ctrl + Shift + click allows changing Window/Level.
No Action: Do nothing. N key to select the action.
Tip
When dragging, accelerate the action by pressing the Ctrl key and Ctrl + Shift to accelerate more.
Default layout: Change the layout of the view. DICOM Information and Histogram are specific layouts where information is automatically updated when scrolling through the series.
Synchronize: The synchronization feature lets you apply the same settings to other images.
None: No synchronization is applied between series.
Default Stack: When selected, the layout is synchronized (window/level, scrolling, zoom) only with the series sharing the same Frame of Reference UID (0020,0052). This is the default behavior.
Default Tile: When selected, the layout is applied in tiled mode (image mosaic of the current series) and is synchronized (window/level, scrolling, zoom) with the image of the same series.
Reset: Reset the image rendering (see below). Escape key to select the action.
Toolbars can be shown or hidden from the View top menu.
Viewer’s tools
Here is a list of the tools which are associated to the DICOM 2D viewer.
The mini-tool is always visible and the other tools are displayed by clicking on the vertical button. The normalize button
allows you to insert the panel into the main layout. Otherwise, the panel is displayed as a popup window with the pin option
(which is not recommended, as it hides other panels).
Mini-tool B
Allows you by default to scroll through the images of the selected series (surrounded by an orange line). From the combobox at the top, the mini-tool can also be configured to change the zoom or the rotation of the image.
Display C
It lets you control the display of the image and the graphic objects.
The Apply to all views option allows you to apply the same display settings to all the views within the selected tab. If unchecked, the display settings are only applied to the selected view (surrounded by an orange line).
Image
Display options for the image. Unchecking the Image option will hide the image and display only the annotations and the graphic objects. The other options are related to DICOM specifications:
Display transformation properties and DICOM information on the image.
Annotations: Display DICOM information on the image corners:
G The top left: Patient information
H The top right: Study information
I The bottom right: Series information (related to the modality type)
J The bottom left: Image information and its position in the series
Minimal Annotations: Reduce the number of annotations. Use space or i key to toggle between the 3 states (minimal, none, all).
Anonymize: Hide identifying information only in the views not in other places of the GUI like the tab title. Must be used with the screenshot tool when exporting image.
Scale: Display the rulers on the left and the bottom of the image K
Allows you to zoom, rotate and flip the image. Zoom and rotation can also be configured with the mini-tool or the mouse actions.
Cine
The Cine start button
lets you scroll through the images in a series at a certain speed (frame per second). The speed values comes from the DICOM file if exists. The cine options can also be changed from the context menu.
Click on Cine stop button
to end the animation.
Click on Loop Sweep toggle button
to change the cine mode: looping vs sweeping.
Note
When the cine is active, the series which are synchronized are also animated. The cine is also applied to other series when they are selected until the Cine stop button is clicked.
When a series have a variable frame rate. The speed is changed automatically. So the speed value entered manually is not preserved.
Tip
A Cine toolbar is also available. It is not visible by default, but can be displayed from the View menu.
Reset
It allows you to return to the default image rendering for all or specific parameters. Also available from the toolbar button
or from the context menu.
From the menu “File > Preferences > Viewer > “2D Viewer”:
Mouse Action Sensitivity
The sensitivity of the mouse drag can be changed according to your preferences for the following actions: Window, Level, Zoom, Rotation and Series Scroll.
Zoom
Zoom interpolation is the process of creating new pixels between existing pixels in an image when it is zoomed in or out.
The Nearest neighbor interpolation is the simplest method. Basically, it extends the pixel value.
The Bilinear method averages the values of the four nearest existing pixels to the new pixel. This produces slightly sharper results than nearest-neighbor interpolation, but it is also slightly slower.
The Bicubic method is similar to bilinear interpolation, but it uses a 16-point kernel instead of a 4-point kernel. This produces even sharper results than bilinear interpolation, but it is also the slowest method.
The Lanczos method uses a sinc kernel to resample the image producing the sharpest results. It is moderately fast, between bilinear and bicubic.
The default value is Bilinear. The Nearest neighbor interpolation is faster but produces aliasing artifacts.
Other
Apply Window/Level on color images: When checked, the window/level is applied on the RGB channels of the image. Otherwise, the window/level has no effect when unchecked.
Inverse level direction: When checked, the level direction with mouse actions is inverted (dragging down will increase the brightness) according to the Basic Image Review profile. Otherwise, dragging down will decrease the brightness when unchecked.
Apply by default the most recent Presentation State: When checked, the most recent Presentation State Object is applied on the related image. Otherwise, it is required to select it from
.
Overlay color: change the color and the opacity of DICOM overlay. The default color is white. The opacity can be changed from the transparency or alpha slider of the different color models in the color picker.
MPR Viewer and 3D cursor
MPR Viewer and 3D cursor (crosshair)
Orthogonal multiplanar reconstruction (MPR)
The orthogonal multiplanar reconstruction (MPR) allows you to create, from the original plane (usually axial), images in the two other planes of the Euclidean space. Only planes along the 3 axes (x,y,z) can be displayed, an oblique plane cannot be obtained with this tool.
The MPR view inherits most of the DICOM 2D viewer properties. It can be opened with
in the toolbar or by right-clicking on the thumbnail in the DICOM explorer.
Note
The menu and the button are only active if the series contains at least 5 images.
When the tab containing the MPR views is selected, the crosshair tool
is automatically applied on the left mouse button. Note that it is possible to change the window/level with the ctrl key while keeping crosshair selected.
By default, zoom and window/level are synchronized between the 3 views. The MRR views can be displayed in different layouts
.
Tip
Once the 2 new plans are created, they also appear in the DICOM explorer and can be exported.
Try to load a volume dataset and open the MPR viewer.
Launch
Info
For more information on the elements related to the orientation of multiplanar views see MPR orientation.
3D cursor (crosshair)
The 3D cursor allows you to synchronize the position of several views sharing the same 3D coordinate system.
In order to know which series sharing the same coordinate system, you can select more than one series from the DICOM explorer by right-clicking on a series and selecting “Select related Series”. Then open the series selection by right-clicking again and selecting “2D Viewer > Open”
The crosshair tool
can be selected in the mouse buttons on the toolbar or by right-clicking on a view.
Try to load several series and select the 3D cursor.
Launch
Preferences
From the main menu “File > Preferences > Viewer > MPR” (Since Version4.1.0):
Auto center axes: Allows you to choose a behavior to recenter the cursor in the different views. The position can be returned to the center systematically with the “Always” option (see the image above) or with the 2nd option only when the position is almost no longer visible (the default value).
Crosshair gap at the center: Defines the size of the empty space in the center of the crosshair
Default layout: The preferred layout used when opening the MPR viewer
Info
The preferences apply to both the MPR and the 3D cursor.
MIP Viewer
Maximum Intensity Projection (MIP)
The MIP viewer is a simple 3D viewer that allows to display the maximum intensity projection of a volume defined by a number of slice of the image stack.
The MIP viewer is also available in the 3D viewer with more advanced options of the volume rendering, but some minimal hardware requirements is necessary.
Open the MIP viewer
The MIP viewer can be opened with
in the Basic 3D toolbar of the DICOM 2D viewer.
Note
If the button is grayed out, it means that the current series has less than 5 images which the minimal number of images for using the MIP viewer.
The MIP Options
This dialog is a modal window that allows you to change the MIP settings and build a new MIP series.
Try to load a volume dataset and open the MIP viewer.
Launch
Note
In MIP mode, the volume is displayed as a 2D projection of the maximum intensity along the perpendicular axis of the image plane. This change in geometry means that overlay graphics are no longer displayed.
Projection type
The projection type defines the way the MIP is calculated. The options are:
Min: Minimum Intensity Projection
Mean: Mean Intensity Projection
Max: Maximum Intensity Projection (the default value)
Windowing and Rendering
The Windowing and Rendering contains some of the tools found in Image Tools to change the windowing or to select a preset, since Version4.4.0.
Slice position
The slice position is used to move around the series to apply the projection and display the result. The Image value represents the position in the series stack.
Slice thickness
The Image Extension value represents the number of slices to use for the MIP calculation. If the images are calibrated and contains the 3D position, the thickness is also displayed in millimeters.
Rebuild Series
It allows you to build a new MIP series according to the MIP options. In this new series the slice position and thickness are modified. If the windowing is custom, then it is added to the presets of the new series.
Since Weasis Version4.1.0 the 3D viewer allows displaying volumetric renderings with different options for adjusting the pseudo colors, the transparency, the shadows and the lighting according to the type of exam.
The volume rendering uses a ray casting algorithm and the OpenGL Shading Language (GLSL). Shader programming is used to create the necessary algorithms and data structures
required for the ray casting computations to be executed efficiently on the graphics card. Therefore, minimal graphic resources are required.
Requirements
Some requirements related to the specifications of your graphic card are mandatory. They can be displayed in “OpenGL Support” from the menu “File > Preferences > Viewer > 3D Viewer”:
Driver version: The OpenGL version must be at least 4.3 to support the Compute Shader (not supported currently on macOS)
Max 3D texture dimension length: The limit of any dimension (X,Y,Z) of the volume data
If you have other information in red, it means that the configuration is not optimal but in most cases can work (see how to limit the size of 3D textures)
Note
If the graphic card displayed in Weasis is not the right one, you must solve this problem on the side of the graphic drivers or the operating system.
OpenGL does not include specific functionality for selecting a particular graphics card. Instead, this is handled by the graphics card driver and operating system, which provide a way for users to configure which graphics card should be used by an application.
Open the 3D viewer
The 3D view can be opened with
in the toolbar or by right-clicking on the thumbnail in the DICOM explorer.
Try to load a volume dataset (Medical Demos from data.kitware.com)
Launch
Toolbar A
Actions in the toolbar are:
Allows you to fully reload the volume
The orthographic projection maintains parallel lines unlike the perspective projection that provides a perception of depth. The default mode is the perspective projection.
This tab contains all the tools to modify the volume rendering. If you want to return to the original settings, just click on the toolbar button
or from the context menu.
Windowing and Rendering B
Some of the options described below are also available in the toolbar and in the contextual menus.
Window: The width of a range of voxels values mapped to a specific range of display values.
Level: The center of the range defined by Window.
Preset: Specific values of Window and level. Auto Level [Image] is the default value when changing a LUT and provides the best visual appearance of a Volume LUT.
LUT Shape: The mapping (transfer function) between the input values and the display values can be linear, sigmoid and logarithmic. Default value is linear.
LUT (Volume LUT): A Volume Lookup Table (LUT) is a 3D LUT used to map the grayscale values of a volume dataset to color, opacity and lighting values for visualization. Choosing a LUT from the toolbar or the contextual menu is easier because the LUTs are displayed in an order according to the modality and with a preview.
allows you to invert the LUT.
Volume Rendering C
This panel contains options for the rendering type and its quality, transparency, lighting, and shading settings.
Type: Composite is the classic type of volume rendering. The Maximum Intensity Projection (MIP) is the highest intensity voxels (3D pixels) along a ray path are projected onto a 2D plane. Iso surface is a technique to create a 3D representation on a specific intensity threshold.
Z-axis sampling: The sampling should be large enough to accurately capture the details of the volume data, but small enough to avoid excessive computation time. The default value is calculated according to the size of the volume.
Opacity: The opacity factor of the voxels. Can be set to more than 100% to modify initial values (lower than 100%) transmitted by the Volume LUTs.
Shading: Allows to activate the shading. Default value is defined in LUT. The additional options allow you to override the default lighting settings (comes from Volume LUT).
Transform D
Allows you to zoom and rotate along a specific axis
Preferences
From the menu “File > Preferences > Viewer > 3D Viewer”:
OpenGL Support
Information about the graphics card and OpenGL capabilities, see Requirements.
3D Viewer
Default layout: The preferred layout used when opening the 3D viewer
Max 3D texture size: The maximum size of the volume according to X/Y (width and height of images) and according to Z (number of images in the stack composing the volume)
Note
The maximum values of the default 3D textures come from the graphics card. However, it may be wise to decrease these values (e.g. 512) in order to allow a more efficient display of volumetric renderings for which the hardware resources are not sufficient.
Volume Rendering
Dynamic quality: Allows you to make the render more fluid by reducing its quality (according to the z-axis) when it is rotating or being modified. When the slider is at maximum then there is no more quality reduction.
Default orientation: The preferred orientation used when opening a volume rendering view. Default is Anterior position by turning 15 degrees to the right and 15 degrees downwards.
Background color: Defines the background color of the rendering
Light color: Defines the color of the light during the illumination of the rendering
Video tutorials
Display an MR scan with an angiography-specific protocol by creating a volume rendering. Then either use the MIP type or choose a 3D LUT and adjust the win/level values.
DICOM ECG Viewer
Displaying electrocardiography data
The ECG viewer is used to display and analyze electrocardiogram (ECG) data in DICOM format obtained from different modalities, such as resting ECGs, ambulatory ECGs, and stress tests.
The viewer can also provide tools for measuring ECG intervals and amplitudes in various formats, such as 12-lead ECGs, 3-lead ECGs, and rhythm strips.
Allows you to print the ECG as it is displayed with some basic information (patient/study)
Show the DICOM metadata of the ECG
Delete all the measurements (yellow areas in the image above), see Markers
Zoom and Display Format B
The zoom is on several graphic components. The first combo box represents the time, the second represents the voltage, and the slider allows you to zoom in both directions while preserving the aspect ratio.
Time (X-axis): The number of millimeters per second (by default is “auto mm/s”)
Voltage (Y-axis): The number of millimeters per milli-volt (by default is “auto mm/mV”)
The Display Format allows you to show the leads in different layouts.
Lead and Cursor information C
Moving the cursor over the ECG displays the following information:
Lead label: show the minimum and maximum voltage values of a lead
Cursor: show the current time and voltage values under the cursor
Markers D
The markers are the result of the measurements made on the ECG (yellow areas in the image above). A measurement is done by defining a starting and ending point:
Start Time: The time in seconds according to the position of the first point
Start Value: The voltage in milli-volt according to the position of the first point
Stop Time: The time in seconds according to the position of the second point
Stop Value: The voltage in milli-volt according to the position of the second point
Duration: The time elapsed between the 2 points
Difference: The difference in milli-volt between the start value and the end value
Amplitude: The maximum variation in milli-volts from the start value to the end value
The actions for making measurements are:
Action to add a starting point: click
Action to add an ending point: ctrl+click or right-click
Deleting the measurement in a lead can be done by a middle-click or shift+click. Deleting all bars can be done with the button in the toolbar.
Note
Only one measurement is possible by lead.
Annotations E
The annotations come from 2 groups of DICOM metadata:
Acquisition context and Annotations: Attributes which describes the conditions present during data acquisition.
Annotations: may represent a measurement or categorization based on the waveform data, identification of regions of interest or particular features of the waveform, or events during the data collection that may affect diagnostic interpretation (e.g., the time at which the subject coughed).
DICOM SR Viewer
Displaying DICOM Structured Report
The DICOM Structured Report (SR) viewer is used to display and analyze DICOM SR data. The SR object is a structured collection of content items that represent a report of a diagnostic or therapeutic procedure. The content items are organized in a tree structure, and each item has a relationship with other items.
The viewer displays the content of the SR object in a structured way, allowing the user to navigate through the tree and visualize the content of each item.
The header of the SR object is displayed in a table format with 3 columns containing information about the patient, the study, and the report status.
DICOM SR Tree C
The content of the SR object is displayed in a tree structure. Each node in the tree represents a content item with hierarchical numbering, and the tree structure reflects the relationships between the items.
Some items can have a link to other content items, and the viewer provides a way to navigate through the tree by clicking on the links.
This link can also open a related image which can contain measurements defined in the SR object (e.g. in the image above, clicking on POLYLINE will open the image and display the polyline).
DICOM Audio Player
Playing DICOM AU data
This player is used to play audio data defined by the DICOM AU standard.
For standard images, in an XML File in the same directory of the image (when exporting the images in non dicom file format). The XML file is automatically loaded when the image is displayed in the standard 2D Viewer.
Draw & Measure Panel
When clicking on
of the vertical button
, the panel is displayed on the right side of the viewer. This panel is divided into 4 parts.
Measurement tools A
Select a measurement tool by clicking on one of the buttons and then draw on the image. Note that the previous action will select automatically the drawing action in the mouse left button.
The first button is the selection tool that allows you to select, resize and move the graphic objects.
By selecting one or several graphic objects, you can change properties (e.g. color, line width) or copy/paste with the contextual menu. You can also delete the selection with the delete key or
. See other shortcuts for graphics.
Note
There are two ways to draw a segment:
Click + drag > release
Click > release > drag > release
In order to continue drawing with the same tool, you can uncheck the Draw only once option (see below).
Tip
For a polyline or polygon, double-click to complete editing. You can also delete a point or add new ones by right-clicking on a specific point.
Rectangles and ellipses can be drawn in any direction. External control points can be used to rotate and resize the shape. With the single control point on the opposite side, you can only resize the shape.
Drawings B
The drawing buttons allow you to add text and graphic as annotations. These graphics objects do not display measurement values and do not appear in Selected MeasurementD.
Graphic Options C
Line color: The default line color when drawing new graphic object. The default value is yellow. The opacity can be changed from the transparency or alpha slider of the different color models in the color picker.
Line width: The default line width.
Draw only once: After drawing a graphic object, the tool is automatically set to the selection mode. If unchecked, the tool remains active for drawing a new graphic.
Pixel statistics: Show statistics of the pixel values within the shape. Only for graphic objects with a closed shape (e.g. rectangle, ellipse, polygon).
More options: The preferences to change more display options (see preferences).
Tip
Show/hide all the graphic objects from the Display panel by checking/unchecking the Drawings option.
Selected Measurement D
The selected graphic E created with a measurement tool is displayed in the table. The table shows the shape properties according to the measurement type (and its units in square brackets if exists).
Note
For polygon, the length, the width and the orientation are calculated with OMBB (Offset Minimum Bounding Box) method which provides a more accurate approximation of the actual length and width based on the bounding box of the polygon.
When Pixel statistics is checked, some statistics are displayed in the table only for graphics with a closed shape (e.g. rectangle, ellipse, polygon). The statistics are calculated from the pixels inside the graphic shape:
Pixels: The number of pixels inside the graphic shape
Min: The minimum modality value
Max: The maximum modality value
Median: The median modality value
Mean: The mean modality value
StDev: The standard deviation is a measure of the dispersion of the values
Skewness: The skewness is a measure of the asymmetry of value distribution
Kurtosis: The kurtosis is a measure of the “tailedness” of value distribution
Note
SUV (Standardized Uptake Value) measurements are added to the table only for PET images containing the required metadata (patient weight,Decay Correction, radio pharmaceutical dose and time…). The SUVs (the minimum, maximum, and average values) are calculated using the body weight (SUVbw) vendor-neutral method.
Tip
The table can be exported by copy/paste. Note that the maximum precision values are copied and not the rounded values displayed in the table.
Preferences
From the menu “File > Preferences > Draw & Measure”:
Drawings
It lets you change the graphic properties when drawing new graphics, since Version4.3.0.
Line color: The default line color. The default value is yellow. The opacity can be changed from the transparency or alpha slider of the different color models in the color picker.
Line width: The default line width.
Fill shape: When checked, the shape is filled with the line color.
Fill opacity: The opacity of the interior of the shape, relative to the opacity of the line color. The default value is 100%. For example, if the line color has an opacity of 80% and the fill opacity is 20%, then the perceived opacity will be 16% (0.8 * 0.2).
Labels on image
It lets you change the display options for labels attached to measurement graphics.
Font type: The default font size of the labels on the image. The default value is Small semibold. Note that the font size is not absolute and is automatically adjusted according to the scale factor.
Geometric measurement: the measurement types displayed on the image according the graphic type.
Pixel statistics: the statistics types displayed on the image for graphic objects with a closed shape (e.g. rectangle, ellipse, polygon).
DICOM RT Tools
Displaying radiotherapy information
The RT Tool appears on the right panel when a CT exam (when linked with DICOM STRUCT, PLAN and DOSE) is displayed. Since Version4.1.0 a specific configuration in config.properties is no longer required.
How to display structure and iso-dose
In order to display the structures in overlay on the image, apply the following points (see in the image below):
InfoOptional When selected, it allows you to force the DVH calculations. Otherwise, it is calculated only if some information is not available in the DICOM files.
Click on “Load RT” button to load DICOM STRUCT, PLAN and DOSE associated the CT images. Once loaded, the button becomes inactive.
InfoOptional Select a structure if there is more than one.
InfoOptional Select a plan if there is more than one.
For displaying the iso-doses, apply the following points (see in the image below):
Select the Isodoses tab
Check the Isodoses root node which is not activated by default
InfoOptional Adjust the graphic opacity
Tip
The “Structures” and “Isodoses” root node can be used to show or hide all graphics while the child nodes can be used independently for showing specific items.
How to display DVH
Select one or several structures. Note: the Structures root node must be selected.
Click on the button “Display DVH chart”
Right-click on the chart to print or save as a PNG image or vector files such as SVG or EPS.
DICOM Attributes
How to display DICOM attributes
The DICOM attributes
can be displayed either by:
selecting the “Dicom Information” layout from the layout dropdown button A
clicking on the “Dicom Information” button in the toolbar to open a detached window B
Note
Using the view in the layout (A) allows updating dynamically the DICOM attributes to the current image (e.g. scrolling into the series). The DICOM attributes won’t change when opening the detached window (B).
When Weasis opens particular DICOM files (e.g. PDF and video) with an external viewer, the DICOM attributes can be viewed from the thumbnail context menu (see image below).
How to find a specific DICOM attribute or value
The Dicom Information window contains two tabs:
Limited DICOM attributes: List of the main attributes assembled in several groups.
All DICOM attributes: List of all the attributes where each data element is displayed within four columns (Tag ID, VR, Tag Name and Value)
Note
When the data element contains several values, each value is separated by ‘\’.
Data element with a value representation (VR) OB, OD, OL, OF, OW and UN shows “binary data” as value.
In the image above, we are looking for the word “date”. Here are the steps:
Select All DICOM attributes tab for having all the attributes.
Enter the word you are looking for.
Use the arrows to navigate into the highlighted results. The button on the far right allows you to limit the results to positive ones.
The navigation shows the current result in highlight mode.
Using in the toolbar allows you to filter the results. This can be useful to keep the focus on certain elements when scrolling through a stack of images (only possible with layout A).
Note
Some attributes can be into a sequence element (5). Note: the left arrow shows the depth level as a sequence can contain another sequence.
Tip
If there isn’t enough space to display the entire value, simply resize the column from the header (only persistent if the image doesn’t change) or use tooltips by positioning the cursor over the elements (since v4.3.0).
Tip
The DICOM attributes can be copied into the clipboard with the copy shortcut of your system.
Lookup Tables (LUT)
How to handle Color and DICOM LUTs
A DICOM file can contain one or more LUTs. The DICOM pipeline for rendering images contains a number of stages where the LUTs are applied. There are 4 types of Lookup Tables (LUTs) in DICOM:
The Modality LUT is used to transform the pixel values into the values of the modality (e.g. Hounsfield for CT).
The Values of Interest (VOI) LUT is used to transform the modality values into a visible range that enhances specific anatomical structures or pathological conditions.
The Presentation LUT is used to transform the intensity values into P-Values (presentation values are device-independent values related to human perception).
The Palette Color LUT is used to transform the intensity gray values into color values with a pseudo color LUT.
Note
The Modality LUT and the Palette Color LUT are applied automatically when they exist. There are no options in the User Interface to modify them.
Windowing and Rendering
The Windowing and Rendering is a panel in the Image Tools of the DICOM 2D viewer. Some of the options described below are also available in the Lookup Table toolbar, in the main menu and in contextual menus.
Window: The range of pixel intensity values. The value can be changed when Window/Level is selected in mouse actions or by using the slider.
Level: The center of the range defined by Window. The value can be changed when Window/Level is selected in mouse actions or by using the slider.
Preset: The possible items ordered according to the following list:
Empty item when the Window and level values are changed manually from slider or mouse actions.
Window and level values or VOI LUT data from the DICOM file (ending with [DICOM]). The default value is the first [DICOM] item if exists, otherwise Auto Level [Image].
Auto Level [Image] (always visible) which is the Window and level related to the full range of the pixel values
Specific values of Window and level for a modality type (e.g. Lung for CT)
LUT Shape: The mapping (transfer function) between the input values and the display values can be linear, sigmoid and logarithmic. Default value is linear.
LUT: A pseudo color LUT used to map the grayscale values to color. Default (image) is the original image color model. Choosing a LUT from the toolbar or the menus is easier because the LUTs are displayed with a preview.
allows you to invert the LUT.
Filter: The 2D filter is applied to the image before the LUT. The filter can be used to enhance the image quality or to highlight specific structures. The default value is None.
Tip
In order to display the LUT on the image, select it from the Display panel on the right. The LUT color are associated to values that correspond to the Modality LUT values (e.g. Hounsfield values for CT) or to the pixel values for some imaging types.
Another way to see the windowing transformation is to display the histogram.
Build DICOM KO and PR
How to build and export DICOM KO and PR
Key Object Selection (KO)
In order to display KO Toolbar, select in the main menu: View > Toolbars > Key Object Selection Toolbar
When a DICOM KO is loaded then it appears in the explorer menu (1) or it can be selected from the icon on the right of the view (6).
Click on the star icon (3) to add the key image or press ‘k’ to create in a new KO.
Other actions:
Apply a KO (2)
Filter to obtain only the key images defined in the selected KO (4). This means only key images will be visible when scrolling into a series.
Create a new KO (or based on another one) or delete KO (only the ones created by Weasis) (5)
Presentation State (PR or GSPS)
Apply PR loaded from a DICOM file (1)
: Since Version2.6.0 PRs are not applied to the image by default (requires to select the right icon (2) over the image). In order to apply the most recent PR by default, change it from the main menu File > Preferences (Alt + P) and check “Apply by default the most recent Presentation State”, or in the default preferences.
Create a new PR: Any type of annotations (Drawings and Measurements) can be exported in a DICOM Presentation State. Image presentation actions (zoom, calibration, W/L, LUT…) are not yet possible to export into PR.
Exporting Key Object Selection or Presentation State
In order to export KO or PR, select the DICOM Export icon or from the main menu File > Export > DICOM
Select the export type (locally or remotely)
Choose the exporting options (series created by Weasis have the flag “NEW”)
Select the patient/study/series/instance to export
Export the selection and close the Window
DICOM SEG
Displaying DICOM Segmentation
Since Weasis Version4.3.0, this panel lets you display the contents of a DICOM SEG file superimposed on the image. It also lets you modify the transparency of specific regions (label defined by a color).
DICOM SEG can be generated by AI frameworks to represent the results of segmentation algorithms applied to medical images.
How to display DICOM SEG
In order to display the DICOM SEG regions in overlay on the image, follow these steps (see in the image below):
Open the DICOM series with a link to a DICOM SEG object. This link is visible by the segmentation icon
in the lower right-hand corner of the thumbnail.
Once the image is displayed, you can click on
of the vertical button
to show the Segmentation panel on the right side of the viewer.
A DICOM SEG file is represented by a selected item in the combo box and its list of regions below. By default, all DICOM SEG files linked to an image are displayed.
Select one or several regions to display for the selected DICOM SEG (3). Several regions are grouped together when they share the same first name. Note: the parent node must be selected to display the child regions.
Adjust global graphic opacity (border and interior)
The regions tree has context menus that allow you to:
Fill opacity (all nodes): The opacity of the interior of the shape, relative to the opacity of the line color (Graphic Opacity). The default value is 20%. For example, if the line color has an opacity of 80% and the fill opacity is 20%, then the perceived opacity will be 16% (0.8 * 0.2).
Select/Unselect all the child nodes (only for parent nodes)
Show ih the images view (only for leaf nodes): The region with the highest surface area is displayed in the image overview.
Pixel statistics from the selected view (only for leaf nodes): Show statistics of the pixel values within the region shape. For the definition of the statistics parameters, see graphic Pixel Statistics.
Tip
The regions tree has tooltips on leaf elements that show the region description and the region volume.
AI DICOM Objects
DICOM objects generated by artificial intelligence
Artificial intelligence (AI) frameworks can produce various DICOM objects for different purposes. Here are some common DICOM object types produced by AI frameworks and how they are handled in Weasis (see Info window).
DICOM Secondary Capture (SC)
This type of object represents secondary images where the AI has embedded information in the image pixels. These images may include annotations, measurements, or other enhancements to the original image data.
Info
DICOM Secondary Capture can be displayed by Weasis like any other image data, see DICOM 2D Viewer.
DICOM Segmentation (SEG)
These objects represent the results of segmentation algorithms applied to medical images. Segmentation involves partitioning an image into multiple segments to simplify its representation for analysis or display. AI frameworks can produce SEG objects containing segmentations of anatomical structures, lesions, or other regions of interest.
Info
See DICOM SEG for displaying DICOM SEG objects in Weasis.
DICOM RTSTRUCT
This type of DICOM object is originally used to represent structures delineated on CT images for radiotherapy treatment planning. Some AI frameworks may produce DICOM RTSTRUCT objects (geometric shapes) instead of DICOM Segmentation (pixel-based).
Info
See DICOM RT for displaying DICOM RTSTRUCT objects in Weasis.
TotalSegmentator automatically segments over a hundred anatomical zones on CT images.
When the result is saved in DICOM RTSTRUCT (since version 2), the segmentation result can be displayed directly in Weasis:
DICOM Structured Report (SR)
AI frameworks can generate structured report containing the results of their analysis. These reports typically include structured information about findings, measurements, observations, and interpretations derived from medical images or other data.
AI frameworks may produce DICOM objects containing encapsulated documents such as PDF reports, text documents, or other non-image data related to medical imaging studies.
Info
This type of object can be displayed by the default system application associated with the document mime type. The DICOM attributes can be viewed from the thumbnail context menu (see image below).
DICOM Presentation States
Presentation states define how images should be displayed, including display parameters such as window width, window center, and image orientation. A Grayscale Softcopy Presentation State (GSPS) object is used to display annotations and graphics that overlay on a displayed image. AI frameworks might generate presentation states to specify how images should be displayed based on their analysis results or to display graphics overlays on images.
Info
See DICOM PR for displaying DICOM Presentation States in Weasis.
DICOM Enhanced Objects
Enhanced DICOM objects contain additional information. AI frameworks might produce enhanced DICOM objects to include additional annotations or other enhancements to the image data.
Info
DICOM Enhanced (e.g. reduce noise or improve visualization of anatomical structures) can be displayed by Weasis like any other image data. Some other additional information (overlay, shutter and pixel padding) can be added to the image rendering, see 2D Viewer Display.
Zoom
Zoom tool
The zoom tool can be associated with one of three mouse actions . In the image below the zoom tool
is associated with the middle mouse button. See also zoom preferences.
The zoom factor can be modified from different locations:
By dragging the cursor over the image with the configured mouse button
By scrolling the mouse wheel when configured
By selecting an item in the zoom dropdown button in the toolbar
From the context menu: right-click on the image > Zoom
Form the slider in the image tool panel
Using Keyboard Shortcuts (Ctrl + Plus (+), Ctrl + Minus (-) and Ctrl + Enter) on the selected view
The context menu and the toolbar button allows you to select different zoom factor:
Actual pixel size
: display the image at a 1:1 ratio, where each pixel in the image corresponds to one pixel on the screen
Resize to best fit
: scaling the image to make it fit the view area as closely as possible
Note
The zoom function always zooms in/out to the center of the screen regardless of where the cursor is. This mode provides greater positional accuracy in particular situations.
Since “Resize to best fit” is the default mode for a view, the image will be centered when scrolling to the next image. You need to change the mode or the zoom factor to keep the image off center when scrolling.
Tip
For selecting directly the zoom action of the mouse left button, enter “z” as a shortcut.
Real-world zoom
The real-world zoom allows displaying the content of the image at the same size of the real objects.
The feature requires calibrating the screen where the image is displayed. From the main menu, open File > Preferences (Alt + P) > Monitors and click on Spatial calibration. Then enter a value that matches to the line length or the diagonal length of the screen.
Note
Several screens can be calibrated. Each one has its own spatial calibration factor.
Magnifying lens
The magnifying lens can be activated from the toggle button of the zoom toolbar (see the image below). It has several parameters accessible from the context menu.
This lens can be used in many situations, for instance:
to magnify a specific area
to compare two images from the same series (select Freeze image)
to display a specific area without the drawings (Unselect Show Drawings)
to compare different values of Window/Level (select Freeze parameters - see image below)
Note
Using the mouse wheel on the lens changes the zoom factor. Double-clicking on the lens adjusts the zoom factor of the lens to the one of the main image.
Parameters of the context menu:
Synchronize to parent zoom: When this option is activated, the zoom factor of the lens is permanently adjusted to the zoom factor of the main image (meaningful when using freeze parameters).
Show Drawings: Displays in the lens the visible drawings.
Magnify: Allows to select a zoom magnitude.
Image:Freeze parameters allows you to keep the current image processing (c.f. Window/level, LUT or filter) and Freeze image allows you to keep the current image and its parameters.
Histogram
Displaying Histogram
Displaying the histogram allows you to view the distribution of the modality values.
Note
Displaying the histogram allow you to better understand the effect on the pixel distribution wen changing all the LUT parameters from the Image Tool right panel.
To open the histogram, select the “Histogram” layout from the Layouts dropdown button (see the image below).
General histogram parameters:
Channel: With gray images only the Luminance channel is available. With color images, you can choose one of the following color models: RGB, HSV and HLS.
Bins: The bins are the intervals values of pixels. By default, this number is calculated by the max value minus the min value and cannot exceed 512. The value entered must be between 64 and 4096.
Statistics: Show the statistics of the histogram which allow you to analyze and to compare images or image regions in a quantitative way. For the definition of the statistics parameters, see graphic Pixel Statistics.
Note
The values on the x-axis represent the modality values (e.g. Hounsfield for CT) or the pixel values for some imaging types. If the unit of the pixel value of the modality exists, it is visible at the end of the histogram title.
Display histogram parameters:
-/+: shrink/strech the y-axis scale (the number of occurrences)
Accumulate: Display a cumulative histogram
Logarithmic: Show the number of occurrences in a logarithmic scale (y-axis).
Show intensity color: Show the bin with the LUT colors, otherwise in black.
Reset: Set the default parameters
Note
It is possible to display the histogram of a region with the measurement tools. Simply select the region to display its histogram (see the image below).
Tip
Clicking on the histogram bin allows displaying the number of occurrences and the modality range values of the selected bin.
Print
Build the image selection to print
The image selection to print must be prepared before calling the print function. If you need to print more than one image per page, choose a layout from the dropdown button in the toolbar (1).
Note
The layout list is built dynamically according to the window size. So changing the window size ratio will provide other layouts. For instance, with a panoramic screen, you can choose a horizontal layout and then print with a landscape orientation.
To fill the layout with images you can change the synchronized mode of series (2):
with Default Tile selected, all the views will be filled with the same series. Each view has a new image of the series stack (n + 1).
with Default Stack selected, drag and drop a series into each view and select independently which image you want to display.
Select a print mode
Standard Printer
From the main menu, open File > Print > Print 2D viewer layout (P).
The meaning of the standard print parameters:
Image position: the position of the image in the print area.
Image DPI: the print resolution in dot per inch (Default value is 150). Higher DPI means higher resolution.
Print image with annotations: Allows to print the annotations defined in the Display panel.
Print only the selected view: When this option is checked, only the selected view is printed (view with an orange border). Otherwise, all the views of the layout are printed.
DICOM Print
From the main menu, open File > Print > DICOM Print.
In the DICOM Print dialog, you can manage several configurations. For the options meaning, you can refer to the above parameters and the DICOM print pages.
Note
The DICOM printer configurations can be distributed at the server side for all the clients, see preferences.
Image orientation
Interpretation of the orientation
The orientation of the DICOM images is displayed by one or more uppercase letters in the middle on the top and left of the view.
If Anatomical Orientation Type (0010,2210)attribute is absent or has a value of BIPED, anatomical direction is:
A: anterior
P: posterior
R: right
L: left
H: head
F: foot
If Anatomical Orientation Type (0010,2210)attribute has a value of QUADRUPED (since Version4.1.0), anatomical direction is designated by:
LE: Left
RT: Right
D: Dorsal
V: Ventral
CR: Cranial
CD: Caudal
R: Rostral
M: Medial
L: Lateral
PR: Proximal
DI: Distal
PA: Palmar
PL: Plantar
Info
If the orientation is not perfectly aligned according to the 3 axes of the referential then there can be a secondary and tertiary orientation (in subscript) separated by “-”.
Info
For some modalities such as CR or DX, the orientation comes from the Patient Orientation (0020,0020) attribute and is not displayed when using the rotation tools because it cannot be recalculated dynamically.
For other modalities such as CT and MRI, the orientation is always displayed because it is dynamically calculated.
Tip
To display or hide the orientation on the image, select it from the Display panel on the right (DICOM Annotations > Orientation).
Orientation in 2D multiplanar reconstruction (MPR)
The image below shows the 3 views of the orthogonal MPR. The uppercase letter at the left or at the top designates the orientation of each multiplanar view whose type (axial, coronal, sagittal) is defined at the bottom.
Info
The color of the axes used comes from the one defined in DICOM Patient Orientation based on the anatomical direction. Blue corresponds to the left-right axis, the red axis to anterior-posterior, and the green axis to foot-head.
The colored square in the MPR view above corresponds to the plane that is perpendicular to one of the axes.
Third-party Launcher
Third-party application launchers allow you to run another application by transmitting information to it in the startup parameters.
In the graphical user interface, launchers appear in the File > Launcher menu and optionally in the toolbar.
In the example above, we add a button to launch the Horos software on the Mac, importing the directory containing the DICOM files downloaded by Weasis.
How to create the third-party launcher
From the main menu, open File > Preferences (Alt + P) and select the Launcher item.
Click on the Add New button to create a new DICOM launcher.
In DICOM launcher dialog, fill in the fields:
Name: the name of the launcher
Icon path: the icon to display in the menu and toolbar. The path can be absolute or relative to the Weasis resources folder. When the icon is not found, the default icon is displayed.
Enable: to display the launcher in the menu and toolbar
Button: to display the launcher in the toolbar
In DICOM Launcher dialog, click on Configure to specify the launch context.
In Launcher Type, select the launcher type:
URI: add a URI to open a web page or a file. The URI can contain dynamic variables described below.
Application: run an application with parameters. The application Parameters and Environment Variables can contain dynamic variables described below.
Binary Path: the command to run the application.
Working Directory: the working directory of the application (optional).
Parameters: the parameters to pass to the application. Each line is a parameter.
Environment Variables: the environment variables to pass to the application. Each line is an environment variable.
Compatibility: the compatibility of the launcher with the current platform. This feature is useful when the launcher configuration is coming from the server side.
In Launcher Type, click on Save to save the launcher parameters.
In DICOM Launcher, click on Save to save the launcher general information.
List of dynamic variables in URI, Parameters and Environment Variables:
{dicom:wado.folder} the temporary folder for images downloaded from the WADO and DICOMWeb protocols.
{dicom:last.folder} the last open folder of Local Device in Import DICOM.
{dicom:selection.folder} it will display a selection dialog (such as Export DICOM) and copy the result to this folder, which will be deleted when Weasis is closed.
{tag::<key>} any DICOM attribute value from the selected image, e.g. {tag:AccessionNumber}
{pref:<key>} any preferences, e.g. {pref:weasis.user}.
Note
The Other Launcher is a special launcher that allows you to display a button on any viewers. For this type, only {pref:<key>} can be used as a dynamic variable.
How to run the third-party launcher
From the main menu, open File > Launcher and select the desired launcher
From the toolbar click on the launcher button
Note
The launcher must be enabled in the preferences to be displayed in the menu and toolbar.
Spatial Calibration
How to change the spatial calibration
When the image does not contain a default spatial calibration and it contains a ruler (or other element allowing to determine a known distance) then you can apply a calibration manually:
Select a line in the Measurement Tool
Draw a line on an object with a known distance
Right-click on the selected line and enter the distance on the Manual Calibration window
Note
The calibration can be applied only to the current image or to all the images belonging to the series.
Info
Once calibrated, all measuring tools will produce results according to the calibration and the real-world zoom will display the images at the same size of the real objects. Currently, the calibration is not saved in the DICOM file.
Changing spacial calibration with Weasis 1.1.3
Styles and themes
Change the appearance of the user interface
How to apply another theme
From the main menu, open File > Preferences (Alt + P) and select the desired theme and click on “show” to see a partial preview (1).
How to scale the user interface
It is recommended to adapt the scale factor to the one of the system (2). In this way, Weasis will scale on HiDPI displays as the operating system. On Windows it is the Display Scaling preference and on Linux it is either the display scaling factor or the text scaling factor.
However, the scaling factor can be increased (or even decreased) independently of the system. That means all the elements of the graphical interface will be adapted (fonts, icons, graphic components…).
Note
The last option (3) allows you to force the integration of the main menu in the window bar (not activated by default). This option appears only on Linux because there is a wide variety of window managers.
On Windows and Mac this option does not appear because it is always supported.
From the main menu, open File > Preferences (Alt + P) and select the desired language and the regional format. The languages available in the list can be partially translated. In this case you can participate in the translation directly from a web portal.
Note
Anywhere in the user interface, date and number should be displayed with the selected regional format.
Changing the default locale settings
If you need to change the default settings, please see the preferences.
Logging
Configure and view log files
The log folder that can be opened from the menu “Help > Open the logging folder” (since Version4.1.0) contains two types of log:
A boot log file (boot.log) is always written since Version3.5.0
Rolling log files (default.log) that need to be activated in the preferences dialog (see below How to configure the rolling log files)
Tip
In order to determine the path of <user.home>/.weasis/log for versions prior to v4.1.0, go to the “Help > About Weasis” menu and find the property weasis.path in the “System Information” tab.
Once the file has reached its maximum size, it is compressed into a zip archive, since Version4.4.0.
Boot log files
The boot log file is used to trace the startup configuration to ensure that the application starts with the correct input parameters and configuration.
This type of logs is interesting if the application doesn’t start, crash at startup, or if there is a problem with the startup preferences.
How to configure the rolling log files
From the main menu “File > Preferences > General” enable “Rolling log” to activate writing to files
Enter the maximum of File numbers for rolling log (by default 20)
Enter the maximum size of each rolling file (by default 10 MB)
Select a log level which defines the verbosity of the traces (by default INFO)
Select a stacktrace limit which represents the number of lines (by default 3). No value is recommended for investigating problems (it means unlimited stacktrace lines)
Info
The default logging configuration comes from base.json, see Weasis Preferences. Some default values has changed since Version4.4.0.
Proxy server
How to configure a proxy server
Manual configuration from the user interface
From the main menu, open File > Preferences (Alt + P) and select Proxy Server.
The default configuration is Direct connection (no proxy) and by clicking on Manual proxy configuration you can define a custom proxy server (in the image below, a local proxy like Squid).
In order to fill in the fields, you must refer to the Java documentation.
Tip
In some cases it is necessary to restart Weasis.
Configuration at launch
For setting JVM properties at launch, the selection in user interface must be Direct connection (no proxy) or configuration at launch.
Tip
The Java options can be manually set in the section “[JavaOptions]” of Weasis.cfg (in the installed path).
The Java options can also be passed in the parameters of the URL (e.g. http://localhost:8080/weasis-pacs-connector/weasis?patientID=9702672&pro=“https.proxyHost%20127.0.0.1”&pro=“https.proxyPort%203128”).
Dicomizer
How to convert images into DICOM files
Stories
The latest software developed at the University Hospital of Geneva (HUG) for medical imaging is Weasis which is the clinical viewer in the home-made Electronic Medical Records. Weasis is open source since 2010 and has become a reference DICOM viewer.
The University Hospital of Geneva has a long history of medical imaging software. Starting in 1990 at HUG, Osiris was the first radiological imaging viewer freely distributed around the world and then in 2003 OsiriX was the Mac successor to Osiris.
List of Weasis Success Stories
Note
Tell us if Weasis has been successfully used in your research projects, clinical applications or healthcare networks.
Edit this page with a pull request or send a message to @nroduit and we’ll share it on this page.
Color Histograms
Exporting DICOM
Measurement tools
Orthogonal Multiplanar Reconstruction
Pseudo-color
User Interface Language
Cross-reference lines
DICOM Attributes
DICOM Structured Report
Dicomizer
Display DICOM RT (Radiotherapy)
Display DICOM Waveforms
Download Manager
Exporting DICOM
Image Histogram
Importing DICOM
Lens on View
Split Series and Presentation State
