Copyright 2009 The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
Package jpeg implements a JPEG image decoder and encoder. JPEG is defined in ITU-T T.81: https://www.w3.org/Graphics/JPEG/itu-t81.pdf.
package jpeg

import (
	
	
	
	
)
TODO(nigeltao): fix up the doc comment style so that sentences start with the name of the type or function that they annotate.
A FormatError reports that the input is not a valid JPEG.
type FormatError string

func ( FormatError) () string { return "invalid JPEG format: " + string() }
An UnsupportedError reports that the input uses a valid but unimplemented JPEG feature.
type UnsupportedError string

func ( UnsupportedError) () string { return "unsupported JPEG feature: " + string() }

var errUnsupportedSubsamplingRatio = UnsupportedError("luma/chroma subsampling ratio")
Component specification, specified in section B.2.2.
type component struct {
	h  int   // Horizontal sampling factor.
	v  int   // Vertical sampling factor.
	c  uint8 // Component identifier.
	tq uint8 // Quantization table destination selector.
}

const (
	dcTable = 0
	acTable = 1
	maxTc   = 1
	maxTh   = 3
	maxTq   = 3

	maxComponents = 4
)

const (
	sof0Marker = 0xc0 // Start Of Frame (Baseline Sequential).
	sof1Marker = 0xc1 // Start Of Frame (Extended Sequential).
	sof2Marker = 0xc2 // Start Of Frame (Progressive).
	dhtMarker  = 0xc4 // Define Huffman Table.
	rst0Marker = 0xd0 // ReSTart (0).
	rst7Marker = 0xd7 // ReSTart (7).
	soiMarker  = 0xd8 // Start Of Image.
	eoiMarker  = 0xd9 // End Of Image.
	sosMarker  = 0xda // Start Of Scan.
	dqtMarker  = 0xdb // Define Quantization Table.
	driMarker  = 0xdd // Define Restart Interval.
"APPlication specific" markers aren't part of the JPEG spec per se, but in practice, their use is described at https://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/JPEG.html
	app0Marker  = 0xe0
	app14Marker = 0xee
	app15Marker = 0xef
)
See https://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/JPEG.html#Adobe
unzig maps from the zig-zag ordering to the natural ordering. For example, unzig[3] is the column and row of the fourth element in zig-zag order. The value is 16, which means first column (16%8 == 0) and third row (16/8 == 2).
var unzig = [blockSize]int{
	0, 1, 8, 16, 9, 2, 3, 10,
	17, 24, 32, 25, 18, 11, 4, 5,
	12, 19, 26, 33, 40, 48, 41, 34,
	27, 20, 13, 6, 7, 14, 21, 28,
	35, 42, 49, 56, 57, 50, 43, 36,
	29, 22, 15, 23, 30, 37, 44, 51,
	58, 59, 52, 45, 38, 31, 39, 46,
	53, 60, 61, 54, 47, 55, 62, 63,
}
Deprecated: Reader is not used by the image/jpeg package and should not be used by others. It is kept for compatibility.
type Reader interface {
	io.ByteReader
	io.Reader
}
bits holds the unprocessed bits that have been taken from the byte-stream. The n least significant bits of a form the unread bits, to be read in MSB to LSB order.
type bits struct {
	a uint32 // accumulator.
	m uint32 // mask. m==1<<(n-1) when n>0, with m==0 when n==0.
	n int32  // the number of unread bits in a.
}

type decoder struct {
	r    io.Reader
bytes is a byte buffer, similar to a bufio.Reader, except that it has to be able to unread more than 1 byte, due to byte stuffing. Byte stuffing is specified in section F.1.2.3.
buf[i:j] are the buffered bytes read from the underlying io.Reader that haven't yet been passed further on.
		buf  [4096]byte
nUnreadable is the number of bytes to back up i after overshooting. It can be 0, 1 or 2.
		nUnreadable int
	}
	width, height int

	img1        *image.Gray
	img3        *image.YCbCr
	blackPix    []byte
	blackStride int

	ri    int // Restart Interval.
	nComp int
As per section 4.5, there are four modes of operation (selected by the SOF? markers): sequential DCT, progressive DCT, lossless and hierarchical, although this implementation does not support the latter two non-DCT modes. Sequential DCT is further split into baseline and extended, as per section 4.11.
	baseline    bool
	progressive bool

	jfif                bool
	adobeTransformValid bool
	adobeTransform      uint8
	eobRun              uint16 // End-of-Band run, specified in section G.1.2.2.

	comp       [maxComponents]component
	progCoeffs [maxComponents][]block // Saved state between progressive-mode scans.
	huff       [maxTc + 1][maxTh + 1]huffman
	quant      [maxTq + 1]block // Quantization tables, in zig-zag order.
	tmp        [2 * blockSize]byte
}
fill fills up the d.bytes.buf buffer from the underlying io.Reader. It should only be called when there are no unread bytes in d.bytes.
func ( *decoder) () error {
	if .bytes.i != .bytes.j {
		panic("jpeg: fill called when unread bytes exist")
Move the last 2 bytes to the start of the buffer, in case we need to call unreadByteStuffedByte.
	if .bytes.j > 2 {
		.bytes.buf[0] = .bytes.buf[.bytes.j-2]
		.bytes.buf[1] = .bytes.buf[.bytes.j-1]
		.bytes.i, .bytes.j = 2, 2
Fill in the rest of the buffer.
	,  := .r.Read(.bytes.buf[.bytes.j:])
	.bytes.j += 
	if  > 0 {
		 = nil
	}
	return 
}
unreadByteStuffedByte undoes the most recent readByteStuffedByte call, giving a byte of data back from d.bits to d.bytes. The Huffman look-up table requires at least 8 bits for look-up, which means that Huffman decoding can sometimes overshoot and read one or two too many bytes. Two-byte overshoot can happen when expecting to read a 0xff 0x00 byte-stuffed byte.
func ( *decoder) () {
	.bytes.i -= .bytes.nUnreadable
	.bytes.nUnreadable = 0
	if .bits.n >= 8 {
		.bits.a >>= 8
		.bits.n -= 8
		.bits.m >>= 8
	}
}
readByte returns the next byte, whether buffered or not buffered. It does not care about byte stuffing.
func ( *decoder) () ( byte,  error) {
	for .bytes.i == .bytes.j {
		if  = .fill();  != nil {
			return 0, 
		}
	}
	 = .bytes.buf[.bytes.i]
	.bytes.i++
	.bytes.nUnreadable = 0
	return , nil
}
errMissingFF00 means that readByteStuffedByte encountered an 0xff byte (a marker byte) that wasn't the expected byte-stuffed sequence 0xff, 0x00.
var errMissingFF00 = FormatError("missing 0xff00 sequence")
readByteStuffedByte is like readByte but is for byte-stuffed Huffman data.
Take the fast path if d.bytes.buf contains at least two bytes.
	if .bytes.i+2 <= .bytes.j {
		 = .bytes.buf[.bytes.i]
		.bytes.i++
		.bytes.nUnreadable = 1
		if  != 0xff {
			return , 
		}
		if .bytes.buf[.bytes.i] != 0x00 {
			return 0, errMissingFF00
		}
		.bytes.i++
		.bytes.nUnreadable = 2
		return 0xff, nil
	}

	.bytes.nUnreadable = 0

	,  = .readByte()
	if  != nil {
		return 0, 
	}
	.bytes.nUnreadable = 1
	if  != 0xff {
		return , nil
	}

	,  = .readByte()
	if  != nil {
		return 0, 
	}
	.bytes.nUnreadable = 2
	if  != 0x00 {
		return 0, errMissingFF00
	}
	return 0xff, nil
}
readFull reads exactly len(p) bytes into p. It does not care about byte stuffing.
Unread the overshot bytes, if any.
	if .bytes.nUnreadable != 0 {
		if .bits.n >= 8 {
			.unreadByteStuffedByte()
		}
		.bytes.nUnreadable = 0
	}

	for {
		 := copy(, .bytes.buf[.bytes.i:.bytes.j])
		 = [:]
		.bytes.i += 
		if len() == 0 {
			break
		}
		if  := .fill();  != nil {
			if  == io.EOF {
				 = io.ErrUnexpectedEOF
			}
			return 
		}
	}
	return nil
}
ignore ignores the next n bytes.
Unread the overshot bytes, if any.
	if .bytes.nUnreadable != 0 {
		if .bits.n >= 8 {
			.unreadByteStuffedByte()
		}
		.bytes.nUnreadable = 0
	}

	for {
		 := .bytes.j - .bytes.i
		if  >  {
			 = 
		}
		.bytes.i += 
		 -= 
		if  == 0 {
			break
		}
		if  := .fill();  != nil {
			if  == io.EOF {
				 = io.ErrUnexpectedEOF
			}
			return 
		}
	}
	return nil
}
Specified in section B.2.2.
func ( *decoder) ( int) error {
	if .nComp != 0 {
		return FormatError("multiple SOF markers")
	}
	switch  {
	case 6 + 3*1: // Grayscale image.
		.nComp = 1
	case 6 + 3*3: // YCbCr or RGB image.
		.nComp = 3
	case 6 + 3*4: // YCbCrK or CMYK image.
		.nComp = 4
	default:
		return UnsupportedError("number of components")
	}
	if  := .readFull(.tmp[:]);  != nil {
		return 
We only support 8-bit precision.
	if .tmp[0] != 8 {
		return UnsupportedError("precision")
	}
	.height = int(.tmp[1])<<8 + int(.tmp[2])
	.width = int(.tmp[3])<<8 + int(.tmp[4])
	if int(.tmp[5]) != .nComp {
		return FormatError("SOF has wrong length")
	}

	for  := 0;  < .nComp; ++ {
Section B.2.2 states that "the value of C_i shall be different from the values of C_1 through C_(i-1)".
		for  := 0;  < ; ++ {
			if .comp[].c == .comp[].c {
				return FormatError("repeated component identifier")
			}
		}

		.comp[].tq = .tmp[8+3*]
		if .comp[].tq > maxTq {
			return FormatError("bad Tq value")
		}

		 := .tmp[7+3*]
		,  := int(>>4), int(&0x0f)
		if  < 1 || 4 <  ||  < 1 || 4 <  {
			return FormatError("luma/chroma subsampling ratio")
		}
		if  == 3 ||  == 3 {
			return errUnsupportedSubsamplingRatio
		}
		switch .nComp {
If a JPEG image has only one component, section A.2 says "this data is non-interleaved by definition" and section A.2.2 says "[in this case...] the order of data units within a scan shall be left-to-right and top-to-bottom... regardless of the values of H_1 and V_1". Section 4.8.2 also says "[for non-interleaved data], the MCU is defined to be one data unit". Similarly, section A.1.1 explains that it is the ratio of H_i to max_j(H_j) that matters, and similarly for V. For grayscale images, H_1 is the maximum H_j for all components j, so that ratio is always 1. The component's (h, v) is effectively always (1, 1): even if the nominal (h, v) is (2, 1), a 20x5 image is encoded in three 8x8 MCUs, not two 16x8 MCUs.
			,  = 1, 1

For YCbCr images, we only support 4:4:4, 4:4:0, 4:2:2, 4:2:0, 4:1:1 or 4:1:0 chroma subsampling ratios. This implies that the (h, v) values for the Y component are either (1, 1), (1, 2), (2, 1), (2, 2), (4, 1) or (4, 2), and the Y component's values must be a multiple of the Cb and Cr component's values. We also assume that the two chroma components have the same subsampling ratio.
			switch  {
We have already verified, above, that h and v are both either 1, 2 or 4, so invalid (h, v) combinations are those with v == 4.
				if  == 4 {
					return errUnsupportedSubsamplingRatio
				}
			case 1: // Cb.
				if .comp[0].h% != 0 || .comp[0].v% != 0 {
					return errUnsupportedSubsamplingRatio
				}
			case 2: // Cr.
				if .comp[1].h !=  || .comp[1].v !=  {
					return errUnsupportedSubsamplingRatio
				}
			}

For 4-component images (either CMYK or YCbCrK), we only support two hv vectors: [0x11 0x11 0x11 0x11] and [0x22 0x11 0x11 0x22]. Theoretically, 4-component JPEG images could mix and match hv values but in practice, those two combinations are the only ones in use, and it simplifies the applyBlack code below if we can assume that: - for CMYK, the C and K channels have full samples, and if the M and Y channels subsample, they subsample both horizontally and vertically. - for YCbCrK, the Y and K channels have full samples.
			switch  {
			case 0:
				if  != 0x11 &&  != 0x22 {
					return errUnsupportedSubsamplingRatio
				}
			case 1, 2:
				if  != 0x11 {
					return errUnsupportedSubsamplingRatio
				}
			case 3:
				if .comp[0].h !=  || .comp[0].v !=  {
					return errUnsupportedSubsamplingRatio
				}
			}
		}

		.comp[].h = 
		.comp[].v = 
	}
	return nil
}
Specified in section B.2.4.1.
func ( *decoder) ( int) error {
:
	for  > 0 {
		--
		,  := .readByte()
		if  != nil {
			return 
		}
		 :=  & 0x0f
		if  > maxTq {
			return FormatError("bad Tq value")
		}
		switch  >> 4 {
		default:
			return FormatError("bad Pq value")
		case 0:
			if  < blockSize {
				break 
			}
			 -= blockSize
			if  := .readFull(.tmp[:blockSize]);  != nil {
				return 
			}
			for  := range .quant[] {
				.quant[][] = int32(.tmp[])
			}
		case 1:
			if  < 2*blockSize {
				break 
			}
			 -= 2 * blockSize
			if  := .readFull(.tmp[:2*blockSize]);  != nil {
				return 
			}
			for  := range .quant[] {
				.quant[][] = int32(.tmp[2*])<<8 | int32(.tmp[2*+1])
			}
		}
	}
	if  != 0 {
		return FormatError("DQT has wrong length")
	}
	return nil
}
Specified in section B.2.4.4.
func ( *decoder) ( int) error {
	if  != 2 {
		return FormatError("DRI has wrong length")
	}
	if  := .readFull(.tmp[:2]);  != nil {
		return 
	}
	.ri = int(.tmp[0])<<8 + int(.tmp[1])
	return nil
}

func ( *decoder) ( int) error {
	if  < 5 {
		return .ignore()
	}
	if  := .readFull(.tmp[:5]);  != nil {
		return 
	}
	 -= 5

	.jfif = .tmp[0] == 'J' && .tmp[1] == 'F' && .tmp[2] == 'I' && .tmp[3] == 'F' && .tmp[4] == '\x00'

	if  > 0 {
		return .ignore()
	}
	return nil
}

func ( *decoder) ( int) error {
	if  < 12 {
		return .ignore()
	}
	if  := .readFull(.tmp[:12]);  != nil {
		return 
	}
	 -= 12

	if .tmp[0] == 'A' && .tmp[1] == 'd' && .tmp[2] == 'o' && .tmp[3] == 'b' && .tmp[4] == 'e' {
		.adobeTransformValid = true
		.adobeTransform = .tmp[11]
	}

	if  > 0 {
		return .ignore()
	}
	return nil
}
decode reads a JPEG image from r and returns it as an image.Image.
func ( *decoder) ( io.Reader,  bool) (image.Image, error) {
	.r = 
Check for the Start Of Image marker.
	if  := .readFull(.tmp[:2]);  != nil {
		return nil, 
	}
	if .tmp[0] != 0xff || .tmp[1] != soiMarker {
		return nil, FormatError("missing SOI marker")
	}
Process the remaining segments until the End Of Image marker.
	for {
		 := .readFull(.tmp[:2])
		if  != nil {
			return nil, 
		}
Strictly speaking, this is a format error. However, libjpeg is liberal in what it accepts. As of version 9, next_marker in jdmarker.c treats this as a warning (JWRN_EXTRANEOUS_DATA) and continues to decode the stream. Even before next_marker sees extraneous data, jpeg_fill_bit_buffer in jdhuff.c reads as many bytes as it can, possibly past the end of a scan's data. It effectively puts back any markers that it overscanned (e.g. an "\xff\xd9" EOI marker), but it does not put back non-marker data, and thus it can silently ignore a small number of extraneous non-marker bytes before next_marker has a chance to see them (and print a warning). We are therefore also liberal in what we accept. Extraneous data is silently ignored. This is similar to, but not exactly the same as, the restart mechanism within a scan (the RST[0-7] markers). Note that extraneous 0xff bytes in e.g. SOS data are escaped as "\xff\x00", and so are detected a little further down below.
			.tmp[0] = .tmp[1]
			.tmp[1],  = .readByte()
			if  != nil {
				return nil, 
			}
		}
		 := .tmp[1]
Treat "\xff\x00" as extraneous data.
			continue
		}
Section B.1.1.2 says, "Any marker may optionally be preceded by any number of fill bytes, which are bytes assigned code X'FF'".
			,  = .readByte()
			if  != nil {
				return nil, 
			}
		}
		if  == eoiMarker { // End Of Image.
			break
		}
Figures B.2 and B.16 of the specification suggest that restart markers should only occur between Entropy Coded Segments and not after the final ECS. However, some encoders may generate incorrect JPEGs with a final restart marker. That restart marker will be seen here instead of inside the processSOS method, and is ignored as a harmless error. Restart markers have no extra data, so we check for this before we read the 16-bit length of the segment.
			continue
		}
Read the 16-bit length of the segment. The value includes the 2 bytes for the length itself, so we subtract 2 to get the number of remaining bytes.
		if  = .readFull(.tmp[:2]);  != nil {
			return nil, 
		}
		 := int(.tmp[0])<<8 + int(.tmp[1]) - 2
		if  < 0 {
			return nil, FormatError("short segment length")
		}

		switch  {
		case sof0Marker, sof1Marker, sof2Marker:
			.baseline =  == sof0Marker
			.progressive =  == sof2Marker
			 = .processSOF()
			if  && .jfif {
				return nil, 
			}
		case dhtMarker:
			if  {
				 = .ignore()
			} else {
				 = .processDHT()
			}
		case dqtMarker:
			if  {
				 = .ignore()
			} else {
				 = .processDQT()
			}
		case sosMarker:
			if  {
				return nil, nil
			}
			 = .processSOS()
		case driMarker:
			if  {
				 = .ignore()
			} else {
				 = .processDRI()
			}
		case app0Marker:
			 = .processApp0Marker()
		case app14Marker:
			 = .processApp14Marker()
		default:
			if app0Marker <=  &&  <= app15Marker ||  == comMarker {
				 = .ignore()
			} else if  < 0xc0 { // See Table B.1 "Marker code assignments".
				 = FormatError("unknown marker")
			} else {
				 = UnsupportedError("unknown marker")
			}
		}
		if  != nil {
			return nil, 
		}
	}

	if .progressive {
		if  := .reconstructProgressiveImage();  != nil {
			return nil, 
		}
	}
	if .img1 != nil {
		return .img1, nil
	}
	if .img3 != nil {
		if .blackPix != nil {
			return .applyBlack()
		} else if .isRGB() {
			return .convertToRGB()
		}
		return .img3, nil
	}
	return nil, FormatError("missing SOS marker")
}
applyBlack combines d.img3 and d.blackPix into a CMYK image. The formula used depends on whether the JPEG image is stored as CMYK or YCbCrK, indicated by the APP14 (Adobe) metadata. Adobe CMYK JPEG images are inverted, where 255 means no ink instead of full ink, so we apply "v = 255 - v" at various points. Note that a double inversion is a no-op, so inversions might be implicit in the code below.
func ( *decoder) () (image.Image, error) {
	if !.adobeTransformValid {
		return nil, UnsupportedError("unknown color model: 4-component JPEG doesn't have Adobe APP14 metadata")
	}
If the 4-component JPEG image isn't explicitly marked as "Unknown (RGB or CMYK)" as per https://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/JPEG.html#Adobe we assume that it is YCbCrK. This matches libjpeg's jdapimin.c.
Convert the YCbCr part of the YCbCrK to RGB, invert the RGB to get CMY, and patch in the original K. The RGB to CMY inversion cancels out the 'Adobe inversion' described in the applyBlack doc comment above, so in practice, only the fourth channel (black) is inverted.
		 := .img3.Bounds()
		 := image.NewRGBA()
		imageutil.DrawYCbCr(, , .img3, .Min)
		for ,  := 0, .Min.Y;  < .Max.Y; ,  = +.Stride, +1 {
			for ,  := +3, .Min.X;  < .Max.X; ,  = +4, +1 {
				.Pix[] = 255 - .blackPix[(-.Min.Y)*.blackStride+(-.Min.X)]
			}
		}
		return &image.CMYK{
			Pix:    .Pix,
			Stride: .Stride,
			Rect:   .Rect,
		}, nil
	}
The first three channels (cyan, magenta, yellow) of the CMYK were decoded into d.img3, but each channel was decoded into a separate []byte slice, and some channels may be subsampled. We interleave the separate channels into an image.CMYK's single []byte slice containing 4 contiguous bytes per pixel.
	 := .img3.Bounds()
	 := image.NewCMYK()

	 := [4]struct {
		    []byte
		 int
	}{
		{.img3.Y, .img3.YStride},
		{.img3.Cb, .img3.CStride},
		{.img3.Cr, .img3.CStride},
		{.blackPix, .blackStride},
	}
	for ,  := range  {
		 := .comp[].h != .comp[0].h || .comp[].v != .comp[0].v
		for ,  := 0, .Min.Y;  < .Max.Y; ,  = +.Stride, +1 {
			 :=  - .Min.Y
			if  {
				 /= 2
			}
			for ,  := +, .Min.X;  < .Max.X; ,  = +4, +1 {
				 :=  - .Min.X
				if  {
					 /= 2
				}
				.Pix[] = 255 - .[*.+]
			}
		}
	}
	return , nil
}

func ( *decoder) () bool {
	if .jfif {
		return false
	}
https://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/JPEG.html#Adobe says that 0 means Unknown (and in practice RGB) and 1 means YCbCr.
		return true
	}
	return .comp[0].c == 'R' && .comp[1].c == 'G' && .comp[2].c == 'B'
}

func ( *decoder) () (image.Image, error) {
	 := .comp[0].h / .comp[1].h
	 := .img3.Bounds()
	 := image.NewRGBA()
	for  := .Min.Y;  < .Max.Y; ++ {
		 := .PixOffset(.Min.X, )
		 := .img3.YOffset(.Min.X, )
		 := .img3.COffset(.Min.X, )
		for ,  := 0, .Max.X-.Min.X;  < ; ++ {
			.Pix[+4*+0] = .img3.Y[+]
			.Pix[+4*+1] = .img3.Cb[+/]
			.Pix[+4*+2] = .img3.Cr[+/]
			.Pix[+4*+3] = 255
		}
	}
	return , nil
}
Decode reads a JPEG image from r and returns it as an image.Image.
func ( io.Reader) (image.Image, error) {
	var  decoder
	return .decode(, false)
}
DecodeConfig returns the color model and dimensions of a JPEG image without decoding the entire image.
func ( io.Reader) (image.Config, error) {
	var  decoder
	if ,  := .decode(, true);  != nil {
		return image.Config{}, 
	}
	switch .nComp {
	case 1:
		return image.Config{
			ColorModel: color.GrayModel,
			Width:      .width,
			Height:     .height,
		}, nil
	case 3:
		 := color.YCbCrModel
		if .isRGB() {
			 = color.RGBAModel
		}
		return image.Config{
			ColorModel: ,
			Width:      .width,
			Height:     .height,
		}, nil
	case 4:
		return image.Config{
			ColorModel: color.CMYKModel,
			Width:      .width,
			Height:     .height,
		}, nil
	}
	return image.Config{}, FormatError("missing SOF marker")
}

func () {
	image.RegisterFormat("jpeg", "\xff\xd8", Decode, DecodeConfig)