Add optional support for JPEG-LS, JPEG and JPEG2000 transfer syntaxes

.github/workflows/bench_pr.yml

@@ -13,13 +13,15 @@ jobs:
         go-version: 1.22
       id: go
 
-    - name: Check out code 
+    - name: Check out code
       uses: actions/checkout@v1
 
     - name: Get dependencies
-      run: | 
+      run: |
+            sudo apt-get update
+            sudo apt-get install -y pkg-config swig libcharls-dev libdcmtk-dev libopenjp2-7-dev
             go mod download
-  
+
     - name: Benchmark against GITHUB_BASE_REF
       run: |
        go install golang.org/x/perf/cmd/benchstat@latest
@@ -32,4 +34,4 @@ jobs:
        git log -1 --format="%H"
        go test -bench=. -benchmem -benchtime=10x -count=7 > $HOME/old.txt
        $GOBIN/benchstat $HOME/old.txt $HOME/new.txt
-       
+

.github/workflows/bench_push.yml

@@ -13,13 +13,15 @@ jobs:
         go-version: 1.22
       id: go
 
-    - name: Check out code 
+    - name: Check out code
       uses: actions/checkout@v1
 
     - name: Get dependencies
-      run: | 
+      run: |
+            sudo apt-get update
+            sudo apt-get install -y pkg-config swig libcharls-dev libdcmtk-dev libopenjp2-7-dev
             go mod download
-  
+
     - name: Benchmark (against HEAD~1)
       run: |
        go install golang.org/x/perf/cmd/benchstat@latest

.github/workflows/go.yml

@@ -13,20 +13,22 @@ jobs:
         go-version: 1.22
       id: go
 
-    - name: Check out code 
+    - name: Check out code
       uses: actions/checkout@v1
 
     - name: Get dependencies
       run: |
+            sudo apt-get update
+            sudo apt-get install -y pkg-config swig libcharls-dev libdcmtk-dev libopenjp2-7-dev
             go mod download
 
 
     - name: Build
       run: |
             make build-fast
-   
+
     - name: Test
       run: |
             make test
-       
+
 

README.md

@@ -2,10 +2,10 @@
   <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> 
+  <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> 
+    <a href="https://goreportcard.com/report/github.com/suyashkumar/dicom"><img src="https://goreportcard.com/badge/github.com/suyashkumar/dicom" alt=""></a>
   </p>
 </p>
 
@@ -24,9 +24,15 @@ Some notable features:
 - [x] Enhanced testing and benchmarking support
 - [x] Modern, canonical Go.
 
+### Compressed *Pixel Data*
+#### JPEG, JPEG-LS and JPEG 2000
+Converting JPEG compressed *Pixel Data* to an uncompressed *Native Data* requires installing one or more additional C/C++ libraries. For information on which libraries are required, see the [DICOM Codecs for pixel data](https://github.com/suyashkumar/dicom/blob/main/pkg/codec/README.md).
+
+Compressing data into one of the JPEG formats is not currently supported.
+
 ## 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:
-```go 
+```go
 
 dataset, _ := dicom.ParseFile("testdata/1.dcm", nil) // See also: dicom.Parse which has a generic io.Reader API.
 
@@ -54,15 +60,15 @@ wget -qO- "https://getbin.io/suyashkumar/dicom" | tar xvz
 ```
 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). 
+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:
 ```sh
 make
 ```
-Which will build the dicomutil binary and include it in a `build/` folder in your current working directory. 
+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:
 
@@ -71,21 +77,21 @@ go build -o dicomutil ./cmd/dicomutil
 ```
 
 ## History
-Here's a little more history on this repository for those who are interested! 
+Here's a little more history on this repository for those who are interested!
 
 ### v0
 The v0 [suyashkumar/dicom](https://github.com/suyashkumar/dicom) started off as a hard fork of [go-dicom](https://github.com/gillesdemey/go-dicom) which was not being maintained actively anymore (with the [original author being supportive of my fork](https://www.reddit.com/r/golang/comments/bnu47l/high_performance_dicom_medical_image_parser_in/en9hp6h?utm_source=share&utm_medium=web2x&context=3)--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. 
+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`](https://github.com/suyashkumar/dicom/tree/s/1.0-rewrite) branch. 
+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`](https://github.com/suyashkumar/dicom/tree/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](https://www.segmed.ai/) for their help with validation and other contributions to the library. 
+* <img src="https://user-images.githubusercontent.com/6299853/90325771-b23f2e80-df34-11ea-9d18-5c33b69c2746.png" width="110px" align="left"/> [Segmed](https://www.segmed.ai/) for their help with validation and other contributions to the library.
 * Original [go-dicom](https://github.com/gillesdemey/go-dicom)
 * Grailbio [go-dicom](https://github.com/grailbio/go-dicom) -- commits from their fork were applied to ours
 * GradientHealth for supporting work I did on this while there [gradienthealth/dicom](https://github.com/gradienthealth/dicom)

pkg/codec/README.md

@@ -0,0 +1,40 @@
+# Codec
+DICOM codec for decoding JPEG/JPEG-LS/JPEG2000 images, with a focus on providing support for [suyashkumar/dicom](https://github.com/suyashkumar/dicom).
+
+### Prerequisites
+To be able to decompress compressed DICOM pixel data, you first have to install the corresponding libraries, that are able to handle the format the data is encoded in:
+
+- LINUX
+```bash
+apt-get install pkg-config swig libcharls-dev libdcmtk-dev libopenjp2-7-dev
+```
+- MACOS
+```bash
+brew install swig pkg-config
+brew install dcmtk
+brew install openjpeg
+brew install team-charls/tap/charls
+```
+
+Generate the necessary C++ wrapper code to allow Go to bind to it. You need to do this each time the dependent *.h or *.cxx files change.
+```bash
+swig -go -cgo -c++ -intgosize 64 codec.i
+```
+
+## Usage
+```go
+import (
+	"github.com/suyashkumar/dicom"
+	"github.com/suyashkumar/dicom/pkg/tag"
+	_ "github.com/suyashkumar/dicom/pkg/codec"
+)
+
+func main() {
+    dataset, err := dicom.ParseFile("testdata/1.dcm", nil)
+    pixelDataElem, err := dataset.FindElementByTag(tag.PixelData)
+    pixelData := dicom.MustGetPixelDataInfo(pixelDataElem.Value)
+    encapsulatedFrame, err := pixelData.Frames[0].GetEncapsulatedFrame()
+    image, err = encapsulatedFrame.GetImage()
+    ...
+}
+```