4 \page dcmmklut Create DICOM look-up tables
6 \page dcmmklut dcmmklut: Create DICOM look-up tables
9 \section synopsis SYNOPSIS
12 dcmmklut [options] dcmimg-out
15 \section description DESCRIPTION
17 The \b dcmmklut utility allows to create a variety of DICOM Modality,
18 Presentation and VOI look-up tables (LUT) and is intended for the creation
19 of test images. The utility is able to read an existing DICOM image file,
20 create a look up table according to the command line options, and write
21 the new object back to file. It is also possible to create a new object
22 containing the specified LUT without reading an existing DICOM image file.
23 This is e.g. useful to simply store different look-up tables in a DICOM-like
24 structure. As a default the output file is encoded with the same transfer
25 syntax used for the input file, but the transfer syntax can also be specified
26 as a command line option.
28 The LUT data can be derived from the shape of a gamma curve (default for the
29 gamma factor is 1) or imported from a file (currently the MAP format from
30 Ulead's PhotoImpact and a simple text format are supported). The input and
31 output width of the LUT can also be specified in the range allowed by the
32 DICOM standard. The interpolation of the input range is done by a polynomial
33 curve fitting algorithm.
35 In addition to the DICOM output file the LUT data can also be exported to a
36 tabbed text file which allows the easy visualization of the curves with a
37 common spread sheet application (e.g. Microsoft Excel).
39 \section parameters PARAMETERS
42 dcmimg-out DICOM output filename
45 \section options OPTIONS
47 \subsection general_options general options
50 print this help text and exit
53 print version information and exit
56 print expanded command line arguments
59 quiet mode, print no warnings and errors
62 verbose mode, print processing details
65 debug mode, print debug information
67 -ll --log-level [l]evel: string constant
68 (fatal, error, warn, info, debug, trace)
69 use level l for the logger
71 -lc --log-config [f]ilename: string
72 use config file f for the logger
75 \subsection lut_creation_options LUT creation options
80 create as Modality LUT
83 create as Presentation LUT
86 create as VOI LUT (default)
91 add to existing transform
92 (default for and only with --voi)
95 replace existing transform
96 (default for --modality and --presentation)
100 +Cg --gamma [g]amma: float
101 use gamma value (default: 1.0)
103 +Cm --map-file [f]ilename: string
104 read input data from MAP file
106 +Ct --text-file [f]ilename: string
107 read input data from text file
112 apply inverse GSDF (print presentation LUT in OD)
114 --min-density [v]alue: integer (0..65535, default: 20)
115 set min density to v (in hundreds of OD)
117 --max-density [v]alue: integer (0..65535, default: 300)
118 set max density to v (in hundreds of OD)
120 +Oi --illumination [v]alue: integer (0..65535, default: 2000)
121 set illumination to v (in cd/m^2)
123 +Or --reflection [v]alue: integer (0..65535, default: 10)
124 set reflected ambient light to v (in cd/m^2)
128 -b --bits [n]umber: integer
129 create LUT with n bit values (8..16, default: 16)
131 -e --entries [n]umber: integer
132 create LUT with n entries (1..65536, default: 256)
134 -f --first-mapped [n]umber: integer
135 first input value mapped (-31768..65535, default: 0)
137 -r --random [n]umber: unsigned integer
138 perform n randomly selected permutations on the LUT
140 -rs --random-seed [n]umber: unsigned integer
141 initialize the random-number generator with n
142 (default: 0, for reproducible results)
144 -o --order [n]umber: integer
145 use polynomial curve fitting algorithm with order n
148 -E --explanation [n]ame: string
149 LUT explanation (default: automatically created)
154 create byte-aligned LUT
155 (default for and only with 8 bit values)
158 create word-aligned LUT
159 (default for 9-16 bit values)
164 write LUT Data as OW (default)
170 write LUT Data as SS (minimal support)
173 \subsection file_options file options
175 +Fi --dicom-input [f]ilename: string
176 read dataset from DICOM file f
178 +Fo --text-output [f]ilename: string
179 write LUT data to tabbed text file f
184 Please check the DICOM standard for further restrictions on the look-up table
185 structure. Especially the number of bits per table entry might be restricted
188 \section logging LOGGING
190 The level of logging output of the various command line tools and underlying
191 libraries can be specified by the user. By default, only errors and warnings
192 are written to the standard error stream. Using option \e --verbose also
193 informational messages like processing details are reported. Option
194 \e --debug can be used to get more details on the internal activity, e.g. for
195 debugging purposes. Other logging levels can be selected using option
196 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
197 very severe error events, the application will usually terminate. For more
198 details on the different logging levels, see documentation of module "oflog".
200 In case the logging output should be written to file (optionally with logfile
201 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
202 can be used. This configuration file also allows for directing only certain
203 messages to a particular output stream and for filtering certain messages
204 based on the module or application where they are generated. An example
205 configuration file is provided in <em><etcdir>/logger.cfg</em>).
207 \section command_line COMMAND LINE
209 All command line tools use the following notation for parameters: square
210 brackets enclose optional values (0-1), three trailing dots indicate that
211 multiple values are allowed (1-n), a combination of both means 0 to n values.
213 Command line options are distinguished from parameters by a leading '+' or '-'
214 sign, respectively. Usually, order and position of command line options are
215 arbitrary (i.e. they can appear anywhere). However, if options are mutually
216 exclusive the rightmost appearance is used. This behaviour conforms to the
217 standard evaluation rules of common Unix shells.
219 In addition, one or more command files can be specified using an '@' sign as a
220 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
221 is replaced by the content of the corresponding text file (multiple
222 whitespaces are treated as a single separator unless they appear between two
223 quotation marks) prior to any further evaluation. Please note that a command
224 file cannot contain another command file. This simple but effective approach
225 allows to summarize common combinations of options/parameters and avoids
226 longish and confusing command lines (an example is provided in file
227 <em><datadir>/dumppat.txt</em>).
229 \section environment ENVIRONMENT
231 The \b dcmmklut utility will attempt to load DICOM data dictionaries specified
232 in the \e DCMDICTPATH environment variable. By default, i.e. if the
233 \e DCMDICTPATH environment variable is not set, the file
234 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
235 into the application (default for Windows).
237 The default behaviour should be preferred and the \e DCMDICTPATH environment
238 variable only used when alternative data dictionaries are required. The
239 \e DCMDICTPATH environment variable has the same format as the Unix shell
240 \e PATH variable in that a colon (":") separates entries. On Windows systems,
241 a semicolon (";") is used as a separator. The data dictionary code will
242 attempt to load each file specified in the \e DCMDICTPATH environment variable.
243 It is an error if no data dictionary can be loaded.
247 <em><datadir>/philips.lut</em> - sample LUT in text format
249 \section copyright COPYRIGHT
251 Copyright (C) 1998-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.