Categorygithub.com/suyashkumar/dicom
modulepackage
1.0.7
Repository: https://github.com/suyashkumar/dicom.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
19
Dependents
23
Files
2.2k SLOC

# README

dicom

High Performance Golang DICOM Medical Image Parser

: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

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

AllowMismatchPixelDataLength allows parser to ignore an error when the length calculated from elements do not match with value length.
AllowMissingMetaElementGroupLength allows parser to work around missing metaelement group length tag (0x0002,0x0000) by reading elements only in group 2.
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.
ExhaustElementChannel exhausts the channel iterator returned by Dataset.FlatIterator, ensuring that the underlying Go routine completes.
MustGetBytes attempts to get a Bytes value out of the provided Value, and will panic if it is unable to do so.
MustGetFloats attempts to get a Floats value out of the provided Value, and will panic if it is unable to do so.
MustGetInts attempts to get an Ints value out of the provided value, and will panic if it is unable to do so.
MustGetPixelDataInfo attempts to get a PixelDataInfo value out of the provided Value, and will panic if it is unable to do so.
MustGetStrings attempts to get a Strings value out of the provided Value, and will panic if it is unable to do so.
NewElement creates a new DICOM Element with the supplied tag and with a value built from the provided data.
NewParser returns a new Parser that points to the provided io.Reader, with bytesToRead bytes left to read.
NewValue creates a new DICOM value for the supplied data.
NewWriter returns a new Writer, that points to the provided io.Writer.
No description provided by the author
ParseFile parses the entire DICOM at the given filepath.
No description provided by the author
SkipMetadataReadOnNewParserInit makes NewParser skip trying to parse metadata.
SkipPixelData skips reading data from the PixelData tag, wherever it appears (e.g.
SkipProcessingPixelDataValue will attempt to skip processing the _value_ of any PixelData elements.
SkipValueTypeVerification returns WriteOption function that skips checking ValueType for concurrency with VR and casting.
SkipVRVerification returns a WriteOption that skips VR verification.
Write will write the input DICOM dataset to the provided io.Writer as a complete DICOM (including any header information if available).

# Constants

Bytes represents an underlying value of []byte.
Floats represents an underlying value of []float64.
Ints represents an underlying value of []int.
PixelData represents an underlying value of PixelDataInfo.
SequenceItem represents an underlying value of []*Element.
Sequences represents an underlying value of []SequenceItem.
Strings represents an underlying value of []string.

# Variables

ErrorElementNotFound indicates that the requested element was not found in the Dataset.
ErrorEndOfDICOM indicates to the callers of Parser.Next() that the DICOM has been fully parsed.
No description provided by the author
ErrorMagicWord indicates that the magic word was not found in the correct location in the DICOM.
ErrorMetaElementGroupLength indicates that the MetaElementGroupLength was not found where expected in the metadata.
ErrorMismatchPixelDataLength indicates that the size calculated from DICOM mismatch the VL.
ErrorMismatchValueTypeAndVR is for when there's a discrepancy between the ValueType and what the VR specifies.
ErrorOWRequiresEvenVL indicates that an element with VR=OW had a not even value length which is not allowed.
ErrorUnexpectedDataType indicates that an unexpected (not allowed) data type was sent to NewValue.
ErrorUnexpectedValueType indicates an unexpected value type was seen.
ErrorUnimplemented is for not yet finished things.
ErrorUnsupportedBitsAllocated indicates that the BitsAllocated in the NativeFrame PixelData is unsupported.
ErrorUnsupportedBitsPerSample indicates that the BitsPerSample in this Dataset is not supported when unpacking native PixelData.
ErrorUnsupportedVR indicates that this VR is not supported.

# Structs

Dataset represents a DICOM dataset, see https://dicom.nema.org/medical/dicom/current/output/html/part05.html#chapter_7.
Element represents a standard DICOM data element (see the DICOM standard: https://dicom.nema.org/medical/dicom/current/output/html/part05.html#sect_7.1 ).
FlatDatasetIterator is a stateful iterator over a Dataset.
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.
PixelDataInfo is a representation of DICOM PixelData.
SequenceItemValue is a Value that represents a single Sequence Item.
Writer is a struct that allows element-by element writing to a DICOM writer.

# Interfaces

Value represents a DICOM value.

# Type aliases

ParseOption represents an option that can be passed to NewParser.
ValueType is a type that represents the type of a Value.
WriteOption represents an option that can be passed to WriteDataset.