Visit the Download Page for a comprehensive list of installation options adapted 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 supports launching Weasis from a web context via the weasis protocol.
General Topics
Get started with these links to learn more about Weasis and its features:
Live Demo: Explore Weasis with a variety of DICOM datasets.
Weasis Web Protocol: Learn how to launch Weasis directly from web links or network-based workflows.
Weasis can be installed on desktop systems such as Windows, macOS, and Linux. It does not require any additional frameworks (such as Java) to be installed. However, some graphics-related requirements must be met to use Volume Rendering.
Info
The open-source distribution of Weasis is not a certified medical device (CE or FDA). Any primary diagnostic use requires you to ensure full compliance with the laws and regulations applicable in your jurisdiction.
Package management systems
Get automatic updates for Weasis by installing it via these package management systems:
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.
List of All Installers
All the packages can be found on Github and the legacy repository Sourceforge
Stay informed about new releases and updates by joining our Google Group. Choose “Email” to get updates directly to your inbox.
For details about GLIBC versions and Linux distribution compatibility, see this page.
This page explains how to integrate Weasis with dcm4chee-arc-light using weasis-pacs-connector. To launch Weasis without the connector, follow the alternative instructions.
Follow these steps for the integration with weasis-pacs-connector:
Install dcm4chee, if not already done (Installation with Docker is straightforward).
Go here and download weasis-pacs-connector.war — See Configuration Matrix below for the recommended version according to your dcm4chee-arc-light version.
Add weasis-pacs-connector.war using the “Add” button (Choose Upload a new deployment or select Replace when the file already exists)
Note
Alternatively one may deploy the .war using JBoss Command Line Interface Console.
Configure weasis-pacs-connector (optional if default settings are sufficient).
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:
To apply the new configuration, from the management console “Disable” weasis-pacs-connector.war then “Enable”
To activate Weasis in the dcm4chee-arc-light user interface (See also Invoke Image Display in dcm4chee):
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:
Configure the URL for a view button at patient or study level and then copy the properties from Configuration Matrix.
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 (allows applying properties at deploy time). 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 opening a new empty window in the browser
Refresh the web page and the view button should appear as in the screenshot above
To launch the viewer from the web portal, the client computer must have installed the Weasis package.
Configuration Matrix
Note
The list below maps dcm4chee-arc-light versions to the recommended weasis-pacs-connector, and gives the properties to add in dcm4chee-arc-light configuration to enable Weasis launching.
Older versions pass _self via query parameter (target=_self); newer versions (5.22.2+) use the dedicated property IID_URL_TARGET=_self.
The Weasis Protocol enables the launch of Weasis (starting from
v3.6.0
) in a web context using a specific URI scheme: weasis://?commands.
How to Use the Weasis Protocol
To launch Weasis from various contexts:
From a Web Page: Create a link that begins with weasis://? (see below How to build an URI).
If certain web frameworks (e.g., WIKI) or contexts only support HTTP protocols, you can use a URL redirection starting with https://. A tool such as Weasis PACS Connector can help with this.
From the Command Line: Utilize the appropriate Weasis command from the terminal:
open weasis://?%24dicom%3Aget+-w+%22https%3A%2F%2Fnroduit.github.io%2Fdemo-archive%2FLumbar%2Fmf.xml%22
How to Build a URI
The weasis://? URI scheme allows you to launch Weasis directly from the system’s URI handler. By constructing the correct URI path, you can execute Weasis commands to load images or perform other actions.
Weasis PACS Connector can dynamically generate manifests (listing references for images to load) and build the required URI through an API. This tool also manages user preferences and other launch parameters.
If you’re not using the Weasis PACS Connector, you can build a URI manually by following these steps:
Choose Commands: Select one or more commands to execute.
Encode the Commands: Use a URL encoder to format the commands correctly for URI inclusion.
Prefix the Commands: Add the weasis://? scheme at the beginning of the encoded command string to create the final URI.
For loading multiple images, it’s recommended to use a manifest file that references all desired images instead of including each image individually in the URI. The easiest way to build this manifest dynamically is by using the Weasis PACS Connector. Alternatively, you can create the manifest manually following the provided 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-native.zip package in ViewerHub). 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.
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
By default, Weasis registers the weasis:// protocol through standard OS mechanisms. To ensure a seamless user experience in institutional environments, administrators can suppress the browser’s security confirmation dialog using central policies.
Windows Registry Editor Version 5.00
; Chrome[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\URLAllowlist]"1"="weasis://*"; Chromium[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Chromium\URLAllowlist]"1"="weasis://*"; Microsoft Edge[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\URLAllowlist]"1"="weasis://*"; Firefox[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Mozilla\Firefox\WebsiteFilter\Exceptions]"1"="weasis://*"
Note: The number in quotes (“1”) should be incremented if you already have other entries in the list.
PayloadType: com.google.Chrome (Chrome) or com.brave.Browser (Brave).
Firefox: Use the macOS Mozilla Policy structure.
Building Weasis
These instructions guide you through building Weasis directly from its GitHub repository. For IDE-based builds, refer to the Weasis plugin development guidelines.
-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, the version must not include SNAPSHOT (as packages with a SNAPSHOT are always downloaded, not cached). To remove SNAPASHOT or create your own release (use a specific name to prevent package conflicts in the cache), update the changelist property. From the Weasis root folder, execute:
However, you can also build the native binaries and installer locally using the package-weasis.sh script. This process is not guaranteed to work on all systems, as it requires proper configuration of multiple tools. Refer to the jpackage prerequisites for more details.
Obtain the weasis-native.zip file, extract the archive, and navigate to the root folder in a Bash prompt.
Run the following command to build the native binaries and installer:
Replace --jdk with the path to your local JDK installation.
To generate only the native binaries (without creating an installer), include the --no-installer flag.
For additional command 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 Plugin Development
This page describes the necessary configurations to be able to debug Weasis using an IDE. For developers who want to create new plugins, you can visit How to build and install a plugin.
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.3 or higher)
Use JDK 24 or higher and set the language level to SDK Default in File > Project Structure… >. Required Maven version is 3.8.1 or higher.
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 plugins
In the maven panel, select clean/install in Lifecycle of weasis-framework (root) to compile and to install all the plugins 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 a 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 plugins 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 plugins 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 plugin 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).
