dicom

<p align="center"> <img src="https://suyashkumar.com/assets/img/magnetic-resonance.png" width="125px"/> <h3 align="center">dicom</h3> <p align="center">High Performance Golang DICOM Medical Image Parser<p> <p align="center"> <a href="https://github.com/suyashkumar/dicom/actions"><img src="https://github.com/suyashkumar/dicom/workflows/build/badge.svg" /></a> <a href="https://godoc.org/github.com/suyashkumar/dicom"><img src="https://godoc.org/github.com/suyashkumar/dicom?status.svg" alt="" /></a> <a href="https://goreportcard.com/report/github.com/suyashkumar/dicom"><img src="https://goreportcard.com/badge/github.com/suyashkumar/dicom" alt=""></a> </p> </p>

:eyes: v1.0 just released!

This is a library and command-line tool to read, write, and generally work with DICOM medical image files in native Go. The goal is to build a full-featured, high-performance, and readable DICOM parser for the Go community.

After a fair bit of work, I've just released v1.0 of this library which is essentially rewritten from the ground up to be more canonical go, better tested, has new features, many bugfixes, and more (though there is always more to come on the roadmap).

Some notable features:

Parse multi-frame DICOM imagery (both encapsulated and native pixel data)
Channel-based streaming of Frames to a client as they are parsed out of the dicom
Cleaner Go Element and Dataset representations (in the absence of Go generics)
Better support for icon image sets in addition to primary image sets
Write and encode Datasets back to DICOM files
Enhanced testing and benchmarking support
Modern, canonical Go.

Usage

To use this in your golang project, import github.com/suyashkumar/dicom. This repository supports Go modules, and regularly tags releases using semantic versioning. Typical usage is straightforward:


dataset, _ := dicom.ParseFile("testdata/1.dcm", nil) // See also: dicom.Parse which has a generic io.Reader API.

// Dataset will nicely print the DICOM dataset data out of the box.
fmt.Println(dataset)

// Dataset is also JSON serializable out of the box.
j, _ := json.Marshal(dataset)
fmt.Println(j)

More details about the package (and additional examples and APIs) can be found in the godoc.

CLI Tool

A CLI tool that uses this package to parse imagery and metadata out of DICOMs is provided in the cmd/dicomutil package. This tool can take in a DICOM, and dump out all the elements to STDOUT, in addition to writing out any imagery to the current working directory either as PNGs or JPEG (note, it does not perform any automatic color rescaling by default).

Installation

You can download the prebuilt binaries from the releases tab, or use the following to download the binary at the command line using my getbin tool:

wget -qO- "https://getbin.io/suyashkumar/dicom" | tar xvz

(This attempts to infer your OS and 301 redirects wget to the latest github release asset for your system. Downloads come from GitHub releases).

Usage

dicomutil -path myfile.dcm

Note: for some DICOMs (with native pixel data) no automatic intensity scaling is applied yet (this is coming). You can apply this in your image viewer if needed (in Preview on mac, go to Tools->Adjust Color).

Build manually

To build manually, ensure you have make and go installed. Clone (or go get) this repo into your $GOPATH and then simply run:

make

Which will build the dicomutil binary and include it in a build/ folder in your current working directory.

You can also built it using Go directly:

go build -o dicomutil ./cmd/dicomutil

History

Here's a little more history on this repository for those who are interested!

v0

The v0 suyashkumar/dicom started off as a hard fork of go-dicom which was not being maintained actively anymore (with the original author being supportive of my fork--thank you!). I worked on adding several new capabilities, bug fixes, and general maintainability refactors (like multiframe support, streaming parsing, updated APIs, low-level parsing bug fixes, and more).

That represents the v0 history of the repository.

v1

For v1 I rewrote and redesigned the core library essentially from scratch, and added several new features and bug fixes that only live in v1. The architecture and APIs are completely different, as is some of the underlying parser logic (to be more efficient and correct). Most of the core rewrite work happened at the s/1.0-rewrite branch.

Acknowledgements

<img src="https://user-images.githubusercontent.com/6299853/90325771-b23f2e80-df34-11ea-9d18-5c33b69c2746.png" width="110px" align="left"/> Segmed for their help with validation and other contributions to the library.
Original go-dicom
Grailbio go-dicom -- commits from their fork were applied to ours
GradientHealth for supporting work I did on this while there gradienthealth/dicom
Innolitics DICOM browser
DICOM Specification
<div>Icons made by <a href="https://www.freepik.com/?__hstc=57440181.48e262e7f01bcb2b41259e2e5a8103b3.1557697512782.1557697512782.1557697512782.1&__hssc=57440181.4.1557697512783&__hsfp=2768524783" title="Freepik">Freepik</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a> is licensed by <a href="https://creativecommons.org/licenses/by/3.0/" title="Creative Commons BY 3.0" target="_blank">CC 3.0 BY</a></div>