Debian Codegraph @

upstream/debian-unstable/man1/jpegtopnm.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Jpegtopnm User Manual" 1 "20 March 2023" "netpbm documentation"
7
8 .SH NAME
9 jpegtopnm - convert JPEG/JFIF file to PPM or PGM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBjpegtopnm\fP
15 [\fB-dct\fP {\fBint\fP|\fBfast\fP|\fBfloat\fP}]
16 [\fB-nosmooth\fP]
17 [\fB-maxmemory\fP \fIN\fP]
18 [{\fB-adobe\fP|\fB-notadobe\fP}]
19 [\fB-comments\fP]
20 [\fB-dumpexif\fP]
21 [\fB-exif=\fP\fIfilespec\fP]
22 [\fB-multiple\fP]
23 [\fB-repair\fP]
24 [\fB-verbose\fP]
25 [\fB-tracelevel\fP \fIN\fP]
26 [\fB-traceexif\fP]
27 [\fIfilename\fP]
28 .PP
29 Minimum unique abbreviation of option is acceptable. You may use double
30 hyphens instead of single hyphen to denote options. You may use white
31 space in place of the equals sign to separate an option name from its value.
32
33 .UN description
34 .SH DESCRIPTION
35 .PP
36 This program is part of
37 .BR "Netpbm" (1)\c
38 \&.
39 .PP
40 \fBjpegtopnm\fP converts JFIF images to PPM or PGM images.
41 .PP
42 By default, \fBjpegtopnm\fP expects the input stream to contain one
43 JFIF image and produces one PGM or PPM image as output. It fails if the
44 input stream is empty.
45 .PP
46 But with the \fB-multiple\fP option, \fBjpegtopnm\fP reads JFIF
47 images sequentially from the input stream and writes one PPM or PGM image
48 to the output stream for each JFIF input. If the input stream is empty,
49 so is the output.
50 .PP
51 The input stream is the \fIfilename\fP you specify or, if you
52 don't specify \fIfilename\fP, Standard Input. The output stream is
53 Standard Output.
54 .PP
55 If a JFIF input image is of the grayscale variety, \fBjpegtopnm\fP
56 generates a PGM image. Otherwise, it generates a PPM image.
57 .PP
58 Before Netpbm 10.11 (October 2002), \fBjpegtopnm\fP did not have
59 the multiple image stream capability. From 10.11 through 10.22,
60 Netpbm always behaved as if you specified \fB-multiple\fP. Starting
61 with Netpbm 10.23 (July 2004), Netpbm's default behavior went back to
62 the pre-10.11 behavior and the new \fB-multiple\fP option selected
63 the 10.12 behavior. The reason for the reversion was that there were
64 discovered in the world files that contain JFIF images followed by
65 something other than another JFIF image. The producers of these files
66 expect them to work with any JFIF interpreter because most JFIF
67 interpreters just stop reading the file after the first JFIF image.
68 .PP
69 \fBjpegtopnm\fP uses the Independent JPEG Group's JPEG library to
70 interpret the input file. See \fB
71 .UR http://www.ijg.org
72 http://www.ijg.org
73 .UE
74 \& \fP
75 for information on the library.
76 .PP
77 "JFIF" is the correct name for the image format commonly
78 known as "JPEG." Strictly speaking, JPEG is a method of
79 compression. The image format using JPEG compression that is by far
80 the most common is JFIF. There is also a subformat of TIFF that uses
81 JPEG compression.
82 .PP
83 EXIF is an image format that is a subformat of JFIF (to wit, a JFIF
84 file that contains an EXIF header as an APP1 marker).
85 \fBjpegtopnm\fP handles EXIF.
86 .PP
87 JFIF files can have either 8 bits per sample or 12 bits per sample.
88 The 8 bit variety is by far the most common. There are two versions
89 of the IJG JPEG library. One reads only 8 bit files and the other
90 reads only 12 bit files. You must link the appropriate one of these
91 libraries with \fBjpegtopnm\fP. Ordinarily, this means the library
92 is in your shared library search path when you run \fBjpegtopnm\fP.
93 .PP
94 \fBjpegtopnm\fP generates output with either one byte or two bytes
95 per sample depending on whether the JFIF input has either 8 bits or 12
96 bits per sample. You can use \fBpamdepth\fP to reduce a
97 two-byte-per-sample file to a one-byte-per-sample file if you need to.
98 .PP
99 If the JFIF file uses the CMYK or YCCK color space, the input does
100 not actually contain enough information to know what color each pixel
101 is. To know what color a pixel is, one would have to know the
102 properties of the inks to which the color space refers.
103 \fBjpegtopnm\fP interprets the colors using the common transformation
104 which assumes all the inks are simply subtractive and linear.
105 .PP
106 See the
107 .BR "\fBjpegtopnm\fP manual" (1)\c
108 \&
109 for information on how images lose quality when you convert to and
110 from JFIF.
111
112 .UN options
113 .SH OPTIONS
114 .PP
115 In addition to the options common to all programs based on libnetpbm
116 (most notably \fB-quiet\fP, see
117 .UR index.html#commonoptions
118 Common Options
119 .UE
120 \&), \fBjpegtopnm\fP recognizes the following
121 command line options:
122 .PP
123 The options are only for advanced users.
124
125
126 .TP
127 \fB-dct int\fP
128 Use integer DCT method (default).
129
130 .TP
131 \fB-dct fast\fP
132 Use fast integer DCT (less accurate).
133
134 .TP
135 \fB-dct float\fP
136 Use floating-point DCT method.
137 The float method is very slightly more accurate than the int method, but is
138 much slower unless your machine has very fast floating-point hardware. Also
139 note that results of the floating-point method may vary slightly across
140 machines, while the integer methods should give the same results everywhere.
141 The fast integer method is much less accurate than the other two.
142
143 .TP
144 \fB-nosmooth\fP
145 Use a faster, lower-quality upsampling routine.
146 .TP
147 \fB-maxmemory\fP\fI N\fP
148 Set limit on the amount of memory \fBjpegtopnm\fP uses in
149 processing large images. Value is in thousands of bytes, or millions
150 of bytes if "M" is suffixed to the number. For example,
151 \fB-maxmemory 4m\fP selects 4000000 bytes. If \fBjpegtopnm\fP needs
152 more space, it uses temporary files.
153
154 .TP
155 \fB-adobe\fP
156 .TP
157 \fB-notadobe\fP
158 There are two variations on the CMYK (and likewise YCCK) color space that
159 may be used in the JFIF input. In the normal one, a zero value for a color
160 components indicates absence of ink. In the other, a zero value means the
161 maximum ink coverage. The latter is used by Adobe Photoshop when it creates
162 a bare JFIF output file (but not when it creates JFIF output as part of
163 Encapsulated Postscript output).
164 .sp
165 These options tell \fBjpegtopnm\fP which version of the CMYK or
166 YCCK color space the image uses. If you specify neither,
167 \fBjpegtopnm\fP tries to figure it out on its own. In the present
168 version, it doesn't try very hard at all: It just assumes the
169 Photoshop version, since Photoshop and its emulators seem to be the
170 main source of CMYK and YCCK images. But with experience of use,
171 future versions might be more sophisticated.
172 .sp
173 If the JFIF image does not indicate that it is CMYK or YCCK, these
174 options have no effect.
175 .sp
176 If you don't use the right one of these options, the symptom is
177 output that looks like a negative.
178
179 .TP
180 \fB-dumpexif\fP
181 Print the interpreted contents of any Exif header in the input
182 file to the Standard Error file. Similar to the program \fBjhead\fP
183 (not part of the Netpbm package).
184 .sp
185 This option was added in Netpbm 9.19 (September 2001).
186
187 .TP
188 \fB-exif=\fP\fIfilespec\fP
189 Extract the contents of the EXIF header from the input image and
190 write it to the file \fIfilespec\fP. \fIfilespec\fP=\fB-\fP means
191 write it to Standard Output. When you write the EXIF header to
192 Standard Output, \fBjpegtopnm\fP does not output the converted image
193 (which is what normally would go to Standard Output) at all.
194 .sp
195 \fBjpegtopnm\fP writes the contents of the EXIF header
196 byte-for-byte, starting with the two byte length field (which length
197 includes those two bytes).
198 .sp
199 You can use this file as input to \fBpnmtojpeg\fP to insert an
200 identical EXIF header into a new JFIF image.
201 .sp
202 If there is no EXIF header, \fBjpegtopnm\fP writes two bytes of
203 binary zero and nothing else.
204 .sp
205 An EXIF header takes the form of a JFIF APP1 marker. Only the
206 first such marker within the JFIF header counts.
207 .sp
208 This option was added in Netpbm 9.19 (September 2001).
209
210 .TP
211 \fB-multiple\fP
212 Read multiple JFIF images sequentially from the input stream.
213 See
214 .UR #description
215 Description section
216 .UE
217 \& for details.
218 .sp
219 This option was new in Netpbm 10.23 (July 2004).
220
221 .TP
222 \fB-repair\fP
223 If the JFIF input is invalid, try to salvage whatever information is
224 there and produce a valid PNM image as output.
225 .sp
226 Without this option, some invalid input causes \fBjpegtopnm\fP
227 to fail, and what output it produces is undefined. With \fB-repair\fP
228 such invalid input causes \fBjpegtopnm\fP to succeed instead.
229 .sp
230 But note that there are some forms of invalid input that always cause
231 \fBjpegtopnm\fP to fail and others that always cause it to salvage image
232 information and succeed.
233 .sp
234 One particular case where \fB-repair\fP makes a difference is the
235 common case that the file is truncated somewhere after the JFIF
236 header. Without \fB-repair\fP, that always causes a failure; with
237 \fB-repair\fP it always causes success. Because the image
238 information is laid out generally top to bottom in the JFIF stream,
239 the image \fBjpegtopnm\fP produces in this case has the proper image
240 contents at the top, but the bottom is padded with gray.
241 .sp
242 This option was new in Netpbm 10.38.0 (March 2007). Before that,
243 \fBjpegtopnm\fP always fails in the cases in question.
244
245
246 .TP
247 \fB-comments\fP
248 Print any comments in the input file to the Standard Error file.
249
250 .TP
251 \fB-verbose\fP
252 Print details about the conversion to the Standard Error file.
253
254 .TP
255 \fB-tracelevel\fP\fI n\fP
256 Turn on the JPEG library's trace messages to the Standard Error
257 file. A higher value of \fIn\fP gets more trace information.
258 \fB-verbose\fP implies a trace level of at least 1.
259
260 .TP
261 \fB-traceexif\fP
262 Print trace information about the processing of EXIF header information.
263 .sp
264 This option was new in Netpbm 11.02 (March 2023).
265
266
267
268 .UN examples
269 .SH EXAMPLES
270 .PP
271 This example converts the color JFIF file foo.jpg to a PPM file
272 named foo.ppm:
273
274 .nf
275 jpegtopnm foo.jpg >foo.ppm
276
277 .fi
278
279 .UN hints
280 .SH HINTS
281
282 You can use \fBpnmquant\fP to color quantize the result, i.e. to
283 reduce the number of distinct colors in the image. In fact, you may
284 have to if you want to convert the PPM file to certain other formats.
285 \fBppmdither\fP Does a more sophisticated quantization.
286 .PP
287 Use \fBpamscale\fP to change the dimensions of the resulting
288 image.
289 .PP
290 Use \fBppmtopgm \fP to convert a color JFIF file to a grayscale
291 PGM file.
292 .PP
293 You can easily use these converters together. E.g.:
294
295 .nf
296 jpegtopnm foo.jpg | ppmtopgm | pamscale .25 >foo.pgm
297
298 .fi
299 .PP
300 \fB-dct fast\fP and/or \fB-nosmooth\fP gain speed at a small
301 sacrifice in quality.
302 .PP
303 If you are fortunate enough to have very fast floating point
304 hardware, \fB-dct float\fP may be even faster than \fB-dct fast\fP.
305 But on most machines \fB-dct float\fP is slower than \fB-dct int\fP;
306 in this case it is not worth using, because its theoretical accuracy
307 advantage is too small to be significant in practice.
308 .PP
309 Another program, \fBdjpeg\fP, is similar. \fBdjpeg\fP is
310 maintained by the Independent JPEG Group and packaged with the JPEG
311 library which \fBjpegtopnm\fP uses for all its JPEG work. Because of
312 that, you may expect it to exploit more current JPEG features. Also,
313 since you have to have the library to run \fBjpegtopnm\fP, but not
314 vice versa, \fBcjpeg\fP may be more commonly available.
315 .PP
316 On the other hand, \fBdjpeg\fP does not use the NetPBM libraries
317 to generate its output, as all the NetPBM tools such as
318 \fBjpegtopnm\fP do. This means it is less likely to be consistent
319 with all the other programs that deal with the NetPBM formats. Also,
320 the command syntax of \fBjpegtopnm\fP is consistent with that of the
321 other Netpbm tools, unlike \fBdjpeg\fP.
322
323 .UN environment
324 .SH ENVIRONMENT
325
326
327 .TP
328 \fBJPEGMEM\fP
329 If this environment variable is set, its value is the default
330 memory limit. The value is specified as described for the
331 \fB-maxmemory\fP option. An explicit \fB-maxmemory \fP option
332 overrides any \fBJPEGMEM\fP.
333
334
335
336 .UN seealso
337 .SH SEE ALSO
338 .PP
339 .BR "ppm" (1)\c
340 \&,
341 .BR "pgm" (1)\c
342 \&,
343 .BR "pnmtojpeg" (1)\c
344 \&,
345 .BR "pnmquant" (1)\c
346 \&,
347 .BR "pamscale" (1)\c
348 \&,
349 .BR "ppmtopgm" (1)\c
350 \&,
351 .BR "ppmdither" (1)\c
352 \&,
353 .BR "pamdepth" (1)\c
354 \&,
355 .PP
356 \fBdjpeg\fP man page,
357 \fBcjpeg\fP man page,
358 \fBjpegtran\fP man page,
359 \fBrdjpgcom\fP man page,
360 \fBwrjpgcom\fP man page,
361 \fBjhead\fP man page
362 .PP
363 Wallace, Gregory K. "The JPEG Still Picture Compression
364 Standard", Communications of the ACM, April 1991 (vol. 34,
365 no. 4), pp. 30-44.
366
367 .UN author
368 .SH AUTHOR
369 .PP
370 \fBjpegtopnm\fP and this manual were derived in large part from
371 \fBdjpeg\fP, by the Independent JPEG Group. The program is otherwise
372 by Bryan Henderson on March 19, 2000.
373 .SH DOCUMENT SOURCE
374 This manual page was generated by the Netpbm tool 'makeman' from HTML
375 source. The master documentation is at
376 .IP
377 .B http://netpbm.sourceforge.net/doc/jpegtopnm.html
378 .PP