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

FreeBSD Manual Pages

  
 
  

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

NAME
       cjpeg - compress	an image file to a JPEG	file

SYNOPSIS
       cjpeg [ options ] [ filename ]

DESCRIPTION
       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, GIF, and Targa.

OPTIONS
       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
	      info.)

       -grayscale
	      Create  monochrome  JPEG	file  from  color  input.   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	color-
	      space.

       -optimize
	      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.

       -progressive
	      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-
       ceptable.

       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:

       -arithmetic
	      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 accurate integer DCT method (default).

       -dct fast
	      Use less accurate	integer	DCT method [legacy feature].  When the
	      Independent JPEG Group's software	was first  released  in	 1991,
	      the  compression	time  for  a 1-megapixel JPEG image on a main-
	      stream PC	was measured in	minutes.  Thus,	the fast  integer  DCT
	      algorithm	 provided  noticeable performance benefits.  On	modern
	      CPUs running libjpeg-turbo, however, the compression time	for  a
	      1-megapixel JPEG image is	measured in milliseconds, and thus the
	      performance benefits of the fast algorithm are much less notice-
	      able.  On	modern x86/x86-64 CPUs that support AVX2 instructions,
	      the  fast	 and  int  methods have	similar	performance.  On other
	      types of CPUs, the fast method is	generally about	 5-15%	faster
	      than the int method.

	      For quality levels of 90 and below, there	should be little or no
	      perceptible  quality difference between the two algorithms.  For
	      quality levels above 90, however,	 the  difference  between  the
	      fast  and	int methods becomes more pronounced.  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 method.

       -dct float
	      Use floating-point  DCT  method  [legacy	feature].   The	 float
	      method 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
	      file.

       -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.

       -memdst
	      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.

       -report
	      Report compression progress.

       -strict
	      Treat all	warnings as fatal.  Enabling this  option  will	 cause
	      the  compressor  to  abort  if an	LZW-compressed GIF input image
	      contains incomplete or corrupt image data.

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

       -debug Same as -verbose.

       -version
	      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-
       ever.

       Switches	for wizards:

       -baseline
	      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.

EXAMPLES
       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

HINTS
       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.)

ENVIRONMENT
       JPEGMEM
	      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.

SEE ALSO
       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.

AUTHOR
       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.

ISSUES
       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.)

			       30 November 2021			      CJPEG(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=cjpeg&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help