Introduction
In this tutorial, we show you how to install OpenREM on a bare Windows 10 64-bit system. OpenREM is a patient dose monitoring system, also known as a radiation dose management system, used for regulatory compliance, such as patient dose tracking and diagnostic reference levels (DRL), as well as quality control activities, such as patient dose optimisation projects. Original author is Ed McDonagh, copyright held by The Royal Marsden, and the project supported by the community.
OpenREM supports various platforms including Windows, Linux and Mac. The purpose of this tutorial is to provide a guide to Radiation Safety Officers, Medical Physicists and any other interested users on how to setup OpenREM and how it might be used to carry out day to day tasks and research. This post should only be used as a guide. IT, PACS and relevant teams should be consulted before integrating such a system in a production setting.
We encourage the community to review the most up to date documentation at http://docs.openrem.org while going through this tutorial as there is always updates and improvements being made to the project.
The video playlist matching this how-to tutorial can be found here.
Sections
Click to jump to the relevant section
Assumptions and Specifications
Assumptions that we make:
- You have some understanding of DICOM – https://en.wikipedia.org/wiki/DICOM
- You have some understanding of Python – https://en.wikipedia.org/wiki/Python_(programming_language)
- You are using this tutorial to carry out a test installation and not for production.
Specifications of the system used for installation:
- Windows 10 64-bit system (this should work on Windows Server 2016 as well).
- With no existing conflicting installations – base system.
- You have Administrative access to install applications.
- You have Direct connection to the internet from installation destination.
Installs are best done within a virtual machine as you can snapshot and rollback multiple times if you make any mistakes. Here’s some resource that can help you with this:
- https://www.youtube.com/watch?v=kF-8JijHMEU
- https://www.extremetech.com/computing/198427-how-to-install-windows-10-in-a-virtual-machine
Shopping List
The following items can be downloaded separately to speed up the process. You may be directed to copy and paste some of these URLs during the video segments.
There are additional downloads as part of steps that are more easily downloaded and installed during the steps themselves.
Item | Download |
python 2.7.15 | https://www.python.org/ftp/python/2.7.15/python-2.7.15.msi |
numpy | https://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy
numpy‑1.14.5+mkl‑cp27‑cp27m‑win_amd64.whl |
psycopg2 | https://www.lfd.uci.edu/~gohlke/pythonlibs/#psycopg
psycopg2‑2.7.5‑cp27‑cp27m‑win_amd64.whl |
pynetdicom (custom) | https://bitbucket.org/edmcdonagh/pynetdicom/get/default.tar.gz#egg=pynetdicom-0.8.2b2 |
Erlang | http://erlang.org/download/otp_win64_21.0.1.exe |
RabbitMQ | https://dl.bintray.com/rabbitmq/all/rabbitmq-server/3.7.7/rabbitmq-server-3.7.7.exe |
PostgreSQL 10 | https://get.enterprisedb.com/postgresql/postgresql-10.4-1-windows-x64.exe |
VS Code | https://code.visualstudio.com/download |
NSSM | https://nssm.cc/release/nssm-2.24.zip |
Orthanc | https://www.orthanc-server.com/download-windows.php |
LUA script | https://bitbucket.org/openrem/openrem/raw/0.8.0/stuff/openrem_orthanc_config.lua |
dcmtk (Dicom Toolkit) | ftp://dicom.offis.de/pub/dicom/offis/software/dcmtk/dcmtk363/bin/dcmtk-3.6.3-win64-dynamic.zip |
Python 2.7 and Supporting modules
Python is an interpreted high-level programming language and used to develop OpenREM. In this section, we cover installing Python 2.7 and supporting modules so we can install OpenREM. Note that Python 2.7 is now outdated and the team at OpenREM are working to support Python 3.
Video to follow along to: https://youtu.be/yAUmhlaatb0
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Download Python: https://www.python.org/ftp/python/2.7.15/python-2.7.15.msi |
2 | Browse to: https://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy
Search for and download the following numpy package: numpy‑1.14.5+mkl‑cp27‑cp27m‑win_amd64.whl |
3 | Browse to: https://www.lfd.uci.edu/~gohlke/pythonlibs/#psycopg
Search for and download the following psycopg2 package: psycopg2‑2.7.5‑cp27‑cp27m‑win_amd64.whl |
4 | Download custom pynetdicom:
https://bitbucket.org/edmcdonagh/pynetdicom/get/default.tar.gz#egg=pynetdicom-0.8.2b2 |
5 | Open File explorer
Double click “Downloads” |
6 | Double click “python-2.7.15.msi” installer file |
7 | Select default installation paths
Select “Available from local drive…” when option to add Python to PATH appears |
8 | Sign out of Windows Sign into Windows# This will re-read PATH environment variable for your session and allow you to run Python commands. |
9 | Right click Start
Left Click “Windows Powershell” Pin “Windows Powershell” to taskbar for later use. |
10 | In the Powershell window type the following commands:
|
RabbitMQ
In this part, we look at setting up RabbitMQ and supporting Erlang language framework. OpenREM uses RabbitMQ as a message broker service for tasks processed by Celery, which we discuss in a later section.
Video to follow along to: https://youtu.be/4EqgbsGxxu4
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Download and install Erlang:
http://erlang.org/download/otp_win64_21.0.1.exe Accept defaults |
2 | Download and install RabbitMQ
https://dl.bintray.com/rabbitmq/all/rabbitmq-server/3.7.7/rabbitmq-server-3.7.7.exe Accept defaults Accept firewall prompts |
PostgreSQL
In this section, we cover the installation and configuration of PostgreSQL. PostgreSQL is database system used to store OpenREM data and preferred by OpenREM due to its use of Django framework and inbuilt median functions.
Video to follow along to: https://youtu.be/Dm_TAAyum68
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Download PostgreSQL
https://www.enterprisedb.com/downloads/postgres-postgresql-downloads Select “PostgreSQL 10.4” Select “Windows x86-64” Click “Download Now” |
2 | Double click installer.
Select defaults unless you want an alternate download directory # Remember the postgres superuser password! Take tick off Stack Builder launch at the end of the setup |
3 | Click Start
Find postgres 10 -> pgAdmin Right click to pin pgAdmin to taskbar |
4 | Launch pgAdmin from task bar
Expand Servers Enter Superuser password Keep pgadmin opened |
5 | Expand Login/Group Roles -> Create User
Name: openrem Click Definition # Remember this password! Click Privileges Toggle “Can login?” and “Create Databases?” to “yes” Click Save |
6 | Expand “Databases”
Right click -> Create Database Database: openrem Change owner to “openrem” Click save |
OpenREM Initial Setup
In this section, we cover the initial setup of OpenREM itself. We also cover the installation of an IDE / Editor to better edit python code files There are lots available, but in this instructional, we install Visual Studio Code.
Video to follow along to: https://youtu.be/GgvFyO9jOmM
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Download and install Visual Studio Code
https://code.visualstudio.com/download Select defaults. Take tick OFF “Register code as default editor…” near end of setup. # We do this so vscode doesn’t launch python code files instead of python.exe. |
2 | Open Powershell
Run the following:
|
3 | Launch file explorer
Create folder structure: C:\OpenREM\media |
4 | Launch file explorer
Navigate to “C:\Python27\lib\site-packages\openrem\openremproject” Rename “local_settings.py.example” to “local_settings.py” Rename “wsgi.py.example” to “wsgi.py” Stay in this folder |
5 | Open local_settings.py in editorChange the following settings:
Save the file |
7 | Open Powershell
Run the following:
Keep this window open |
8 | Open file explorer
Navigate to C:\Python27\lib\site-packages\openrem\remapp\migrations Rename “0002_0_7_fresh_install_add_median.py.inactive” to “0002_0_7_fresh_install_add_median.py” |
9 | Back to the Powershell window you kept open
Run the following:
Everything should have a X in it. |
10 | Launch the inbuilt webserver:
Browse http://localhost and see if it loads. Ctrl-C in the powershell window to kill the web server which is required for the next part. |
Web Delivery using IIS
In this section, we cover delivering OpenREM web content using IIS (Internet Information Services) provided by Windows. We do this instead of using the inbuilt web server for both performance and security. We use the FastCGI capabilities of IIS as well as a Python module to serve the web content. This section is quite involved, so it’s best you read through the written steps as well as follow the video. Some sections can be copied and pasted to make things easier.
Video to follow along to: https://youtu.be/DAyeEZHihlw
Adapted from OpenREM documentation. Refer to most up to date documentation at http://docs.openrem.org.
Step | Details | ||||||||||||||
1 | Open Powershell and run:
|
||||||||||||||
2 | Click Start
Start typing (Search) “Turn windows features..” Select “Turn Windows Features on or off” Tick “Internet Information Services” Expand “Internet Information Services” -> “World Wide Web Services:” -> Expand “Application Development Features” Tick “CGI” Press OK |
||||||||||||||
3 | Click Start
Start typing (Search) “IIS” Pin “Internet Information Services (IIS) Manager) to taskbar |
||||||||||||||
4 | Open IIS Manager from pinned icon you just created
Click “FastCGI Settings” Icon at the top level Click “Add application” Change these settings:
Select and click the “…” on the “Environment Variables” line Add these variable pairs (Case sensitive):
Click OK twice |
||||||||||||||
5 | Open File explorer
Right click “C:\OpenREM” -> Properties -> Security Click Edit Click Add Enter “IIS_IUSRS” and click “OK” Click the “Allow” checkbox in the modify row for the user “IIS_IUSRS” Click OK |
||||||||||||||
6 | Repeat step 5 for the following paths:
C:\Python27\lib C:\Python27\Scripts |
||||||||||||||
7 | Open IIS Manager
Expand Sites Click on “Default Web Site” Click on “Basic Settings” in the right action window Change the Physical Path to “C:\Python27\Lib\site-packages\openrem” Stay in IIS manager for next step |
||||||||||||||
8 | Click on “Default Web Site”
Click on the “Handler Mappings” Icon Click on “Add module mapping” in right action window Change the following settings:
Click OK out of settings window and “Yes” to warning |
||||||||||||||
9 | Open File explorer
Navigate to “C:\Python27\Lib\site-packages\openrem” Create folder called “static” Navigate to “C:\Python27\Lib\site-packages\openrem\openremproject” Open “local_settings.py” in editor Change “STATIC_ROOT” setting to read Save the file |
||||||||||||||
10 | Open IIS Manager
Expand “Sites” Right click on “Default Web Site” -> “Add virtual directory” Settings below:
Click OK Click the “static” virtual directory Click “StaticFile” and click “View Ordered List” in the right action window Click “StaticFile” (again) and “Move Up” in the right action window Click “Yes” to the warnings Move “StaticFile” until it is at top of the list |
||||||||||||||
11 | Open Powershell
Run the following:
Type “yes” and hit enter |
||||||||||||||
12 | Browse to: http://localhost/
Site should look the same as when invoked using the inbuilt web server |
OpenREM Users and Settings
Now that we have a correctly configured OpenREM web service we can get to creating users and adjusting settings via the web interface. In most environments, you will have multiple users that require different levels of access. In this section, we cover the basics of creating users and adjusting settings. There is an abundance of settings available, and we encourage you to check them out on the OpenREM doc pages.
Video to follow along to: https://youtu.be/8dTVdKD-exM
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Open a web browser and enter into address bar:
http://localhost/ |
2 | Click the link to add users to the system
OR Navigate to http://localhost/admin |
3 | Authenticate using the “admin” account you created in earlier section
# This is the admin section for configuring users and changing permissions |
4 | Click “Add user” (to the right)
Enter a username and password Scroll down Click “Save” On next page Select all “Available groups” and click the right arrow to move them to “Chosen groups” Scroll down Click “Save” # Note there are settings that can be configured for the user at this point but we’ll do it as the user itself |
5 | Log out (top right)
Navigate to base page http://localhost Login using newly created account (top right) |
6 | Click Config -> Chart Options
Check “Plot charts” and “Submit Query” |
7 | Click Config -> Patient ID
Check Patient details in “Store data” if you wish to have these appear. Click “Submit” |
8 | Click Config -> Skin dose map
Check “Enable skin dose maps?” Check OFF “Calculate skin dose map on import” unless you have a lot of CPU processing power Click Submit |
Celery Workers
We’re almost ready to start importing DICOM files. We need to start workers used to process imports, exports and DICOM networking tasks. Celery is a framework used by OpenREM to process these requests via RabbitMQ message broker (which we set up earlier). In this section, we cover running the Celery workers in the background, so we don’t have to run them manually.
Video to follow along to: https://youtu.be/-AJluoe3OlU
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Open file explorer
Click View -> Options Click view tab Scroll down halfway and uncheck “Hide extensions for known file types” # This is required for creating files with alternate extensions and needed later. |
2 | Open File explorer
Create these subfolders: C:\OpenREM\media\celery |
2 | Download Service wrapper NSSM:
https://nssm.cc/release/nssm-2.24.zip File explorer -> Downloads -> Double click zip file Navigate to nssm-2.24\win64 Right click nssm -> Copy Navigate to C:\OpenREM\Support Paste # nssm.exe should now be in C:\OpenREM\Support directory |
3 | Open file explorer
Navigate to C:\OpenREM\Support Right click empty space -> Left click New -> Text Document Name the file “celery_service.bat” Right click and open in editor Paste the following in. Substitute paths if you’ve deviated from this tutorial:
Save the file |
4 | Right click Powershell -> Run Powershell as Administrator
Run the following:
# We install celery 3.1.25 due to issues with 4.X on Windows and supporting modules Keep window open |
5 | Run the following
When window loads change path to: C:\OpenREM\Support\celery_service.bat Click install Run the following command:
# This is a command line alternative to starting a service via command line instead of Services GUI |
6 | Open File explorer
Browse to C:\OpenREM\media\celery Ensure “default.pid” exists. Check contents of “default.log” and ensure it reads Celery worker started |
Import DICOM Manually
In this section, we show you how to import various DICOM files into OpenREM. We demonstrate using the included import scripts to import DICOM files for different modalities. We also demonstrate using some of the web functionality to report on and export data.
Video to follow along to: https://youtu.be/FcYEtI64HI0
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Open file explorer
Create folder C:\Temp |
2 | Open file explorer
Navigate to C:\Python27\lib\site-packages\openrem\remapp\tests\test_files Copy all dcm (DICOM) files Navigate to C:\Temp Paste files into directory |
3 | Open Powershell
Run the following
# This will use the OpenREM RDSR import script to import some Fluoroscopy and Radiography SR modality DICOMs |
4 | Browse to: http://localhost/
Login if not already logged in. Notice the new count of studies |
5 | Return to Powershell
Run the following
# Note this time we used the DX import script to import DX modality files instead of SRs |
6 | Go back to http://localhost/ in web browser
# Note the additional Radiography cases Click on Fluoroscopy Click on the “Siemens AXIOM-Artis” case Wait for Radiation exposure Incidence Map to be processed Click “Toggle 2D/3D view” # Note the calculated peak skin dose which can be used as estimation. Note that this feature is only supported on specific manufacturers and is experimental. # There are many metrics that you can review in your own time but some useful ones include dose area product, dose at reference point, acquisition protocols, event types, pulse rates. |
7 | Whilst still on site click “Fluoroscopy”
Click “Plot of mean DAP….” # Note the various functionality here. After a build up of cases you can use this feature to build Dose Reference Levels, compare different systems and optimise dose. Click “Export to CSV” in the “Data Export” window # You can review the contents at a later point. This is to demonstrate functionality. |
Import via DICOM Server
It is often more convenient to receive files into OpenREM automatically without having to extract and import into OpenREM manually. A good way to achieve this is to set up a DICOM server on the OpenREM server, have the institution PACS forward files onto the DICOM server and have the DICOM server invoke the import automatically. In this section, we go over setting up the DICOM server and configuring a LUA script to do the import on DICOM receipt. We also show a demo on sending some DICOM files to the DICOM server using a utility.
Video to follow along to: https://youtu.be/4vbMGp8m5_E
Refer to most up to date documentation at http://docs.openrem.org.
Step | Details |
1 | Visit https://www.orthanc-server.com/download-windows.php
Select “Orthanc 18.7.1 installer by Osimis…” Enter rest of details. This can be a personal email address # The actual installer for the free tool is provided by a corporate partner hence the requirement to provide contact details. One can compile manually but this is a much easier approach. |
2 | Wait for email
Download installer from link in email Double click and install the package keeping default options. |
3 | Browse to:
Right click “Raw” -> Save link/target as Save as “openrem_orthanc_config.lua” to C:\OpenREM\Support OR Save in downloads and move to C:\OpenREM\Support |
4 | Edit “C:\OpenREM\Support\openrem_orthanc_config.lua” file and change the following settings:
Save the file Close the file |
5 | Edit “C:\Program Files\Orthanc Server\Configuration\orthanc.json”
Change the “LuaScripts” setting to read like this:
# Scroll down and note your “DicomAet” and “DicomPort” settings. This will be useful later if configuring a PACS system to auto forward. In most cases it will be “ORTHANC” and “4242” Save the file Click “Retry as Admin” when prompt appears in bottom left. Save the file again Close the file |
6 | Open file explorer
Create folder C:\OpenREM\Support\dicom |
6 | Right click Start -> Computer management
Expand “Services and applications” Click Services Find “Orthanc” Right click -> Restart |
7 | Click Start
Start typing “firewall” Select “Allow an app through Windows Firewall” Click “Change settings” Click “Allow another app…” Browse to “C:\Program Files\Orthanc Server\Orthanc.exe” Click “Network Types” Make sure “Private” is also ticked Click OK Click Add Click OK |
8 | Open Powershell
Run the following command:
# Note down the “IPv4” Address. We will use this in transmitting files over DICOM send protocol |
9 | # Either on same system or system on network
Download ftp://dicom.offis.de/pub/dicom/offis/software/dcmtk/dcmtk363/bin/dcmtk-3.6.3-win64-dynamic.zip Open Zip file Copy folder out to C:\ and rename to C:\dcmtk |
10 | Open Powershell
Run the following
# Here we’re sending DICOM files to the DICOM server we just set up. Substitute the IP address for the one you took down earlier. If you are on a virtual machine this may not work if the network is hidden behind a NAT. If you do not know what this means that’s OK, you can do this from the same virtual machine. |
12 | Browse to: http://localhost
OR Browse to http://192.168.0.1 # Substitute IP address you took down earlier |
Wrapping Up
In this tutorial, we covered the basics of setting up an OpenREM server. We covered setting up supporting software, the OpenREM server itself and covered some of the DICOM import mechanisms.
We only covered the basics, and there is much more to discover and configure including things like a scheduled query of DICOMs from PACS, importing patient sizes and creating custom queries/reports. There are considerations to be made and challenges to face when implementation in a production setting.
OpenREM is an ever-evolving and growing project. We encourage everyone to head over to project site at https://www.openrem.org, look through the documentation and get actively involved in the project. There is a sizable community supporting it and they are always looking for feedback and more people to get involved.
If you have any feedback on this tutorial or the supporting videos, please feel free to comment. We are also looking for any suggestions on further “How-tos”.