README ¶
dicom
High Performance Golang DICOM Medical Image Parser
👀 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
Frame
s to a client as they are parsed out of the dicom - Cleaner Go Element and Dataset representations (in the absense 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/rohautl/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/rohautl/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 rohautl/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 happend at the s/1.0-rewrite
branch.
Acknowledgements
- 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
Documentation ¶
Overview ¶
Package dicom provides a set of tools to read, write, and generally work with DICOM (http://dicom.nema.org/) medical image files in Go.
dicom.Parse and dicom.Write provide the core functionality to read and write DICOM Datasets. This package provides Go data structures that represent DICOM concepts (for example, dicom.Dataset and dicom.Element). These structures will pretty-print by default and are JSON serializable out of the box.
This package provides some advanced functionality as well, including: streaming image frames to an output channel, reading elements one-by-one (like an iterator pattern), flat iteration over nested elements in a Dataset, and more.
General usage is simple. Check out the package examples below and some function specific examples.
It may also be helpful to take a look at the example cmd/dicomutil program, which is a CLI built around this library to save out image frames from DICOMs and print out metadata to STDOUT.
Index ¶
- Variables
- func ExhaustElementChannel(c <-chan *Element)
- func MustGetBytes(v Value) []byte
- func MustGetFloats(v Value) []float64
- func MustGetInts(v Value) []int
- func MustGetStrings(v Value) []string
- func Write(out io.Writer, ds Dataset, opts ...WriteOption) error
- type Dataset
- type Element
- type FlatDatasetIterator
- type ParseOption
- type Parser
- type PixelDataInfo
- type SequenceItemValue
- type Value
- type ValueType
- type WriteOption
- type Writer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrorMagicWord indicates that the magic word was not found in the correct // location in the DICOM. ErrorMagicWord = errors.New("error, DICM magic word not found in correct location") // ErrorMetaElementGroupLength indicates that the MetaElementGroupLength // was not found where expected in the metadata. ErrorMetaElementGroupLength = errors.New("MetaElementGroupLength tag not found where expected") // ErrorEndOfDICOM indicates to the callers of Parser.Next() that the DICOM // has been fully parsed. Users using one of the other Parse APIs should not // need to use this. ErrorEndOfDICOM = errors.New("this indicates to the caller of Next() that the DICOM has been fully parsed") )
var ( // ErrorOWRequiresEvenVL indicates that an element with VR=OW had a not even // value length which is not allowed. ErrorOWRequiresEvenVL = errors.New("vr of OW requires even value length") // ErrorUnsupportedVR indicates that this VR is not supported. ErrorUnsupportedVR = errors.New("unsupported VR") // ErrorUnsupportedBitsAllocated indicates that the BitsAllocated in the // NativeFrame PixelData is unsupported. In this situation, the rest of the // dataset returned is still valid. ErrorUnsupportedBitsAllocated = errors.New("unsupported BitsAllocated") )
var ( // ErrorUnimplemented is for not yet finished things. ErrorUnimplemented = errors.New("this functionality is not yet implemented") // ErrorMismatchValueTypeAndVR is for when there's a discrepency betweeen the ValueType and what the VR specifies. ErrorMismatchValueTypeAndVR = errors.New("ValueType does not match the VR required") // ErrorUnexpectedValueType indicates an unexpected value type was seen. ErrorUnexpectedValueType = errors.New("Unexpected ValueType") // ErrorUnsupportedBitsPerSample indicates that the BitsPerSample in this // Dataset is not supported when unpacking native PixelData. ErrorUnsupportedBitsPerSample = errors.New("unsupported BitsPerSample value") )
var ErrorElementNotFound = errors.New("element not found")
ErrorElementNotFound indicates that the requested element was not found in the Dataset.
var ErrorUnexpectedDataType = errors.New("the type of the data was unexpected or not allowed")
ErrorUnexpectedDataType indicates that an unexpected (not allowed) data type was sent to NewValue.
Functions ¶
func ExhaustElementChannel ¶ added in v1.0.6
func ExhaustElementChannel(c <-chan *Element)
ExhaustElementChannel exhausts the channel iterator returned by Dataset.FlatIterator, ensuring that the underlying Go routine completes. When using Dataset.FlatIterator, if your program will exit for some reason without reading all the elements of the channel, you should be sure to call this function to prevent a phantom Goroutine. Or, if you don't need the channel interface, simply use Dataset.FlatStatefulIterator.
func MustGetBytes ¶ added in v1.0.6
MustGetBytes attempts to get a Bytes value out of the provided Value, and will panic if it is unable to do so.
func MustGetFloats ¶ added in v1.0.6
MustGetFloats attempts to get a Floats value out of the provided Value, and will panic if it is unable to do so.
func MustGetInts ¶ added in v1.0.6
MustGetInts attempts to get an Ints value out of the provided value, and will panic if it is unable to do so.
func MustGetStrings ¶ added in v1.0.6
MustGetStrings attempts to get a Strings value out of the provided Value, and will panic if it is unable to do so.
Types ¶
type Dataset ¶ added in v1.0.6
type Dataset struct {
Elements []*Element `json:"elements"`
}
Dataset represents a DICOM dataset, see http://dicom.nema.org/medical/dicom/current/output/html/part05.html#chapter_7.
This Dataset representation is JSON serializable out of the box (implements json.Marshaler) and will also pretty print as a string nicely (see String example). This Dataset includes several helper methods to find Elements within this dataset or iterate over every Element within this Dataset (including Elements nested within Sequences).
func Parse ¶ added in v1.0.6
Parse parses the entire DICOM at the input io.Reader into a Dataset of DICOM Elements. Use this if you are looking to parse the DICOM all at once, instead of element-by-element.
func ParseFile ¶ added in v1.0.6
ParseFile parses the entire DICOM at the given filepath. See dicom.Parse as well for a more generic io.Reader based API.
func (*Dataset) FindElementByTag ¶ added in v1.0.6
FindElementByTag searches through the dataset and returns a pointer to the matching element. It DOES NOT search within Sequences as well.
func (*Dataset) FindElementByTagNested ¶ added in v1.0.6
FindElementByTagNested searches through the dataset and returns a pointer to the matching element. This call searches through a flat representation of the dataset, including within sequences.
func (*Dataset) FlatIterator ¶ added in v1.0.6
FlatIterator will be deprecated soon in favor of Dataset.FlatStatefulIterator. Use FlatStatefulIterator instead of this, unless the channel API really makes your life a lot easier (and let the maintainers know on GitHub).
FlatIterator returns a channel upon which every element in this Dataset will be sent, including elements nested inside sequences.
If for some reason your code will not exhaust the iterator (read all elements), be sure to call ExhaustElementChannel to prevent leaving the underlying Goroutine alive (you can safely do this in a defer).
c := dataset.FlatIterator() defer ExhaustElementChannel(c) for elem := range c { // Even if you exit before reading everything in c (e.g. due to an // error) // things will be ok. }
Note that the sequence element itself is sent on the channel in addition to the child elements in the sequence. TODO(rohautl): decide if the sequence element itself should be sent or not
Example ¶
Output: (0028,0010) (0028,0011) (0010,0010) (0046,0102)
func (*Dataset) FlatStatefulIterator ¶ added in v1.0.6
func (d *Dataset) FlatStatefulIterator() *FlatDatasetIterator
FlatStatefulIterator returns a stateful iterator that adheres to FlatDatasetIterator interface. This allows the caller to iterate over every element in the dataset, including elements nested inside sequences.
Important note: if the Dataset changes during the iteration (e.g. if elements are added or removed), those elements will not be included until a new iterator is created.
If you don't need to receive elements on a channel, and don't want to worry about always exhausting this iterator, this is the best and safest way to iterate over a Dataset. Unlike FlatIterator(), no special cleanup or channel exhausting is needed with this iterator.
Example ¶
Output: (0028,0010) (0028,0011) (0010,0010) (0046,0102)
func (*Dataset) String ¶ added in v1.0.6
String returns a printable representation of this dataset as a string, including printing out elements nested inside sequence elements.
Example ¶
Output: [ Tag: (0028,0010) Tag Name: Rows VR: VRInt32List VR Raw: UL VL: 0 Value: &{[100]} ] [ Tag: (0028,0011) Tag Name: Columns VR: VRInt32List VR Raw: UL VL: 0 Value: &{[200]} ]
type Element ¶
type Element struct { Tag tag.Tag `json:"tag"` ValueRepresentation tag.VRKind `json:"VR"` RawValueRepresentation string `json:"rawVR"` ValueLength uint32 `json:"valueLength"` Value Value `json:"value"` }
Element represents a standard DICOM data element (see the DICOM standard: http://dicom.nema.org/medical/dicom/current/output/html/part05.html#sect_7.1 ). This Element can be serialized to JSON out of the box and pretty printed as a string via the String() method.
func NewElement ¶
NewElement creates a new DICOM Element with the supplied tag and with a value built from the provided data. The data can be one of the types that is acceptable to NewValue.
type FlatDatasetIterator ¶ added in v1.0.6
type FlatDatasetIterator struct {
// contains filtered or unexported fields
}
FlatDatasetIterator is a stateful iterator over a Dataset.
func (*FlatDatasetIterator) HasNext ¶ added in v1.0.6
func (f *FlatDatasetIterator) HasNext() bool
HasNext indicates if the iterator as another element.
func (*FlatDatasetIterator) Next ¶ added in v1.0.6
func (f *FlatDatasetIterator) Next() *Element
Next gets and returns the next element in the iterator.
type ParseOption ¶ added in v1.0.6
type ParseOption func(*parseOptSet)
ParseOption represents an option that can be passed to NewParser.
func SkipMetadataReadOnNewParserInit ¶ added in v1.0.6
func SkipMetadataReadOnNewParserInit() ParseOption
SkipMetadataReadOnNewParserInit makes NewParser skip trying to parse metadata. This will make the Parser default to implicit little endian byte order. Any metatata tags found in the dataset will still be available when parsing.
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser is a struct that allows a user to parse Elements from a DICOM element-by-element using Next(), which may be useful for some streaming processing applications. If you instead just want to parse the whole input DICOM at once, just use the dicom.Parse(...) method.
func NewParser ¶
func NewParser(in io.Reader, bytesToRead int64, frameChannel chan *frame.Frame, opts ...ParseOption) (*Parser, error)
NewParser returns a new Parser that points to the provided io.Reader, with bytesToRead bytes left to read. NewParser will read the DICOM header and metadata as part of initialization.
frameChannel is an optional channel (can be nil) upon which DICOM image frames will be sent as they are parsed (if provided).
func (*Parser) GetMetadata ¶ added in v1.0.6
GetMetadata returns just the set of metadata elements that have been parsed so far.
type PixelDataInfo ¶
type PixelDataInfo struct { Frames []frame.Frame IsEncapsulated bool `json:"isEncapsulated"` Offsets []uint32 }
PixelDataInfo is a representation of DICOM PixelData.
func MustGetPixelDataInfo ¶ added in v1.0.6
func MustGetPixelDataInfo(v Value) PixelDataInfo
MustGetPixelDataInfo attempts to get a PixelDataInfo value out of the provided Value, and will panic if it is unable to do so.
type SequenceItemValue ¶ added in v1.0.6
type SequenceItemValue struct {
// contains filtered or unexported fields
}
SequenceItemValue is a Value that represents a single Sequence Item. Learn more about Sequences at http://dicom.nema.org/medical/dicom/current/output/chtml/part05/sect_7.5.html.
func (*SequenceItemValue) GetValue ¶ added in v1.0.6
func (s *SequenceItemValue) GetValue() interface{}
GetValue returns the underlying value that this Value holds. What type is returned here can be determined exactly from the ValueType() of this Value (see the ValueType godoc).
func (*SequenceItemValue) MarshalJSON ¶ added in v1.0.6
func (s *SequenceItemValue) MarshalJSON() ([]byte, error)
MarshalJSON is the method used to marshal this struct to JSON.
func (*SequenceItemValue) String ¶ added in v1.0.6
func (s *SequenceItemValue) String() string
String is used to get a string representation of this struct.
func (*SequenceItemValue) ValueType ¶ added in v1.0.6
func (s *SequenceItemValue) ValueType() ValueType
ValueType returns the underlying ValueType of this Value. This can be used to unpack the underlying data in this Value.
type Value ¶ added in v1.0.6
type Value interface { // ValueType returns the underlying ValueType of this Value. This can be used to unpack the underlying data in this // Value. ValueType() ValueType // GetValue returns the underlying value that this Value holds. What type is returned here can be determined exactly // from the ValueType() of this Value (see the ValueType godoc). GetValue() interface{} // TODO: rename to Get to read cleaner String() string MarshalJSON() ([]byte, error) // contains filtered or unexported methods }
Value represents a DICOM value. The underlying data that a Value stores can be determined by inspecting its ValueType. DICOM values typically can be one of many types (ints, strings, bytes, sequences of other elements, etc), so this Value interface attempts to represent this as canoically as possible in Golang (since generics do not exist yet).
Value is JSON serializable out of the box (implements json.Marshaler).
If necessary, a Value's data can be efficiently unpacked by inspecting its underlying ValueType and either using a Golang type assertion or using the helper functions provided (like MustGetStrings). Because for each ValueType there is exactly one underlying Golang type, this should be safe, efficient, and straightforward.
switch(myvalue.ValueType()) { case dicom.Strings: // We know the underlying Golang type is []string fmt.Println(dicom.MustGetStrings(myvalue)[0]) // or s := myvalue.GetValue().([]string) break; case dicom.Bytes: // ... }
Unpacking the data like above is only necessary if something specific needs to be done with the underlying data. See the Element and Dataset examples as well to see how to work with this kind of data, and common patterns for doing so.
func NewValue ¶ added in v1.0.6
NewValue creates a new DICOM value for the supplied data. Likely most useful if creating an Element in testing or write scenarios.
Data must be one of the following types, otherwise and error will be returned (ErrorUnexpectedDataType).
Acceptable types: []int, []string, []byte, []float64, PixelDataInfo, [][]*Element (represents a sequence, which contains several items which each contain several elements).
type ValueType ¶ added in v1.0.6
type ValueType int
ValueType is a type that represents the type of a Value. It is an enumerated set, and the set of values can be found below.
const ( // Strings represents an underlying value of []string Strings ValueType = iota // Bytes represents an underlying value of []byte Bytes // Ints represents an underlying value of []int Ints // PixelData represents an underlying value of PixelDataInfo PixelData // SequenceItem represents an underlying value of []*Element SequenceItem // Sequences represents an underlying value of []SequenceItem Sequences // Floats represents an underlying value of []float64 Floats )
Possible ValueTypes that represent the different value types for information parsed into DICOM element values. Each ValueType corresponds to exactly one underlying Golang type.
type WriteOption ¶ added in v1.0.6
type WriteOption func(*writeOptSet)
WriteOption represents an option that can be passed to WriteDataset. Later options will override previous options if applicable.
func DefaultMissingTransferSyntax ¶ added in v1.0.6
func DefaultMissingTransferSyntax() WriteOption
DefaultMissingTransferSyntax returns a WriteOption indicating that a missing transferSyntax should not raise an error, and instead the default LittleEndian Implicit transfer syntax should be used and written out as a Metadata element in the Dataset.
func SkipVRVerification ¶ added in v1.0.6
func SkipVRVerification() WriteOption
SkipVRVerification returns a WriteOption that skips VR verification.
func SkipValueTypeVerification ¶ added in v1.0.6
func SkipValueTypeVerification() WriteOption
SkipValueTypeVerification returns WriteOption function that skips checking ValueType for concurrency with VR and casting
type Writer ¶ added in v1.0.6
type Writer struct {
// contains filtered or unexported fields
}
Writer is a struct that allows element-by element writing to a DICOM writer.
func NewWriter ¶ added in v1.0.6
func NewWriter(out io.Writer, opts ...WriteOption) *Writer
NewWriter returns a new Writer, that points to the provided io.Writer.
func (*Writer) SetTransferSyntax ¶ added in v1.0.6
SetTransferSyntax sets the transfer syntax for the underlying dicomio.Writer.
func (*Writer) WriteElement ¶ added in v1.0.6
WriteElement writes a single DICOM element to a Writer.
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
dicomutil
Really basic sanity check program
|
Really basic sanity check program |
mocks
|
|
pkg/dicomio
Package mock_dicomio is a generated GoMock package.
|
Package mock_dicomio is a generated GoMock package. |
pkg
|
|
dcmtime
Package dcmtime contains functions and data types for converting DICOM date and time values to native go values.
|
Package dcmtime contains functions and data types for converting DICOM date and time values to native go values. |
personname
The personname package provides methods and data types for inspecting Person Name (PN) DICOM Value Representations, as defined here: http://dicom.nema.org/dicom/2013/output/chtml/part05/sect_6.2.html
|
The personname package provides methods and data types for inspecting Person Name (PN) DICOM Value Representations, as defined here: http://dicom.nema.org/dicom/2013/output/chtml/part05/sect_6.2.html |
tag
Package tag enumerates element tags defined in the DICOM standard.
|
Package tag enumerates element tags defined in the DICOM standard. |
vrraw
Package vrraw offers aliases to all VR abbreviations as defined here: http://dicom.nema.org/medical/dicom/current/output/html/part05.html#table_6.2-1 Deprecated VRs from older editions are also included
|
Package vrraw offers aliases to all VR abbreviations as defined here: http://dicom.nema.org/medical/dicom/current/output/html/part05.html#table_6.2-1 Deprecated VRs from older editions are also included |