DCMTK

A Ruby wrapper for DCMTK tools - specifically dcmj2pnm or dcm2img for converting DICOM medical files to standard image formats.

Information

Inspired by MiniMagick Ruby gem, this gem provides a DSL for working with DCMTK command-line tools.

Requirements

DCMTK command-line tools must be installed. You can check if you have it installed by running:

$ dcmj2pnm --version
$dcmtk: dcmj2pnm v3.6.7 2022-04-22

Installation

On macOS:

brew install dcmtk

On Ubuntu/Debian:

apt-get install dcmtk

Gem Installation

Add the gem to your Gemfile:

gem "dcmtk"

Usage

Let's first see a basic example - converting a DICOM file to PNG:

require "dcmtk"

package = DCMTK::Package.open("scan.dcm")
package.convert(format: :png)
package.write("output.png")

DCMTK::Package.open makes a copy of the package, and further methods modify that copy (the original stays untouched). The writing part is necessary because the copy is just temporary, it gets garbage collected when we lose reference to the package.

On the other hand, if we want the original package to actually get modified, we can use DCMTK::Package.new:

package = DCMTK::Package.new("scan.dcm")
package.convert(format: :png)
# Output file is created at scan.png (same name, different extension)

Supported Formats

The gem supports converting DICOM files to these formats:

Format	Symbol	dcmj2pnm Flag
PNG	:png	+on
BMP	:bmp	+ob
JPEG	:jpeg	+oj

# Convert to different formats
package.convert(format: :png)   # PNG output
package.convert(format: :bmp)   # BMP output
package.convert(format: :jpeg)  # JPEG output

Configuration

DCMTK.configure do |config|
  config.timeout = 5
  config.whiny = true  # raise errors on non-zero exit codes
  config.cli = "dcmj2pnm"  # force specific CLI (see below)
end

CLI Tool Selection

By default, the gem auto-detects which CLI tool to use:

• If dcm2img is found in PATH, it will be used
• Otherwise, falls back to dcmj2pnm

You can force a specific CLI tool:

# Force dcmj2pnm
DCMTK.configure do |config|
  config.cli = "dcmj2pnm"
end

# Force dcm2img
DCMTK.configure do |config|
  config.cli = "dcm2img"
end

# Check which CLI is being used
DCMTK.convert_cli #=> "dcm2img" or "dcmj2pnm"

Logging

You can choose to log DCMTK commands and their execution times:

DCMTK.logger.level = Logger::DEBUG

D, [2024-01-15T12:07:39.240238 #59063] DEBUG -- : [0.11s] dcmj2pnm +on /tmp/dcmtk20240115-59063-8yvk5s.dcm /tmp/output.png

In Rails you'll probably want to set DCMTK.logger = Rails.logger.

Metal

If you want to be close to the metal, you can use DCMTK's command-line tools directly:

DCMTK::Tool::Convert.new do |convert|
  convert.format(:png)
  convert << "input.dcm"
  convert << "output.png"
end #=> `dcmj2pnm +on input.dcm output.png`

# OR

convert = DCMTK::Tool::Convert.new
convert.format(:jpeg)
convert << "input.dcm"
convert << "output.jpg"
convert.call #=> `dcmj2pnm +oj input.dcm output.jpg`

You can also pass additional flags using method_missing:

DCMTK::Tool::Convert.new do |convert|
  convert.format(:png)
  convert.verbose  # adds --verbose flag
  convert << "input.dcm"
  convert << "output.png"
end

Troubleshooting

Errors being raised when they shouldn't

If you're using the tool directly, you can pass whiny: false value to the constructor:

DCMTK::Tool::Convert.new(whiny: false) do |convert|
  convert.help
end

Command not found

Make sure DCMTK tools are installed and either dcm2img or dcmj2pnm is in your PATH:

which dcm2img
which dcmj2pnm

License

MIT