Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CJPEG(1)		    General Commands Manual		      CJPEG(1)

       cjpeg - compress	an image file to a JPEG	file

       cjpeg [ options ] [ filename ]

       cjpeg compresses	the named image	file, or the standard input if no file
       is named, and produces a	JPEG/JFIF file on the  standard	 output.   The
       currently supported input file formats are: PPM (PBMPLUS	color format),
       PGM (PBMPLUS grayscale format), BMP, Targa, and RLE (Utah Raster	 Tool-
       kit format).  (RLE is supported only if the URT library is available.)

       All  switch  names  may	be abbreviated;	for example, -grayscale	may be
       written -gray or	-gr.  Most of the "basic" switches can be  abbreviated
       to  as little as	one letter.  Upper and lower case are equivalent (thus
       -BMP is the same	as -bmp).  British spellings are also accepted	(e.g.,
       -greyscale), though for brevity these are not mentioned below.

       The basic switches are:

       -quality	N[,...]
	      Scale quantization tables	to adjust image	quality.  Quality is 0
	      (worst) to 100 (best); default  is  75.	(See  below  for  more

	      Create  monochrome  JPEG	file from color	input.	Be sure	to use
	      this switch when compressing a grayscale BMP file, because cjpeg
	      isn't  bright  enough  to	 notice	 whether  a BMP	file uses only
	      shades of	gray.  By saying -grayscale, you'll get	a smaller JPEG
	      file that	takes less time	to process.

       -rgb   Create  RGB JPEG file.  Using this switch	suppresses the conver-
	      sion from	RGB colorspace input to	the default  YCbCr  JPEG  col-

	      Perform  optimization  of	 entropy encoding parameters.  Without
	      this, default encoding parameters	are used.   -optimize  usually
	      makes  the  JPEG	file a little smaller, but cjpeg runs somewhat
	      slower and needs much more memory.  Image	quality	and  speed  of
	      decompression are	unaffected by -optimize.

	      Create progressive JPEG file (see	below).

       -targa Input  file is Targa format.  Targa files	that contain an	"iden-
	      tification" field	will not be automatically recognized by	cjpeg;
	      for  such	 files you must	specify	-targa to make cjpeg treat the
	      input as Targa format.  For most Targa  files,  you  won't  need
	      this switch.

       The  -quality  switch  lets  you	trade off compressed file size against
       quality of the reconstructed image: the higher the quality setting, the
       larger  the  JPEG  file,	and the	closer the output image	will be	to the
       original	input.	Normally you want to use the  lowest  quality  setting
       (smallest  file)	 that  decompresses  into something visually indistin-
       guishable from the original image.  For this purpose the	 quality  set-
       ting should generally be	between	50 and 95 (the default is 75) for pho-
       tographic images.  If you see defects at	-quality 75, then go up	 5  or
       10  counts  at  a time until you	are happy with the output image.  (The
       optimal setting will vary from one image	to another.)

       -quality	100 will generate a quantization table of all 1's,  minimizing
       loss  in	 the quantization step (but there is still information loss in
       subsampling, as well as roundoff	error.)	 For most images, specifying a
       quality	value  above about 95 will increase the	size of	the compressed
       file dramatically, and while the	quality	gain from these	higher quality
       values is measurable (using metrics such	as PSNR	or SSIM), it is	rarely
       perceivable by human vision.

       In the other direction, quality values below 50 will produce very small
       files of	low image quality.  Settings around 5 to 10 might be useful in
       preparing an index of a large image library, for	example.  Try -quality
       2 (or so) for some amusing Cubist effects.  (Note: quality values below
       about 25	generate 2-byte	quantization tables, which are considered  op-
       tional  in  the	JPEG standard.	cjpeg emits a warning message when you
       give such a quality value, because some other JPEG programs may be  un-
       able to decode the resulting file.  Use -baseline if you	need to	ensure
       compatibility at	low quality values.)

       The -quality option has been extended in	this version of	cjpeg to  sup-
       port  separate  quality	settings for luminance and chrominance (or, in
       general,	separate settings for every  quantization  table  slot.)   The
       principle  is the same as chrominance subsampling:  since the human eye
       is more sensitive to spatial changes in brightness than spatial changes
       in color, the chrominance components can	be quantized more than the lu-
       minance components without incurring any	visible	 image	quality	 loss.
       However,	unlike subsampling, this feature reduces data in the frequency
       domain instead of the spatial  domain,  which  allows  for  more	 fine-
       grained	control.   This	option is useful in quality-sensitive applica-
       tions, for which	the artifacts generated	by subsampling	may  be	 unac-

       The -quality option accepts a comma-separated list of parameters, which
       respectively refer to the quality levels	that should be assigned	to the
       quantization table slots.  If there are more q-table slots than parame-
       ters, then the last parameter is	replicated.  Thus, if only one quality
       parameter  is  given,  this  is used for	both luminance and chrominance
       (slots 0	and 1, respectively), preserving the legacy behavior of	 cjpeg
       v6b  and	 prior.	  More	(or customized)	quantization tables can	be set
       with the	-qtables option	and assigned to	components  with  the  -qslots
       option (see the "wizard"	switches below.)

       JPEG  files  generated  with separate luminance and chrominance quality
       are fully compliant with	standard JPEG decoders.

       CAUTION:	For this setting to be useful, be sure to pass an argument  of
       -sample	1x1  to	 cjpeg to disable chrominance subsampling.  Otherwise,
       the default subsampling level (2x2, AKA "4:2:0")	will be	used.

       The -progressive	switch creates a "progressive  JPEG"  file.   In  this
       type  of	 JPEG file, the	data is	stored in multiple scans of increasing
       quality.	 If the	file is	being transmitted over a  slow	communications
       link, the decoder can use the first scan	to display a low-quality image
       very quickly, and can then improve the  display	with  each  subsequent
       scan.  The final	image is exactly equivalent to a standard JPEG file of
       the same	quality	setting, and the total file size is about the same ---
       often a little smaller.

       Switches	for advanced users:

	      Use  arithmetic  coding.	 Caution: arithmetic coded JPEG	is not
	      yet widely implemented, so many decoders will be unable to  view
	      an arithmetic coded JPEG file at all.

       -dct int
	      Use integer DCT method (default).

       -dct fast
	      Use  fast	 integer  DCT  (less accurate).	 In libjpeg-turbo, the
	      fast method is generally about 5-15% faster than the int	method
	      when using the x86/x86-64	SIMD extensions	(results may vary with
	      other SIMD implementations, or when using	libjpeg-turbo  without
	      SIMD  extensions.)   For	quality	 levels	of 90 and below, there
	      should be	little or no perceptible difference  between  the  two
	      algorithms.   For	 quality levels	above 90, however, the differ-
	      ence between the fast and	the  int  methods  becomes  more  pro-
	      nounced.	 With quality=97, for instance,	the fast method	incurs
	      generally	about a	1-3 dB loss (in	 PSNR)	relative  to  the  int
	      method,  but this	can be larger for some images.	Do not use the
	      fast method with quality levels above 97.	 The  algorithm	 often
	      degenerates  at  quality=98 and above and	can actually produce a
	      more lossy image than if lower quality  levels  had  been	 used.
	      Also, in libjpeg-turbo, the fast method is not fully accelerated
	      for quality levels above 97, so it will be slower	than  the  int

       -dct float
	      Use  floating-point  DCT	method.	  The float method is mainly a
	      legacy feature.  It does not produce significantly more accurate
	      results  than  the int method, and it is much slower.  The float
	      method may also give different results on	different machines due
	      to varying roundoff behavior, whereas the	integer	methods	should
	      give the same results on all machines.

       -icc file
	      Embed ICC	color management profile contained  in	the  specified

       -restart	N
	      Emit  a  JPEG  restart  marker  every N MCU rows,	or every N MCU
	      blocks if	"B" is attached	to the number.	-restart  0  (the  de-
	      fault) means no restart markers.

       -smooth N
	      Smooth the input image to	eliminate dithering noise.  N, ranging
	      from 1 to	100, indicates the strength of smoothing.  0 (the  de-
	      fault) means no smoothing.

       -maxmemory N
	      Set  limit  for  amount of memory	to use in processing large im-
	      ages.  Value is in thousands of bytes, or	millions of  bytes  if
	      "M"  is  attached	 to  the number.  For example, -max 4m selects
	      4000000 bytes.  If more space is needed, an error	will occur.

       -outfile	name
	      Send output image	to the named file, not to standard output.

	      Compress to memory instead of a file.  This feature  was	imple-
	      mented mainly as a way of	testing	the in-memory destination man-
	      ager (jpeg_mem_dest()), but it is	also useful for	 benchmarking,
	      since it reduces the I/O overhead.

	      Enable  debug printout.  More -v's give more output.  Also, ver-
	      sion information is printed at startup.

       -debug Same as -verbose.

	      Print version information	and exit.

       The -restart option inserts extra markers that allow a JPEG decoder  to
       resynchronize after a transmission error.  Without restart markers, any
       damage to a compressed file will	usually	ruin the image from the	 point
       of  the error to	the end	of the image; with restart markers, the	damage
       is usually confined to the portion of the image up to the next  restart
       marker.	 Of course, the	restart	markers	occupy extra space.  We	recom-
       mend -restart 1 for images that will be transmitted  across  unreliable
       networks	such as	Usenet.

       The  -smooth  option  filters  the input	to eliminate fine-scale	noise.
       This is often useful when converting dithered images to JPEG: a	moder-
       ate  smoothing factor of	10 to 50 gets rid of dithering patterns	in the
       input file, resulting in	a smaller JPEG file and	a  better-looking  im-
       age.   Too  large  a smoothing factor will visibly blur the image, how-

       Switches	for wizards:

	      Force baseline-compatible	quantization tables to	be  generated.
	      This  clamps  quantization  values to 8 bits even	at low quality
	      settings.	 (This switch is poorly	named, since it	does  not  en-
	      sure  that  the  output is actually baseline JPEG.  For example,
	      you can use -baseline and	-progressive together.)

       -qtables	file
	      Use the quantization tables given	in the specified text file.

       -qslots N[,...]
	      Select which quantization	table to use for each color component.

       -sample HxV[,...]
	      Set JPEG sampling	factors	for each color component.

       -scans file
	      Use the scan script given	in the specified text file.

       The "wizard" switches are intended for experimentation with  JPEG.   If
       you  don't know what you	are doing, don't use them.  These switches are
       documented further in the file wizard.txt.

       This example compresses the PPM file foo.ppm with a quality  factor  of
       60 and saves the	output as foo.jpg:

	      cjpeg -quality 60	foo.ppm	> foo.jpg

       Color  GIF  files  are not the ideal input for JPEG; JPEG is really in-
       tended for compressing  full-color  (24-bit)  images.   In  particular,
       don't  try  to  convert	cartoons, line drawings, and other images that
       have only a few distinct	colors.	 GIF works great on these,  JPEG  does
       not.   If you want to convert a GIF to JPEG, you	should experiment with
       cjpeg's -quality	and -smooth options to get a satisfactory  conversion.
       -smooth 10 or so	is often helpful.

       Avoid  running an image through a series	of JPEG	compression/decompres-
       sion cycles.  Image quality loss	will accumulate; after ten or  so  cy-
       cles  the  image	 may  be noticeably worse than it was after one	cycle.
       It's best to use	a lossless format while	manipulating  an  image,  then
       convert to JPEG format when you are ready to file the image away.

       The -optimize option to cjpeg is	worth using when you are making	a "fi-
       nal" version for	posting	or archiving.  It's also a win	when  you  are
       using  low quality settings to make very	small JPEG files; the percent-
       age improvement is often	a lot more than	it is on  larger  files.   (At
       present,	 -optimize mode	is always selected when	generating progressive
       JPEG files.)

	      If this environment variable is set, its value  is  the  default
	      memory  limit.   The  value  is  specified  as described for the
	      -maxmemory switch.  JPEGMEM overrides the	default	 value	speci-
	      fied  when the program was compiled, and itself is overridden by
	      an explicit -maxmemory.

       djpeg(1), jpegtran(1), rdjpgcom(1), wrjpgcom(1)
       ppm(5), pgm(5)
       Wallace,	Gregory	K.  "The JPEG  Still  Picture  Compression  Standard",
       Communications of the ACM, April	1991 (vol. 34, no. 4), pp. 30-44.

       Independent JPEG	Group

       This file was modified by The libjpeg-turbo Project to include only in-
       formation relevant to libjpeg-turbo, to wordsmith certain sections, and
       to describe features not	present	in libjpeg.

       Support	for  GIF  input	files was removed in cjpeg v6b due to concerns
       over the	Unisys LZW patent.  Although  this  patent  expired  in	 2006,
       cjpeg  still lacks GIF support, for these historical reasons.  (Conver-
       sion of GIF files to JPEG is usually a bad idea anyway, since GIF is  a
       256-color format.)

       Not all variants	of BMP and Targa file formats are supported.

       The  -targa switch is not a bug,	it's a feature.	 (It would be a	bug if
       the Targa format	designers had not been clueless.)

				 18 March 2017			      CJPEG(1)


Want to link to this manual page? Use this URL:

home | help