Source file src/pkg/image/jpeg/reader.go

     1	// Copyright 2009 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	// Package jpeg implements a JPEG image decoder and encoder.
     6	//
     7	// JPEG is defined in ITU-T T.81: http://www.w3.org/Graphics/JPEG/itu-t81.pdf.
     8	package jpeg
     9	
    10	import (
    11		"bufio"
    12		"image"
    13		"image/color"
    14		"io"
    15	)
    16	
    17	// TODO(nigeltao): fix up the doc comment style so that sentences start with
    18	// the name of the type or function that they annotate.
    19	
    20	// A FormatError reports that the input is not a valid JPEG.
    21	type FormatError string
    22	
    23	func (e FormatError) Error() string { return "invalid JPEG format: " + string(e) }
    24	
    25	// An UnsupportedError reports that the input uses a valid but unimplemented JPEG feature.
    26	type UnsupportedError string
    27	
    28	func (e UnsupportedError) Error() string { return "unsupported JPEG feature: " + string(e) }
    29	
    30	// Component specification, specified in section B.2.2.
    31	type component struct {
    32		h  int   // Horizontal sampling factor.
    33		v  int   // Vertical sampling factor.
    34		c  uint8 // Component identifier.
    35		tq uint8 // Quantization table destination selector.
    36	}
    37	
    38	const (
    39		dcTable = 0
    40		acTable = 1
    41		maxTc   = 1
    42		maxTh   = 3
    43		maxTq   = 3
    44	
    45		// A grayscale JPEG image has only a Y component.
    46		nGrayComponent = 1
    47		// A color JPEG image has Y, Cb and Cr components.
    48		nColorComponent = 3
    49	
    50		// We only support 4:4:4, 4:4:0, 4:2:2 and 4:2:0 downsampling, and therefore the
    51		// number of luma samples per chroma sample is at most 2 in the horizontal
    52		// and 2 in the vertical direction.
    53		maxH = 2
    54		maxV = 2
    55	)
    56	
    57	const (
    58		soiMarker   = 0xd8 // Start Of Image.
    59		eoiMarker   = 0xd9 // End Of Image.
    60		sof0Marker  = 0xc0 // Start Of Frame (Baseline).
    61		sof2Marker  = 0xc2 // Start Of Frame (Progressive).
    62		dhtMarker   = 0xc4 // Define Huffman Table.
    63		dqtMarker   = 0xdb // Define Quantization Table.
    64		sosMarker   = 0xda // Start Of Scan.
    65		driMarker   = 0xdd // Define Restart Interval.
    66		rst0Marker  = 0xd0 // ReSTart (0).
    67		rst7Marker  = 0xd7 // ReSTart (7).
    68		app0Marker  = 0xe0 // APPlication specific (0).
    69		app15Marker = 0xef // APPlication specific (15).
    70		comMarker   = 0xfe // COMment.
    71	)
    72	
    73	// unzig maps from the zig-zag ordering to the natural ordering. For example,
    74	// unzig[3] is the column and row of the fourth element in zig-zag order. The
    75	// value is 16, which means first column (16%8 == 0) and third row (16/8 == 2).
    76	var unzig = [blockSize]int{
    77		0, 1, 8, 16, 9, 2, 3, 10,
    78		17, 24, 32, 25, 18, 11, 4, 5,
    79		12, 19, 26, 33, 40, 48, 41, 34,
    80		27, 20, 13, 6, 7, 14, 21, 28,
    81		35, 42, 49, 56, 57, 50, 43, 36,
    82		29, 22, 15, 23, 30, 37, 44, 51,
    83		58, 59, 52, 45, 38, 31, 39, 46,
    84		53, 60, 61, 54, 47, 55, 62, 63,
    85	}
    86	
    87	// If the passed in io.Reader does not also have ReadByte, then Decode will introduce its own buffering.
    88	type Reader interface {
    89		io.Reader
    90		ReadByte() (c byte, err error)
    91	}
    92	
    93	type decoder struct {
    94		r             Reader
    95		b             bits
    96		width, height int
    97		img1          *image.Gray
    98		img3          *image.YCbCr
    99		ri            int // Restart Interval.
   100		nComp         int
   101		progressive   bool
   102		eobRun        uint16 // End-of-Band run, specified in section G.1.2.2.
   103		comp          [nColorComponent]component
   104		progCoeffs    [nColorComponent][]block // Saved state between progressive-mode scans.
   105		huff          [maxTc + 1][maxTh + 1]huffman
   106		quant         [maxTq + 1]block // Quantization tables, in zig-zag order.
   107		tmp           [1024]byte
   108	}
   109	
   110	// Reads and ignores the next n bytes.
   111	func (d *decoder) ignore(n int) error {
   112		for n > 0 {
   113			m := len(d.tmp)
   114			if m > n {
   115				m = n
   116			}
   117			_, err := io.ReadFull(d.r, d.tmp[0:m])
   118			if err != nil {
   119				return err
   120			}
   121			n -= m
   122		}
   123		return nil
   124	}
   125	
   126	// Specified in section B.2.2.
   127	func (d *decoder) processSOF(n int) error {
   128		switch n {
   129		case 6 + 3*nGrayComponent:
   130			d.nComp = nGrayComponent
   131		case 6 + 3*nColorComponent:
   132			d.nComp = nColorComponent
   133		default:
   134			return UnsupportedError("SOF has wrong length")
   135		}
   136		_, err := io.ReadFull(d.r, d.tmp[:n])
   137		if err != nil {
   138			return err
   139		}
   140		// We only support 8-bit precision.
   141		if d.tmp[0] != 8 {
   142			return UnsupportedError("precision")
   143		}
   144		d.height = int(d.tmp[1])<<8 + int(d.tmp[2])
   145		d.width = int(d.tmp[3])<<8 + int(d.tmp[4])
   146		if int(d.tmp[5]) != d.nComp {
   147			return UnsupportedError("SOF has wrong number of image components")
   148		}
   149		for i := 0; i < d.nComp; i++ {
   150			d.comp[i].c = d.tmp[6+3*i]
   151			d.comp[i].tq = d.tmp[8+3*i]
   152			if d.nComp == nGrayComponent {
   153				// If a JPEG image has only one component, section A.2 says "this data
   154				// is non-interleaved by definition" and section A.2.2 says "[in this
   155				// case...] the order of data units within a scan shall be left-to-right
   156				// and top-to-bottom... regardless of the values of H_1 and V_1". Section
   157				// 4.8.2 also says "[for non-interleaved data], the MCU is defined to be
   158				// one data unit". Similarly, section A.1.1 explains that it is the ratio
   159				// of H_i to max_j(H_j) that matters, and similarly for V. For grayscale
   160				// images, H_1 is the maximum H_j for all components j, so that ratio is
   161				// always 1. The component's (h, v) is effectively always (1, 1): even if
   162				// the nominal (h, v) is (2, 1), a 20x5 image is encoded in three 8x8
   163				// MCUs, not two 16x8 MCUs.
   164				d.comp[i].h = 1
   165				d.comp[i].v = 1
   166				continue
   167			}
   168			hv := d.tmp[7+3*i]
   169			d.comp[i].h = int(hv >> 4)
   170			d.comp[i].v = int(hv & 0x0f)
   171			// For color images, we only support 4:4:4, 4:4:0, 4:2:2 or 4:2:0 chroma
   172			// downsampling ratios. This implies that the (h, v) values for the Y
   173			// component are either (1, 1), (1, 2), (2, 1) or (2, 2), and the (h, v)
   174			// values for the Cr and Cb components must be (1, 1).
   175			if i == 0 {
   176				if hv != 0x11 && hv != 0x21 && hv != 0x22 && hv != 0x12 {
   177					return UnsupportedError("luma downsample ratio")
   178				}
   179			} else if hv != 0x11 {
   180				return UnsupportedError("chroma downsample ratio")
   181			}
   182		}
   183		return nil
   184	}
   185	
   186	// Specified in section B.2.4.1.
   187	func (d *decoder) processDQT(n int) error {
   188		const qtLength = 1 + blockSize
   189		for ; n >= qtLength; n -= qtLength {
   190			_, err := io.ReadFull(d.r, d.tmp[0:qtLength])
   191			if err != nil {
   192				return err
   193			}
   194			pq := d.tmp[0] >> 4
   195			if pq != 0 {
   196				return UnsupportedError("bad Pq value")
   197			}
   198			tq := d.tmp[0] & 0x0f
   199			if tq > maxTq {
   200				return FormatError("bad Tq value")
   201			}
   202			for i := range d.quant[tq] {
   203				d.quant[tq][i] = int32(d.tmp[i+1])
   204			}
   205		}
   206		if n != 0 {
   207			return FormatError("DQT has wrong length")
   208		}
   209		return nil
   210	}
   211	
   212	// Specified in section B.2.4.4.
   213	func (d *decoder) processDRI(n int) error {
   214		if n != 2 {
   215			return FormatError("DRI has wrong length")
   216		}
   217		_, err := io.ReadFull(d.r, d.tmp[0:2])
   218		if err != nil {
   219			return err
   220		}
   221		d.ri = int(d.tmp[0])<<8 + int(d.tmp[1])
   222		return nil
   223	}
   224	
   225	// decode reads a JPEG image from r and returns it as an image.Image.
   226	func (d *decoder) decode(r io.Reader, configOnly bool) (image.Image, error) {
   227		if rr, ok := r.(Reader); ok {
   228			d.r = rr
   229		} else {
   230			d.r = bufio.NewReader(r)
   231		}
   232	
   233		// Check for the Start Of Image marker.
   234		_, err := io.ReadFull(d.r, d.tmp[0:2])
   235		if err != nil {
   236			return nil, err
   237		}
   238		if d.tmp[0] != 0xff || d.tmp[1] != soiMarker {
   239			return nil, FormatError("missing SOI marker")
   240		}
   241	
   242		// Process the remaining segments until the End Of Image marker.
   243		for {
   244			_, err := io.ReadFull(d.r, d.tmp[0:2])
   245			if err != nil {
   246				return nil, err
   247			}
   248			for d.tmp[0] != 0xff {
   249				// Strictly speaking, this is a format error. However, libjpeg is
   250				// liberal in what it accepts. As of version 9, next_marker in
   251				// jdmarker.c treats this as a warning (JWRN_EXTRANEOUS_DATA) and
   252				// continues to decode the stream. Even before next_marker sees
   253				// extraneous data, jpeg_fill_bit_buffer in jdhuff.c reads as many
   254				// bytes as it can, possibly past the end of a scan's data. It
   255				// effectively puts back any markers that it overscanned (e.g. an
   256				// "\xff\xd9" EOI marker), but it does not put back non-marker data,
   257				// and thus it can silently ignore a small number of extraneous
   258				// non-marker bytes before next_marker has a chance to see them (and
   259				// print a warning).
   260				//
   261				// We are therefore also liberal in what we accept. Extraneous data
   262				// is silently ignored.
   263				//
   264				// This is similar to, but not exactly the same as, the restart
   265				// mechanism within a scan (the RST[0-7] markers).
   266				//
   267				// Note that extraneous 0xff bytes in e.g. SOS data are escaped as
   268				// "\xff\x00", and so are detected a little further down below.
   269				d.tmp[0] = d.tmp[1]
   270				d.tmp[1], err = d.r.ReadByte()
   271				if err != nil {
   272					return nil, err
   273				}
   274			}
   275			marker := d.tmp[1]
   276			if marker == 0 {
   277				// Treat "\xff\x00" as extraneous data.
   278				continue
   279			}
   280			for marker == 0xff {
   281				// Section B.1.1.2 says, "Any marker may optionally be preceded by any
   282				// number of fill bytes, which are bytes assigned code X'FF'".
   283				marker, err = d.r.ReadByte()
   284				if err != nil {
   285					return nil, err
   286				}
   287			}
   288			if marker == eoiMarker { // End Of Image.
   289				break
   290			}
   291			if rst0Marker <= marker && marker <= rst7Marker {
   292				// Figures B.2 and B.16 of the specification suggest that restart markers should
   293				// only occur between Entropy Coded Segments and not after the final ECS.
   294				// However, some encoders may generate incorrect JPEGs with a final restart
   295				// marker. That restart marker will be seen here instead of inside the processSOS
   296				// method, and is ignored as a harmless error. Restart markers have no extra data,
   297				// so we check for this before we read the 16-bit length of the segment.
   298				continue
   299			}
   300	
   301			// Read the 16-bit length of the segment. The value includes the 2 bytes for the
   302			// length itself, so we subtract 2 to get the number of remaining bytes.
   303			_, err = io.ReadFull(d.r, d.tmp[0:2])
   304			if err != nil {
   305				return nil, err
   306			}
   307			n := int(d.tmp[0])<<8 + int(d.tmp[1]) - 2
   308			if n < 0 {
   309				return nil, FormatError("short segment length")
   310			}
   311	
   312			switch {
   313			case marker == sof0Marker || marker == sof2Marker: // Start Of Frame.
   314				d.progressive = marker == sof2Marker
   315				err = d.processSOF(n)
   316				if configOnly {
   317					return nil, err
   318				}
   319			case marker == dhtMarker: // Define Huffman Table.
   320				err = d.processDHT(n)
   321			case marker == dqtMarker: // Define Quantization Table.
   322				err = d.processDQT(n)
   323			case marker == sosMarker: // Start Of Scan.
   324				err = d.processSOS(n)
   325			case marker == driMarker: // Define Restart Interval.
   326				err = d.processDRI(n)
   327			case app0Marker <= marker && marker <= app15Marker || marker == comMarker: // APPlication specific, or COMment.
   328				err = d.ignore(n)
   329			default:
   330				err = UnsupportedError("unknown marker")
   331			}
   332			if err != nil {
   333				return nil, err
   334			}
   335		}
   336		if d.img1 != nil {
   337			return d.img1, nil
   338		}
   339		if d.img3 != nil {
   340			return d.img3, nil
   341		}
   342		return nil, FormatError("missing SOS marker")
   343	}
   344	
   345	// Decode reads a JPEG image from r and returns it as an image.Image.
   346	func Decode(r io.Reader) (image.Image, error) {
   347		var d decoder
   348		return d.decode(r, false)
   349	}
   350	
   351	// DecodeConfig returns the color model and dimensions of a JPEG image without
   352	// decoding the entire image.
   353	func DecodeConfig(r io.Reader) (image.Config, error) {
   354		var d decoder
   355		if _, err := d.decode(r, true); err != nil {
   356			return image.Config{}, err
   357		}
   358		switch d.nComp {
   359		case nGrayComponent:
   360			return image.Config{
   361				ColorModel: color.GrayModel,
   362				Width:      d.width,
   363				Height:     d.height,
   364			}, nil
   365		case nColorComponent:
   366			return image.Config{
   367				ColorModel: color.YCbCrModel,
   368				Width:      d.width,
   369				Height:     d.height,
   370			}, nil
   371		}
   372		return image.Config{}, FormatError("missing SOF marker")
   373	}
   374	
   375	func init() {
   376		image.RegisterFormat("jpeg", "\xff\xd8", Decode, DecodeConfig)
   377	}

View as plain text