4 \page dcmcjpls Encode DICOM file to JPEG-LS transfer syntax
6 \page dcmcjpls dcmcjpls: Encode DICOM file to JPEG-LS transfer syntax
9 \section synopsis SYNOPSIS
12 dcmcjpls [options] dcmfile-in dcmfile-out
15 \section description DESCRIPTION
17 The \b dcmcjpls utility reads an uncompressed DICOM image (\e dcmfile-in),
18 performs a JPEG-LS compression (i. e. conversion to an encapsulated DICOM
19 transfer syntax) and writes the converted image to an output file
22 \section parameters PARAMETERS
25 dcmfile-in DICOM input filename to be converted
27 dcmfile-out DICOM output filename
30 \section options OPTIONS
32 \subsection general_options general options
35 print this help text and exit
38 print version information and exit
41 print expanded command line arguments
44 quiet mode, print no warnings and errors
47 verbose mode, print processing details
50 debug mode, print debug information
52 -ll --log-level [l]evel: string constant
53 (fatal, error, warn, info, debug, trace)
54 use level l for the logger
56 -lc --log-config [f]ilename: string
57 use config file f for the logger
60 \subsection input_options input options
65 read file format or data set (default)
71 read data set without file meta information
73 input transfer syntax:
76 use TS recognition (default)
78 -td --read-xfer-detect
79 ignore TS specified in the file meta header
81 -te --read-xfer-little
82 read with explicit VR little endian TS
85 read with explicit VR big endian TS
87 -ti --read-xfer-implicit
88 read with implicit VR little endian TS
91 \subsection JPEG_LS_encoding_options JPEG-LS encoding options
96 encode JPEG-LS lossless only TS (default)
98 # This options selects the JPEG-LS lossless only transfer syntax
99 # and performs a lossless compression.
101 +en --encode-nearlossless
102 encode JPEG-LS near-lossless TS (NEAR: 2)
104 # This options selects the JPEG-LS lossy transfer syntax
105 # and performs a near-lossless compression.
107 JPEG-LS bit rate (near-lossless only):
109 +md --max-deviation [d]eviation: integer (default: 2)
110 defines maximum deviation for an encoded pixel
112 # This option specifies the maximum deviation for a single pixel from
113 # the original pixel value.
115 lossless compression:
118 prefer raw encoder mode (default)
120 # This option enables the raw encoder. The raw encoder encodes the
121 # complete pixel cell as it was read from the source image without
122 # performing any modifications.
125 prefer cooked encoder mode
127 # This option enables the cooked encoder. The cooked encoder moves
128 # overlay data to separate tags (60xx,3000) and only encodes the
129 # stored bits in each pixel.
133 +t1 --threshold1 [t]hreshhold: integer (default for 8 bpp: 3)
134 set JPEG-LS encoding parameter threshold 1
136 +t2 --threshold2 [t]hreshhold: integer (default for 8 bpp: 7)
137 set JPEG-LS encoding parameter threshold 2
139 +t3 --threshold3 [t]hreshhold: integer (default for 8 bpp: 21)
140 set JPEG-LS encoding parameter threshold 3
142 +rs --reset [r]eset: integer (default: 64)
143 set JPEG-LS encoding parameter reset
145 +lm --limit [l]imit: integer (default: 0)
146 set JPEG-LS encoding parameter limit
150 +il --interleave-line
151 force line-interleaved JPEG-LS images (default)
153 # This flag forces line-interleaved mode for the resulting image.
154 # In line-interleave mode each line from the source image is
155 # compressed separately for each component and then the next line
158 +is --interleave-sample
159 force sample-interleaved JPEG-LS images
161 # This flag forces sample-interleaved mode for the resulting image.
162 # In sample-interleave mode each pixel's components are encoded before
163 # the next pixe is encoded.
165 +in --interleave-none
166 force uninterleaved JPEG-LS images
168 # This flag forces uninterleaved mode for the resulting image.
169 # In this mode, each of the image's components are completely encoded
170 # before the next component is handled.
172 +iv --interleave-default
173 use the fastest possible interleave mode
175 # This flag selects an interleave mode based on the source image's mode.
176 # If possible, the image is not converted to a different interleave mode.
179 \subsection enc_pix_data_encoding_opt encapsulated pixel data encoding options
181 encapsulated pixel data fragmentation:
183 +ff --fragment-per-frame
184 encode each frame as one fragment (default)
186 # This option causes the creation of one compressed fragment for each
187 # frame (recommended).
189 +fs --fragment-size [s]ize: integer
190 limit fragment size to s kbytes
192 # This option limits the fragment size which may cause the creation of
193 # multiple fragments per frame.
195 basic offset table encoding:
197 +ot --offset-table-create
198 create offset table (default)
200 # This option causes the creation of a valid offset table for the
201 # compressed JPEG fragments.
203 -ot --offset-table-empty
204 leave offset table empty
206 # This option causes the creation of an empty offset table
207 # for the compressed JPEG fragments.
212 keep SOP Class UID (default)
214 # Keep the SOP Class UID of the source image.
217 convert to Secondary Capture Image (implies --uid-always)
219 # Convert the image to Secondary Capture. In addition to the SOP Class
220 # UID, all attributes required for a valid secondary capture image are
221 # added. A new SOP instance UID is always assigned.
226 assign new UID if lossy compression (default)
228 # Assigns a new SOP instance UID if the compression is lossy JPEG.
231 always assign new UID
233 # Unconditionally assigns a new SOP instance UID.
238 # Never assigns a new SOP instance UID.
241 \subsection output_options output options
243 post-1993 value representations:
246 enable support for new VRs (UN/UT) (default)
249 disable support for new VRs, convert to OB
251 group length encoding:
253 +g= --group-length-recalc
254 recalculate group lengths if present (default)
256 +g --group-length-create
257 always write with group length elements
259 -g --group-length-remove
260 always write without group length elements
262 length encoding in sequences and items:
265 write with explicit lengths (default)
267 -e --length-undefined
268 write with undefined lengths
270 data set trailing padding:
273 do not change padding (default)
278 +p --padding-create [f]ile-pad [i]tem-pad: integer
279 align file on multiple of f bytes
280 and items on multiple of i bytes
285 The \b dcmcjpls utility compresses DICOM images of all SOP classes. However,
286 \b dcmcjpls does not attempt to ensure that the compressed image still
287 complies with all restrictions of the object's IOD.
289 The user is responsible for making sure that the compressed images he creates
290 are compliant with the DICOM standard. If in question, the \b dcmcjpls utility
291 allows to convert an image to secondary capture - this SOP class does not pose
292 restrictions as the ones mentioned above.
294 \section transfer_syntaxes TRANSFER SYNTAXES
296 \b dcmcjpls supports the following transfer syntaxes for input
300 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
301 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
302 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
303 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
306 (*) if compiled with zlib support enabled
308 \b dcmcjpls supports the following transfer syntaxes for output
312 JPEGLSLosslessTransferSyntax 1.2.840.10008.1.2.4.80
313 JPEGLSLossyTransferSyntax 1.2.840.10008.1.2.4.81
316 \section logging LOGGING
318 The level of logging output of the various command line tools and underlying
319 libraries can be specified by the user. By default, only errors and warnings
320 are written to the standard error stream. Using option \e --verbose also
321 informational messages like processing details are reported. Option
322 \e --debug can be used to get more details on the internal activity, e.g. for
323 debugging purposes. Other logging levels can be selected using option
324 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
325 very severe error events, the application will usually terminate. For more
326 details on the different logging levels, see documentation of module "oflog".
328 In case the logging output should be written to file (optionally with logfile
329 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
330 can be used. This configuration file also allows for directing only certain
331 messages to a particular output stream and for filtering certain messages
332 based on the module or application where they are generated. An example
333 configuration file is provided in <em><etcdir>/logger.cfg</em>).
335 \section command_line COMMAND LINE
337 All command line tools use the following notation for parameters: square
338 brackets enclose optional values (0-1), three trailing dots indicate that
339 multiple values are allowed (1-n), a combination of both means 0 to n values.
341 Command line options are distinguished from parameters by a leading '+' or '-'
342 sign, respectively. Usually, order and position of command line options are
343 arbitrary (i.e. they can appear anywhere). However, if options are mutually
344 exclusive the rightmost appearance is used. This behaviour conforms to the
345 standard evaluation rules of common Unix shells.
347 In addition, one or more command files can be specified using an '@' sign as a
348 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
349 is replaced by the content of the corresponding text file (multiple
350 whitespaces are treated as a single separator unless they appear between two
351 quotation marks) prior to any further evaluation. Please note that a command
352 file cannot contain another command file. This simple but effective approach
353 allows to summarize common combinations of options/parameters and avoids
354 longish and confusing command lines (an example is provided in file
355 <em><datadir>/dumppat.txt</em>).
357 \section environment ENVIRONMENT
359 The \b dcmcjpls utility will attempt to load DICOM data dictionaries specified
360 in the \e DCMDICTPATH environment variable. By default, i.e. if the
361 \e DCMDICTPATH environment variable is not set, the file
362 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
363 into the application (default for Windows).
365 The default behaviour should be preferred and the \e DCMDICTPATH environment
366 variable only used when alternative data dictionaries are required. The
367 \e DCMDICTPATH environment variable has the same format as the Unix shell
368 \e PATH variable in that a colon (":") separates entries. On Windows systems,
369 a semicolon (";") is used as a separator. The data dictionary code will
370 attempt to load each file specified in the \e DCMDICTPATH environment variable.
371 It is an error if no data dictionary can be loaded.
373 \section see_also SEE ALSO
377 \section copyright COPYRIGHT
379 Copyright (C) 2009-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.