|
DCMTK
Version 3.6.9
OFFIS DICOM Toolkit
|
dcmcjp2k [options] dcmfile-in dcmfile-out
The dcmcjp2k utility reads an uncompressed DICOM image (dcmfile-in), performs a JPEG 2000 compression (i. e. conversion to an encapsulated DICOM transfer syntax) and writes the converted image to an output file (dcmfile-out).
dcmfile-in DICOM input filename to be converted
("-" for stdin)
dcmfile-out DICOM output filename
("-" for stdout)
-h --help
print this help text and exit
--version
print version information and exit
--arguments
print expanded command line arguments
-q --quiet
quiet mode, print no warnings and errors
-v --verbose
verbose mode, print processing details
-d --debug
debug mode, print debug information
-ll --log-level [l]evel: string constant
(fatal, error, warn, info, debug, trace)
use level l for the logger
-lc --log-config [f]ilename: string
use config file f for the logger
input file format:
+f --read-file
read file format or data set (default)
+fo --read-file-only
read file format only
-f --read-dataset
read data set without file meta information
input transfer syntax:
-t= --read-xfer-auto
use TS recognition (default)
-td --read-xfer-detect
ignore TS specified in the file meta header
-te --read-xfer-little
read with explicit VR little endian TS
-tb --read-xfer-big
read with explicit VR big endian TS
-ti --read-xfer-implicit
read with implicit VR little endian TS
compatibility (only with --encode-lossy):
+Ma --accept-acr-nema
accept ACR-NEMA images without photometric interpretation
+Mp --accept-palettes
accept incorrect palette attribute tags (0028,111x) and (0028,121x)
codec selection:
# The codec selection options are available only when dcmcjp2k
# was compiled with OpenJPEG support.
+cl --openjpeg-lossy
encode lossy compressed images using OpenJPEG,
lossless images using JasPer (default)
+co --openjpeg
always encode using OpenJPEG codec
+cj --jasper
always encode using JasPer codec
JPEG 2000 process:
+el --encode-lossless
encode JPEG 2000 lossless only TS (default)
# This options selects the JPEG 2000 lossless only transfer syntax
# and performs a lossless compression
+ex --encode-lossless2
encode JPEG 2000 TS lossless
# This options selects the JPEG 2000 (lossy and lossless) transfer syntax
# and performs a lossless compression
+ey --encode-lossy
encode JPEG 2000 TS lossy
# This options selects the JPEG 2000 (lossy and lossless) transfer syntax
# and performs a lossy compression
JPEG 2000 bit rate (lossy only):
-r --compression-ratio [r]atio: double, 0 < r < 1.0 (default: 0.2)
compress with compression ratio r
# This option specifies the compression ratio for lossy compression.
# The default ratio of 0.2 means that the image will be compressed
# to 20% of the original size. The original size is caculated based
# on Bits Stored, not Bits Allocated (i.e. may be smaller than the
# size of the raw Pixel Data element)
-s --compressed-size [s]ize: integer
compress each frame to approx. s bytes
# This option requests the codec to compress each frame of the DICOM
# image to a approximate absolute size, which must be specified in
# bytes.
JPEG 2000 compression bit depth (lossy only):
+dl --depth-limit [b]its: 2..16 (default: 16)
limit image bit depth to b bits/sample
# Limit bit depth to given value. Image is down-sampled if and
# only if the bit depth exceeds the given limit.
+df --depth-force [b]its: 2..16
force image bit depth to b bits/sample
# Force bit depth to given value. Image is upsampled or downsampled
# to match the given bit depth.
+do --depth-original
compress with original bit depth,
refuse if bit depth too large
# Compress image with original bit depth, fail if bit depth is
# too large (> 16 bits/sample).
JPEG 2000 coordinate system:
# These options modify the JPEG 2000 coordinate system.
# The meaning of these parameters is documented in ISO 15444-1.
--image-offset-x [o]ffset: integer (default: 0)
horizontal image area offset
--image-offset-y [o]ffset: integer (default: 0)
vertical image area offset
--tile-offset-x offset: integer (default: 0)
horizontal tiling grid offset
--tile-offset-y [o]ffset: integer (default: 0)
vertical tiling grid offset
--tile-size-x [s]ize: integer (default: image width)
nominal tile width
--tile-size-y [s]ize: integer (default: image height)
nominal tile height
--codeblock-size-x [s]ize: 2..10 (default: 6)
base 2 log of nominal code block width
--codeblock-size-y [s]ize: 2..10 (default: 6)
base 2 log of nominal code block height
--precinct-size-x [s]ize: 0..15 (default: 15)
base 2 log of precinct width
--precinct-size-y [s]ize: 0..15 (default: 15)
base 2 log of precinct height
JPEG 2000 error resilience:
# These options cause the JPEG 2000 encoder to produce a
# bitstream with higher error resilience at the expense of
# a larger compressed file size.
--generate-sop
generate SOP (Start of Packet) markers
--generate-eph
generate EPH (End of Packet Header) markers
--use-seg-symbols
use segmentation symbols
--use-predict-term
use predictable termination
other JPEG 2000 encoding options:
-l --levels [l]evels: integer (default: 6)
number of wavelet resolution levels
-gb --guard-bits [b]its: 0..7 (default: 2)
use b guard bits during quantization
(not supported by OpenJPEG codec)
-po --progression LRCP/RLCP/RPCL/PCRL/CPRL (default: LRCP)
progression order for layer, resolution, component and position
+al --add-quality-layer [r]atio: double, 0 < r < 1.0
add intermediate quality layer with ratio r. This option can be
specified multiple times. Values must be specified in
increasing order
--lazy
use lazy coding mode, no arithmetic coding
--terminate-all
terminate all coding passes
--vertical-stripe
vertically stripe causal contexts
--reset-models
reset probability models after each coding pass
-ic --image-comment [c]omment: string
comment to write into the JPEG2000 header
# By default, the JasPer library version string is used.
lossless compression:
# The lossless encoder supports two different modes of operation. In
# raw mode, the pixel data cells are fed into the JPEG 2000 codec
# "as is", including unused bits that may contain overlays or just
# garbage. The raw mode requires a Bits Allocated value of 8 or 16
# and works with all photometric interpretations. The cooked encoder
# only processes monochrome, RGB and YBR_FULL images, and only
# unsigned color images. It moves overlays into (60xx,3000) Overlay
# Data if present and only compresses the image bits. It also
# correctly forwards signed/unsigned representation to the JPEG 2000
# codec, which may improve compression ratio. If one mode is unable
# to process an image, the other mode is automatically invoked. In
# general, both modes provide a conformant true lossless
# compression. However, the compression ratio might slightly differ
# and not all readers might correctly support both modes.
+pc --prefer-cooked
prefer cooked encoder mode (default)
+pr --prefer-raw
prefer raw encoder mode
compression color space conversion:
# JPEG 2000 defines two multi-component transformations that are
# mainly intended for RGB color images, the reversible multi-
# component transform (RCT) for lossless compression and the
# irreversible multi-component transform (ICT) for lossy compression
# that is identical to the YCbCr conversion normally used with lossy
# JPEG compression. The transformations can be disabled, but this
# usually only decreases the compression ratio or image quality.
+cy --color-mct
enable RCT/ICT for RGB color images (default)
+cr --color-rgb
disable RCT/ICT for RGB color images
+cm --monochrome
convert color images to monochrome (lossy only)
# The JPEG 2000 algorithm permits the compression of signed pixel
# data. The following options define the use of the sign flag
# in the JPEG 2000 bitstream if the DICOM image contains signed
# pixel data, i.e. (0028,0103) Pixel Representation contains "1".
# By default, the JPEG 2000 encoder is then asked to treat the
# pixel data as signed. This ensures that the sign flag in the
# compressed bitstream is compliant with the DICOM Pixel
# Representation attribute, i.e. works correctly even if the decoder
# replaces the content of the attribute with the information found
# in the JPEG 2000 bitstream. However, under certain circumstances
# (raw mode encoding with BitsStored < BitsAllocated), this will
# cause the compression rate to go down significantly. The alternative
# (which was the only available algorithm until release 3.6.0)
# always sets the JPEG 2000 sign flag to "unsigned". This is safe
# since the compression is lossless anyway, but may fail with a
# decoder replacing PixelRepresentation from the compressed bitstream.
handling of sign bit in lossless encoding:
+bs --bitstream-signed
signed bitstream if image is signed (default)
-bs --bitstream-unsigned
always encode unsigned bitstreamenable/disable pre-processing:
+P --preprocessing
enable image pre-processing (default)
-P --no-preprocessing
disable image pre-processing
# Disable image pre-processing before lossy compression, other than removal
# of overlay data. The image pre-processing options below cannot be combined
# with this option. This type of compression will be refused when
# Modality LUT, VOI LUT, Presentation LUT or Palette Color LUT are present.
VOI windowing for monochrome images:
-W --no-windowing
no VOI windowing (default)
# No window level/width is "burned" into monochrome images prior to
# compression. See notes below on pixel scaling and rescale slope
# and intercept encoding.
+Wi --use-window [n]umber: integer
use the n-th VOI window from image file
# Apply the n-th window center/width encoded in the image data prior
# to compression.
+Wl --use-voi-lut [n]umber: integer
use the n-th VOI look up table from image file
# Apply the n-th VOI LUT encoded in the image data prior
# to compression.
+Wm --min-max-window
compute VOI window using min-max algorithm
# Compute and apply a window center and width that covers the
# range from the smallest to the largest occuring pixel value.
+Wn --min-max-window-n
compute VOI window using min-max algorithm,
ignoring extreme values
# Compute and apply a window center and width that covers the
# range from the second smallest to the second largest occuring
# pixel value. This is useful if the background is set to an
# artificial black (padding value) or if white overlays are burned
# into the image data which should not be considered for the window
# computation.
+Wr --roi-min-max-window [l]eft [t]op [w]idth [h]eight: integer
compute ROI window using min-max algorithm,
region of interest is specified by l,t,w,h
# This option works like --min-max-window but only considers the given
# region of interest inside the image.
+Wh --histogram-window [n]umber: integer
compute VOI window using Histogram algorithm,
ignoring n percent
# Compute a histogram of the image data and apply window center
# and width such than n% of the image data are ignored for the window
# computation
+Ww --set-window [c]enter [w]idth: float
compute VOI window using center c and width w
# Apply the given window center/width prior to compression.
pixel scaling for monochrome images (--no-windowing):
+sp --scaling-pixel
scale using min/max pixel value (default)
# Monochrome image pixel values are always scaled to make use of the
# pixel range available with the selected JPEG process as good as
# possible. This option selects a scaling based on the minimum and
# maximum pixel value occuring in the image. This often leads to
# significantly better image quality, but may cause different
# compressed images within one series to have different values for
# rescale slope and intercept, which is a problem if a presentation
# state for one series is to be created.
+sr --scaling-range
scale using min/max range
# This options selects a scaling based on the pixel range as defined
# by the stored bits, pixel representation and modality transform,
# without consideration of the minimum and maximum value really
# used within the image.
rescale slope/intercept encoding for monochrome (--no-windowing):
+ri --rescale-identity
encode identity modality rescale (default)
Never used for CT images
# This options prevents the creation of a modality transformation
# other than an identity transformation (which is required for
# many DICOM IODs). Window center/width settings encoded
# in the image are adapted, VOI LUTs are removed.
+rm --rescale-map
use modality rescale to scale pixel range
Never used for XA/RF/XA Biplane images
# This option causes the creation of a modality rescale slope and
# intercept that maps the decompressed image data back to their
# original range. This keeps all VOI transformations valid but
# requires that the DICOM IOD supports a modality rescale slope
# and intercept transformation other than identity.
encapsulated pixel data fragmentation:
+ff --fragment-per-frame
encode each frame as one fragment (default)
# This option causes the creation of one compressed fragment for each
# frame (recommended).
+fs --fragment-size [s]ize: integer
limit fragment size to s kbytes
# This option limits the fragment size which may cause the creation of
# multiple fragments per frame.
basic offset table encoding:
+ot --offset-table-create
create offset table (default)
# This option causes the creation of a valid offset table for the
# compressed JPEG fragments.
-ot --offset-table-empty
leave offset table empty
# This option causes the creation of an empty offset table
# for the compressed JPEG fragments.
SOP Class UID:
+cd --class-default
keep SOP Class UID (default)
# Keep the SOP Class UID of the source image.
+cs --class-sc
convert to Secondary Capture Image (implies --uid-always)
# Convert the image to Secondary Capture. In addition to the SOP Class
# UID, all attributes required for a valid secondary capture image are
# added. A new SOP instance UID is always assigned.
SOP Instance UID:
+ud --uid-default
assign new UID if lossy compression (default)
# Assigns a new SOP instance UID if the compression is lossy JPEG.
+ua --uid-always
always assign new UID
# Unconditionally assigns a new SOP instance UID.
+un --uid-never
never assign new UID
# Never assigns a new SOP instance UID.
post-1993 value representations:
+u --enable-new-vr
enable support for new VRs (UN/UT) (default)
-u --disable-new-vr
disable support for new VRs, convert to OB
group length encoding:
+g= --group-length-recalc
recalculate group lengths if present (default)
+g --group-length-create
always write with group length elements
-g --group-length-remove
always write without group length elements
length encoding in sequences and items:
+e --length-explicit
write with explicit lengths (default)
-e --length-undefined
write with undefined lengths
data set trailing padding:
-p= --padding-retain
do not change padding (default)
-p --padding-off
no padding
+p --padding-create [f]ile-pad [i]tem-pad: integer
align file on multiple of f bytes
and items on multiple of i bytes
The dcmcjp2k utility compresses DICOM images of all SOP classes. Special handling has been implemented for lossy compression of CT images (where the modality transformation is required to create Hounsfield units) and the XA/RF/Biplane SOP classes (where the modality transformation has "inversed" semantics). However, dcmcjp2k does not attempt to ensure that the compressed image still complies with all restrictions of the object's IOD.
A few examples:
The user is responsible for making sure that the compressed images he creates are compliant with the DICOM standard. If in question, the dcmcjp2k utility allows to convert an image to secondary capture - this SOP class does not pose restrictions as the ones mentioned above.
dcmcjp2k supports the following transfer syntaxes for input (dcmfile-in):
LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*) BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
(*) if compiled with zlib support enabled
dcmcjp2k supports the following transfer syntaxes for output (dcmfile-out):
JPEG2000LosslessOnlyTransferSyntax 1.2.840.10008.1.2.4.90 JPEG2000TransferSyntax 1.2.840.10008.1.2.4.91
The level of logging output of the various command line tools and underlying libraries can be specified by the user. By default, only errors and warnings are written to the standard error stream. Using option –verbose also informational messages like processing details are reported. Option –debug can be used to get more details on the internal activity, e.g. for debugging purposes. Other logging levels can be selected using option –log-level. In –quiet mode only fatal errors are reported. In such very severe error events, the application will usually terminate. For more details on the different logging levels, see documentation of module "oflog".
In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option –log-config can be used. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated. An example configuration file is provided in <etcdir>/logger.cfg).
All command line tools use the following notation for parameters: square brackets enclose optional values (0-1), three trailing dots indicate that multiple values are allowed (1-n), a combination of both means 0 to n values.
Command line options are distinguished from parameters by a leading '+' or '-' sign, respectively. Usually, order and position of command line options are arbitrary (i.e. they can appear anywhere). However, if options are mutually exclusive the rightmost appearance is used. This behaviour conforms to the standard evaluation rules of common Unix shells.
In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e.g. @command.txt). Such a command argument is replaced by the content of the corresponding text file (multiple whitespaces are treated as a single separator unless they appear between two quotation marks) prior to any further evaluation. Please note that a command file cannot contain another command file. This simple but effective approach allows to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file <datadir>/dumppat.txt).
The dcmcjp2k utility will attempt to load DICOM data dictionaries specified in the DCMDICTPATH environment variable. By default, i.e. if the DCMDICTPATH environment variable is not set, the file <datadir>/dicom.dic will be loaded unless the dictionary is built into the application (default for Windows).
The default behaviour should be preferred and the DCMDICTPATH environment variable only used when alternative data dictionaries are required. The DCMDICTPATH environment variable has the same format as the Unix shell PATH variable in that a colon (":") separates entries. On Windows systems, a semicolon (";") is used as a separator. The data dictionary code will attempt to load each file specified in the DCMDICTPATH environment variable. It is an error if no data dictionary can be loaded.
dcmdjp2k(1)
Copyright (C) 2004-2024 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.