Thursday, January 29, 2015

How-To: dcm4chee on Ubuntu

This article first appeared in Full Circle Magazine, issue #89.

Disclaimer

Maybe this article is not intended for a wide range of people reading this magazine, as I will describe the installation of a niche software related to the medical and health-care enterprise world.  It is not a home software; indeed nobody has a positron emission tomography (PET) facility at home, have they?

Intro


Maybe I’m wrong, but reading magazines like this, I have the feeling that Ubuntu, Linux and FOSS in general are mainly perceived, by common people, as something related to or useful for:
  • a hobby for geeks, computer enthusiasts and programmers
  • a free and legal way to achieve, using a PC, day by day personal interests (an alternative to Windows and paid software) and tasks such as:
    • multimedia and amusement: games, image editing and video playback 
    • personal and home income management
    • office software 
  • and for professional use, it seems something strictly related to information technology, like something made by programmers for other programmers or IT staff:
    • network tools
    • web server and stuff like that 
    • programming languages and development tools 
    • anything strictly related to IT, computer science, network and so on
    • and at last something related to business  
But there are other aspects of Linux and FOSS: the real world, the serious things. Like health care applications, as stated above.

So, in this article I will explain how to install dcm4chee on Ubuntu. Maybe, as I said before, no reader of this magazine will have the need or the knowledge to install and understand this software, but if you are a student, or if you know a dentist or a radiological study, maybe you could be inspired by knowing the existence of this software.

DICOM and PACS


DICOM (Digital Imaging and Communications in Medicine) “is a standard for handling, storing, printing, and transmitting information in medical imaging”.

PACS (Picture archiving and communication system) is a medical imaging technology which provides storage of and access to images from multiple modalities.

A modality is a source machine where patient’s images are acquired from, for example, an X-Ray machine or a Magnetic Resonance scanner. Some other actors of a PACS are: servers, storage (NAS, SAN, tapes), printers, viewers, CD/DVD robots, etc.
dcm4chee (http://dcm4che.org/) is a DICOM archive and image manager, that is the server side of a PACS system, the server where medical images (an x-ray, an ultrasound, a magnetic resonance) will be stored, and from which a radiologist will retrieve your examination in order to carry out a medical report.

“The application contains the DICOM, HL7 services and interfaces that are required to provide storage, retrieval, and workflow to a health-care environment”. It is written in Java and is prepackaged and deployed within the JBoss application server. It is open source and licensed under an MPL/GPL/LGPL triple license. There are also a lot of DICOM related tools provided by the same developers and community (called dcm4che toolkit), and some DICOM viewers, like Mayam, Oviyam and Weasis.

If you need help and assistance there is a Google group where a vibrant and nice community will be willing to give you some advice. On the other hand, the wiki lacks a little bit in documentation, that is some pages are dated or are incomplete.

Let's install it


Even if some willing person has packaged dcm4che in a “.deb” package, and even if I’m a lover of package management systems, in this case I feel better if I install this software by hand.

So, let’s see how to install dcm4chee on Ubuntu server 14.04 LTS.

First of all we need to install Java. I’m not sure if dcm4chee works with OpenJDK. And I’m not sure if it works with Java 1.7, so let’s install Oracle Java 1.6, using a PPA repository.

sudo apt-get install software-properties-common  
sudo add-apt-repository ppa:webupd8team/java 
sudo apt-get update  
sudo apt-get install oracle-java6-installer

We need to accept the license, and so on.  dcm4chee needs a database: Postgres, DB2, Oracle, MySQL, etc. If you want to try it without a RDBMS, you can opt for the HSQL package, but let’s install MySQL.

sudo apt-get install mysql-server 

Now we need to create a schema and grant all rights to a user.

$ mysql -uroot -p***** 
mysql> create schema pacsdb;  
mysql> grant all on pacsdb.* to pacs@localhost identified by 'pacs';  
mysql> flush privileges;  
mysql> \q

Now we need to download JBoss and dcm4chee zip files. Download JBoss 4.2.3.GA (don’t use a newer version!) from
http://sourceforge.net/projects/jboss/files/JBoss/JBoss-4.2.3.GA/jboss-4.2.3.GA-jdk6.zip/download
Download the latest release of dcm4chee-mysql, 2.18.0 at time of writing, from

http://sourceforge.net/projects/dcm4che/files/dcm4chee/

Put the zip files in a temporary folder, like /var/tmp/dcminstall and unzip them

sudo apt-get install unzip  
unzip dcm4chee-2.18.0-mysql.zip 
unzip jboss-4.2.3.GA-jdk6.zip 

Since we are on a 64-bit operating system, and the dcm4chee zip file contains a 32-bit version of compression library, we have to download the proper Java Advanced Imaging Image I/O Tools for linux 64-bit from
http://download.java.net/media/jai-imageio/builds/release/1.1/
and replace the Linux version of libclib_jiio.so

wget http://download.java.net/media/jai-imageio/builds/release/1.1/jai_imageio-1_1-lib-linux-amd64.tar.gz
tar xzvf jai_imageio-1_1-lib-linux-amd64.tar.gz
cp /var/tmp/install/jai_imageio-1_1/lib/libclib_jiio.so /var/tmp/install/dcm4chee-2.18.0-mysql/bin/native/libclib_jiio.so

Now we have to copy files from JBoss to Dcm4chee:

cd /var/tmp/install/dcm4chee-2.18.0-mysql/bin/  
./install_jboss.sh /var/tmp/install/jboss-4.2.3.GA

Now we have to import the provided SQL file in order to create the database tables and indexes:

cd /var/tmp/install/dcm4chee-2.18.0-mysql/sql/ 
mysql -upacs -ppacs pacsdb < create.mysql

And now we have to move the dcm4chee directory to a definitive place, like /opt, and then it is useful to create a symbolic link (so, in case of an upgrade, we don’t need to modify any script or anything else pointing to the dcm4chee directory):

cd /  
sudo mv /var/tmp/install/dcm4chee-2.18.0-mysql/ /opt/ 
sudo ln -s /opt/dcm4chee-2.18.0-mysql /opt/dcm4chee

It is a good idea to create a dcm4chee user and change the owner of the installation dir.

useradd dcm4chee 
chown -R dcm4chee /opt/dcm4chee-2.18.0-mysql

Now we can try to run dcm4chee in foreground:

su - dcm4chee -c /opt/dcm4chee/bin/run.sh

Using a web browser, connect to http://yourubuntuserver:8080/dcm4chee-web3
The default user is “admin” and the default password is “admin”.

In order to make changes to the default configuration, we need to use the JBoss jmx console http://yourubuntuserver:8080/jmx-console/, and this task could be painful since there are no manuals covering a step-by-step configuration: you have to dig inside the wiki and on the old forum or, as I said before, you can call for help in the mailing list.



More info: 

33 comments:

  1. Your post is useful. I am playing with DCM4CHE recently as well. I am getting:
    No Image Reader for format: rle registered
    java.lang.RuntimeException: No Image Reader for format: rle registered
    at org.dcm4che3.imageio.codec.ImageReaderFactory.getImageReader(ImageReaderFactory.java:218)
    at org.dcm4che3.imageio.plugins.dcm.DicomImageReader.readMetadata(DicomImageReader.java:497)
    at org.dcm4che3.imageio.plugins.dcm.DicomImageReader.read(DicomImageReader.java:273)
    while reading RLE encoded DICOM file. Do you have any idea about this error? Thanks!

    ReplyDelete
    Replies
    1. Are you have a OS 32 or 64 bits?

      Delete
    2. Maybe you are using the 32 bit version of imageio library with 64 bit java, or vice versa

      Delete
    3. This comment has been removed by the author.

      Delete
  2. Thanks for great article! What you meant by "Now we have to copy files from JBoss to Dcm4chee:" Copy with or without replace?

    ReplyDelete
    Replies
    1. I mean that you have to run the install_jboss.sh script.
      Maybe I forgot to write this part in this post. I will check asap.

      Delete
  3. Thanks for the article. I was looking for something like this.
    Just one question: Where can I dowload the "Java Advanced Imaging Image I/O Tools for linux 64-bit" from? The link is down and I can't find another option. Thanks.

    ReplyDelete
  4. Indeed the image-io link is broken. Check this post: https://groups.google.com/forum/m/?hl=en#!topic/dcm4che/aT5IdPMnh5Q

    ReplyDelete
  5. This comment has been removed by the author.

    ReplyDelete
  6. i had finished all step, but when i runn:
    su - dcm4chee -c /opt/dcm4chee/bin/run.sh
    i have:
    No directory, logging in with HOME=/
    run.sh: Missing required file: /opt/dcm4chee/bin/run.jar
    please help me!

    ReplyDelete
    Replies
    1. I have the same problem :S!

      Delete
    2. Hi, Maybe you can't create the database structure.

      sudo mysql -u root -p pacsdb < create.mysql

      Delete
  7. Your disclaimer "no reader of this magazine will have the need or the knowledge to install and understand this software" is wrong!

    This was great!! Thank you so much for putting these up!

    ReplyDelete
  8. How can I get access to the server from external network if I don't see the standalone.xml file?, I have already allowed access from anyware to all TCP ports. Thank in advance.

    ReplyDelete
  9. Hi,

    after this command "su - dcm4chee -c /opt/dcm4chee/bin/run.sh"
    system is asking password which one i need to enter

    Thanks & regards

    ReplyDelete
  10. Hi,

    after this command "su - dcm4chee -c /opt/dcm4chee/bin/run.sh" , system is asking password which password i need to enter?

    Thanks & Regards

    ReplyDelete
    Replies
    1. Well, the system user dcm4chee is an application user, like www-data, so it is not necessary to configure a password for it (via the passwd command or whatever). So i think, if you are not root, that you must use sudo:
      sudo su - dcm4chee -c /opt/dcm4chee/bin/run.sh

      Delete
  11. This comment has been removed by the author.

    ReplyDelete
  12. just followed your guide and got it working...Some knowledge about Ubuntu in general, MySQL will help. :-)
    But got it to work in less then 1 hour.... on vmware in Kubuntu 16.10 with MySql 5.7.12 and in 64bit but kept to the advised java 1.6.
    nice blog. TOP
    rgds,
    rob

    ReplyDelete
    Replies
    1. You need to change some in your blog.

      You are mentioning "Put the zip files in a temporary folder, like /var/tmp/dcminstall and unzip them" but using "/var/tmp/install" in your command lines

      I have tried to run it with the default openJDK 1.8 of Ubuntu 16.10 but the web looks running but the JBoss jmx console will fail. actually tried with all versions above 1.6 and all failed to show the console right. the rest gave error messages and showed the code. Probably for the java gurus no challenge but i am not. So went back to SDK 1.6 and all runs smooth.

      Delete
  13. Can you please give details why not to use with a new version of jboss please

    ReplyDelete
    Replies
    1. I have read this
      "Use neither JBoss 5 nor JBoss 6, because it is completely re-architected and is significantly different than the 4.2 line of JBoss!" from the dcm4che wiki, sorry for quick question without reading anything

      Delete
  14. Good tutorial but last step i have an issue
    No directory, logging in with HOME=/
    run.sh: Missing required file: /opt/dcm4chee/bin/run.jar

    could you please help me to run this

    ReplyDelete
    Replies
    1. Which version are you using? The latest one, 2.18.3, lack some files in the bin directory, you have to copy the missing files from the 2.18.0 release. In addition, do you have issued the install_jboss.sh script?

      Delete
  15. This comment has been removed by the author.

    ReplyDelete
  16. Hi,
    I following exactly per your instructions, installed the same versions as yours, but the image is not showing up in the dcm4chee when click on Open Image Selection.

    Following is the log file.
    13:12:43,627 WARN [PatientBean] Coerce null to (0010,0021) Issuer of Patient ID,LO,*1,#22,[Issuer of Patient ID1 ]
    13:12:43,648 INFO [InstanceBean] Created Instance[pk=14, iuid=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.848.26, cuid=1.2.840.10008.5.1.4.1.1.7, series->ejb/Series:6]
    13:12:43,682 INFO [FileBean] Created File[pk=14, 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.128.22
    13:13:03,191 INFO [WADOServlet] 127.0.0.1 - WADO URL:/wado?requestType=WADO&studyUID=100.118.116.2005.2.1.1143729853.921.5&seriesUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.639.21&objectUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.24.23&columns=128
    13:13:03,194 INFO [WADOSupport] Get WADO object for 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.24.23
    13:13:03,206 INFO [WADOServlet] 127.0.0.1 - WADO URL:/wado?requestType=WADO&studyUID=100.118.116.2005.2.1.1143729853.921.5&seriesUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.248.24&objectUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.598.25&columns=128
    13:13:03,208 INFO [WADOSupport] Get WADO object for 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.598.25
    13:13:03,219 INFO [WADOServlet] 127.0.0.1 - WADO URL:/wado?requestType=WADO&studyUID=100.118.116.2005.2.1.1143729853.921.5&seriesUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.248.24&objectUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.848.26&columns=128
    13:13:03,220 INFO [WADOSupport] Get WADO object for 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.848.26
    13:13:03,222 INFO [WADOServlet] 127.0.0.1 - WADO URL:/wado?requestType=WADO&studyUID=100.118.116.2005.2.1.1143729853.921.5&seriesUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.248.24&objectUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.109.27&columns=128
    13:13:03,222 INFO [WADOSupport] Get WADO object for 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.109.27
    13:13:03,395 INFO [CacheJournal] M-WRITE /home/wangchuk/Downloads/dcm4chee-2.18.0-mysql/server/default/wadocachejournal/2016/09/10/13
    13:13:03,401 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,403 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,402 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,402 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,401 INFO [WADOServlet] send WADO response: image/jpeg

    Please let me know.
    Thank you.

    ReplyDelete
  17. Hi,
    I followed exactly per your instructions, installed the same versions. But image is not showing up in dcm4chee when click on open image selection. No any error, i noticed in the log file. Following is some part of the log file.

    13:13:03,208 INFO [WADOSupport] Get WADO object for 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.598.25
    13:13:03,219 INFO [WADOServlet] 127.0.0.1 - WADO URL:/wado?requestType=WADO&studyUID=100.118.116.2005.2.1.1143729853.921.5&seriesUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.248.24&objectUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.848.26&columns=128
    13:13:03,220 INFO [WADOSupport] Get WADO object for 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.848.26
    13:13:03,222 INFO [WADOServlet] 127.0.0.1 - WADO URL:/wado?requestType=WADO&studyUID=100.118.116.2005.2.1.1143729853.921.5&seriesUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.248.24&objectUID=1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.109.27&columns=128
    13:13:03,222 INFO [WADOSupport] Get WADO object for 1.2.826.0.1.3680043.2.1545.1.2.1.7.20160910.131237.109.27
    13:13:03,395 INFO [CacheJournal] M-WRITE /home/wangchuk/Downloads/dcm4chee-2.18.0-mysql/server/default/wadocachejournal/2016/09/10/13
    13:13:03,401 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,403 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,402 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,402 INFO [WADOServlet] send WADO response: image/jpeg
    13:13:03,401 INFO [WADOServlet] send WADO response: image/jpeg

    Please let me know.
    Thanks

    ReplyDelete
  18. Hello, first of all thanks for the article, and now can you tell me how configure dcm4chee as a service or daemon

    ReplyDelete
  19. Hello, first of all thanks for the article, and second, can you tell me how configure dcm4chee as a service or daemon

    ReplyDelete
    Replies
    1. From http://www.dcm4che.org/docs/reference/dcm4chee/html/dcm4chee-installation.html

      After verifying that the application is installed and running correctly, you may want to install it as a Windows service or Unix daemon.

      Stop the application (type ctrl-c in the console window).

      Windows: install dcm4chee as a Windows service executing DCM4CHEE_DIST/bin/install_service.bat.

      Redhat Linux: copy the init script DCM4CHEE_DIST/bin/dcm4chee_init_redhat.sh to /etc/init.d/ and adjust it according to the dcm4chee installation location, the JDK installation location, and which user the dcm4chee should run under.

      Delete
  20. Nice tutorial,I am using dcmsnd command for sending dicom images with PatientId but image can't going to specific patient and other patient are able to view data of different patient.
    what will be the specific permission and roles for User to perform activities and how to send particular images for specific patient.
    can anyone know..?
    Thanks in advance.

    ReplyDelete
  21. Hello,

    Maybe someone can help me, how create CD/DVD from DCM4CHEE autorun using weasis viewer.

    thanks

    ReplyDelete