Skip to content

README.md

Latest commit

 

History

History
159 lines (110 loc) · 5.49 KB

README.md

File metadata and controls

159 lines (110 loc) · 5.49 KB

DCMTK-HTJ2K

A DCMTK codec library for encoding and decoding DICOM images using the High-Throughput JPEG 2000 (HTJ2K) compression and decompression technique.

Overview

DCMTK-HTJ2K provides HTJ2K codec support for DCMTK, enabling seamless compression and decompression of DICOM images using the HTJ2K standard. The library integrates OpenJPH for HTJ2K operations with DCMTK's DICOM handling capabilities.

Supported Transfer Syntaxes

  • High Throughput JPEG 2000 Image Compression - Lossless Only (1.2.840.10008.1.2.4.201)
  • High Throughput JPEG 2000 with RPCL Options Image Compression - Lossless Only (1.2.840.10008.1.2.4.202)
  • High Throughput JPEG 2000 Image Compression (1.2.840.10008.1.2.4.203)

Features

  • HTJ2K Encoding: Compress DICOM images using HTJ2K lossless and lossy compression.
  • HTJ2K Decoding: Decompress HTJ2K-encoded DICOM images.
  • DCMTK Integration: Seamless integration with DCMTK codec framework.
  • Configurable Parameters: Support for codeblock dimensions, progression order, number of decompositions, fragment sizes, and encoding options.
  • Cross Platform: Supports Linux, macOS, and Windows builds.
  • WebAssembly: Optional Emscripten build producing a C++ static library that you can link into other WebAssembly projects to build wasm for browser or Node.js (see Building for WebAssembly).

Dependencies

  • DCMTK (3.6.9 or higher)
  • OpenJPH (0.26.0 or higher)
  • CMake (3.12.0 or higher)

Building

Quick Build

./build.sh [Release|Debug]

The build script accepts an optional build configuration parameter (Release or Debug). If not specified, it defaults to Release.

The provided build script automatically downloads, builds, and installs dependencies. It also builds and installs DCMTK-HTJ2K:

  • Library files to build/ReleaseOrDebug/lib/.
  • Header files to build/ReleaseOrDebug/include/DCMTKHTJ2K/.
  • CMake configuration files to build/ReleaseOrDebug/lib/cmake/DCMTKHTJ2K/.

Windows (MSVC)

From x64 Native Tools Command Prompt for VS 2022 (or with MSVC and CMake on PATH):

build.bat [Release|Debug]

Defaults to Release if omitted. Output is under build\Release or build\Debug.

Building for WebAssembly (WASM)

The project can be built for WebAssembly using Emscripten. The result is a C++ static library, not a standalone wasm binary. You link this library into your own Emscripten project to produce the final wasm file for browser or Node.js.

Prerequisites

Build

From the project root (e.g. in a normal Command Prompt or PowerShell where emsdk and MinGW are on PATH):

build_wasm.bat

This script will:

  1. Clone (if needed) DCMTK and OpenJPH into ots_wasm/
  2. Check out DCMTK 3.6.9 and OpenJPH 0.26.0
  3. Apply the Emscripten compatibility patch to DCMTK (see patches/)
  4. Build DCMTK and OpenJPH with Emscripten, then build DCMTK-HTJ2K

Output

  • Libraries and headers: build_wasm\Release\ (lib, include, CMake config)
  • Static library: build_wasm\Release\lib\libDCMTKHTJ2K.a — Emscripten-built archive; link this into your application’s Emscripten build to produce the final wasm file.

Patches

  • patches/dcmtk-ofwhere-emscripten.patch — adds an Emscripten implementation of OFgetExecutablePath in DCMTK’s ofwhere.c (no real executable path in WASM). See patches/README.md for details.

Usage

Registering Encoder

#include "dcmtkhtj2k/djencode.h"

// Register HTJ2K encoder with default parameters
HtJ2kEncoderRegistration::registerCodecs();

// Or with custom parameters
HtJ2kEncoderRegistration::registerCodecs(
    OFTrue,             // jp2k_optionsEnabled
    5,                  // jp2k_decompositions (decompositions)
    64,                 // jp2k_cblkwidth (codeblock width)
    64,                 // jp2k_cblkheight (codeblock height)
    EJ2KPO_default,     // jp2k_progressionOrder (progression order)
    OFTrue,             // preferCookedEncoding
    0,                  // fragmentSize (0 = unlimited)
    OFTrue,             // createOffsetTable
    EJ2KUC_default,     // uidCreation
    OFFalse             // convertToSC
);

Registering Decoder

#include "dcmtkhtj2k/djdecode.h"

// Register HTJ2K decoder with default parameters
HtJ2kDecoderRegistration::registerCodecs();

// Or with custom parameters
HtJ2kDecoderRegistration::registerCodecs(
    EJ2KUC_default,     // uidCreation
    EJ2KPC_restore,     // planarConfig
    OFFalse             // ignoreOffsetTable
);

Cleanup

// Cleanup encoder
HtJ2kEncoderRegistration::cleanup();

// Cleanup decoder
HtJ2kDecoderRegistration::cleanup();

Using in Your Project

CMake Integration

find_package(DCMTKHTJ2K REQUIRED)
target_link_libraries(your_target DCMTKHTJ2K)

API Documentation

The library provides the following main classes:

  • HtJ2kEncoderRegistration: Singleton for registering HTJ2K encoder.
  • HtJ2kDecoderRegistration: Singleton for registering HTJ2K decoder.
  • HtJ2kCodecParameter: Codec configuration parameters.
  • HtJ2kEncoder: HTJ2K encoding implementation.
  • HtJ2kDecoder: HTJ2K decoding implementation.

License

DCMTK-HTJ2K is released under the MIT License.