png

README

png

A fork of Go's image/png, under the same BSD-3-Clause licence. The import path is github.com/go-images/png. Every change is stated in NOTICE, and Go's own test suite passes here unaltered in substance.

What differs: DecodePartial says what a stream that stopped early did decode.

img, rows, err := png.DecodePartial(r)

The image at its full declared size, the number of pixel rows that are complete counting from the top, and the error that stopped the decode — nil when everything arrived. Rows past the count hold whatever the image was allocated with, so a caller draws the first rows and nothing else.

Decode is all-or-nothing, and for a file still arriving that is the same as having nothing: it returns a nil image and not enough pixel data whatever fraction is present. image/jpeg and image/gif answer the same way, so this is a gap in the shape of every decoder rather than in one of them.

What DecodePartial returns for a 150×103 picture:

bytes given	rows offered
20%	25	24.3%
40%	48	46.6%
60%	66	64.1%
80%	84	81.6%
100%	103	100%

The count is exact, in both directions

It never names the row being decoded. A row's bytes are read in one go before anything is stored, so the row that ran out is untouched — and claiming it would hand a caller a band of unfiltered noise.

And it is the largest count that is true. Under-claiming is invisible to a check that only verifies the rows it offers, and it shows a caller less of the picture than arrived. Measured over eleven fixtures covering every colour model this decoder has — grey 8 and 16 bit, RGB 8 and 16, NRGBA, paletted, grey+alpha, RGBA — the first row that differs from the complete decode is the count, every time. The test asserts that equality rather than a tolerance.

What is refused partially

An interlaced (Adam7) image, with a nil image and zero rows. A pass covers a subset of the whole frame — every eighth pixel of every eighth row, then the gaps between them — so "rows from the top" describes nothing about what arrived. A caller told forty rows would draw forty rows of which seven pixels in eight are missing.

So is anything that failed before the first row completed: there is a size, but no picture.

Everything else

Identical to the standard library, including Encode. Use it exactly as you would use image/png.

Documentation

Overview

Package png implements a PNG image decoder and encoder.

The PNG specification is at https://www.w3.org/TR/PNG/.

Index

• func Decode(r io.Reader) (image.Image, error)
• func DecodeConfig(r io.Reader) (image.Config, error)
• func DecodePartial(r io.Reader) (image.Image, int, error)
• func Encode(w io.Writer, m image.Image) error
• type CompressionLevel
• type Encoder
  • func (enc *Encoder) Encode(w io.Writer, m image.Image) error
• type EncoderBuffer
• type EncoderBufferPool
• type FormatError
  • func (e FormatError) Error() string
• type UnsupportedError
  • func (e UnsupportedError) Error() string

Examples

• Decode
• Encode

Functions

func Decode

func Decode(r io.Reader) (image.Image, error)

Decode reads a PNG image from r and returns it as an image.Image. The type of Image returned depends on the PNG contents.

Example

package main

import (
	"encoding/base64"
	"fmt"
	"github.com/go-images/png"
	"image/color"
	"io"
	"log"
	"strings"
)

const gopher = `iVBORw0KGgoAAAANSUhEUgAAAEsAAAA8CAAAAAALAhhPAAAFfUlEQVRYw62XeWwUVRzHf2+OPbo9d7tsWyiyaZti6eWGAhISoIGKECEKCAiJJkYTiUgTMYSIosYYBBIUIxoSPIINEBDi2VhwkQrVsj1ESgu9doHWdrul7ba73WNm3vOPtsseM9MdwvvrzTs+8/t95ze/33sI5BqiabU6m9En8oNjduLnAEDLUsQXFF8tQ5oxK3vmnNmDSMtrncks9Hhtt/qeWZapHb1ha3UqYSWVl2ZmpWgaXMXGohQAvmeop3bjTRtv6SgaK/Pb9/bFzUrYslbFAmHPp+3WhAYdr+7GN/YnpN46Opv55VDsJkoEpMrY/vO2BIYQ6LLvm0ThY3MzDzzeSJeeWNyTkgnIE5ePKsvKlcg/0T9QMzXalwXMlj54z4c0rh/mzEfr+FgWEz2w6uk8dkzFAgcARAgNp1ZYef8bH2AgvuStbc2/i6CiWGj98y2tw2l4FAXKkQBIf+exyRnteY83LfEwDQAYCoK+P6bxkZm/0966LxcAAILHB56kgD95PPxltuYcMtFTWw/FKkY/6Opf3GGd9ZF+Qp6mzJxzuRSractOmJrH1u8XTvWFHINNkLQLMR+XHXvfPPHw967raE1xxwtA36IMRfkAAG29/7mLuQcb2WOnsJReZGfpiHsSBX81cvMKywYZHhX5hFPtOqPGWZCXnhWGAu6lX91ElKXSalcLXu3UaOXVay57ZSe5f6Gpx7J2MXAsi7EqSp09b/MirKSyJfnfEEgeDjl8FgDAfvewP03zZ+AJ0m9aFRM8eEHBDRKjfcreDXnZdQuAxXpT2NRJ7xl3UkLBhuVGU16gZiGOgZmrSbRdqkILuL/yYoSXHHkl9KXgqNu3PB8oRg0geC5vFmLjad6mUyTKLmF3OtraWDIfACyXqmephaDABawfpi6tqqBZytfQMqOz6S09iWXhktrRaB8Xz4Yi/8gyABDm5NVe6qq/3VzPrcjELWrebVuyY2T7ar4zQyybUCtsQ5Es1FGaZVrRVQwAgHGW2ZCRZshI5bGQi7HesyE972pOSeMM0dSktlzxRdrlqb3Osa6CCS8IJoQQQgBAbTAa5l5epO34rJszibJI8rxLfGzcp1dRosutGeb2VDNgqYrwTiPNsLxXiPi3dz7LiS1WBRBDBOnqEjyy3aQb+/bLiJzz9dIkscVBBLxMfSEac7kO4Fpkngi0ruNBeSOal+u8jgOuqPz12nryMLCniEjtOOOmpt+KEIqsEdocJjYXwrh9OZqWJQyPCTo67LNS/TdxLAv6R5ZNK9npEjbYdT33gRo4o5oTqR34R+OmaSzDBWsAIPhuRcgyoteNi9gF0KzNYWVItPf2TLoXEg+7isNC7uJkgo1iQWOfRSP9NR11RtbZZ3OMG/VhL6jvx+J1m87+RCfJChAtEBQkSBX2PnSiihc/Twh3j0h7qdYQAoRVsRGmq7HU2QRbaxVGa1D6nIOqaIWRjyRZpHMQKWKpZM5feA+lzC4ZFultV8S6T0mzQGhQohi5I8iw+CsqBSxhFMuwyLgSwbghGb0AiIKkSDmGZVmJSiKihsiyOAUs70UkywooYP0bii9GdH4sfr1UNysd3fUyLLMQN+rsmo3grHl9VNJHbbwxoa47Vw5gupIqrZcjPh9R4Nye3nRDk199V+aetmvVtDRE8/+cbgAAgMIWGb3UA0MGLE9SCbWX670TDy1y98c3D27eppUjsZ6fql3jcd5rUe7+ZIlLNQny3Rd+E5Tct3WVhTM5RBCEdiEK0b6B+/ca2gYU393nFj/n1AygRQxPIUA043M42u85+z2SnssKrPl8Mx76NL3E6eXc3be7OD+H4WHbJkKI8AU8irbITQjZ+0hQcPEgId/Fn/pl9crKH02+5o2b9T/eMx7pKoskYgAAAABJRU5ErkJggg==`

// gopherPNG creates an io.Reader by decoding the base64 encoded image data string in the gopher constant.
func gopherPNG() io.Reader { return base64.NewDecoder(base64.StdEncoding, strings.NewReader(gopher)) }

func main() {
	// This example uses png.Decode which can only decode PNG images.
	// Consider using the general image.Decode as it can sniff and decode any registered image format.
	img, err := png.Decode(gopherPNG())
	if err != nil {
		log.Fatal(err)
	}

	levels := []string{" ", "░", "▒", "▓", "█"}

	for y := img.Bounds().Min.Y; y < img.Bounds().Max.Y; y++ {
		for x := img.Bounds().Min.X; x < img.Bounds().Max.X; x++ {
			c := color.GrayModel.Convert(img.At(x, y)).(color.Gray)
			level := c.Y / 51 // 51 * 5 = 255
			if level == 5 {
				level--
			}
			fmt.Print(levels[level])
		}
		fmt.Print("\n")
	}
}

func DecodeConfig

func DecodeConfig(r io.Reader) (image.Config, error)

DecodeConfig returns the color model and dimensions of a PNG image without decoding the entire image.

func DecodePartial

func DecodePartial(r io.Reader) (image.Image, int, error)

DecodePartial decodes as much of a PNG as r holds, and says how much is real.

func Encode

func Encode(w io.Writer, m image.Image) error

Encode writes the Image m to w in PNG format. Any Image may be encoded, but images that are not image.NRGBA might be encoded lossily.

Example

package main

import (
	"github.com/go-images/png"
	"image"
	"image/color"
	"log"
	"os"
)

func main() {
	const width, height = 256, 256

	// Create a colored image of the given width and height.
	img := image.NewNRGBA(image.Rect(0, 0, width, height))

	for y := 0; y < height; y++ {
		for x := 0; x < width; x++ {
			img.Set(x, y, color.NRGBA{
				R: uint8((x + y) & 255),
				G: uint8((x + y) << 1 & 255),
				B: uint8((x + y) << 2 & 255),
				A: 255,
			})
		}
	}

	f, err := os.Create("image.png")
	if err != nil {
		log.Fatal(err)
	}

	if err := png.Encode(f, img); err != nil {
		f.Close()
		log.Fatal(err)
	}

	if err := f.Close(); err != nil {
		log.Fatal(err)
	}
}

Types

type CompressionLevel

type CompressionLevel int

CompressionLevel indicates the compression level.

const (
	DefaultCompression CompressionLevel = 0
	NoCompression      CompressionLevel = -1
	BestSpeed          CompressionLevel = -2
	BestCompression    CompressionLevel = -3
)

type Encoder

type Encoder struct {
	CompressionLevel CompressionLevel

	// BufferPool optionally specifies a buffer pool to get temporary
	// EncoderBuffers when encoding an image.
	BufferPool EncoderBufferPool
}

Encoder configures encoding PNG images.

func (*Encoder) Encode

func (enc *Encoder) Encode(w io.Writer, m image.Image) error

Encode writes the Image m to w in PNG format.

type EncoderBuffer

type EncoderBuffer encoder

EncoderBuffer holds the buffers used for encoding PNG images.

type EncoderBufferPool

type EncoderBufferPool interface {
	Get() *EncoderBuffer
	Put(*EncoderBuffer)
}

EncoderBufferPool is an interface for getting and returning temporary instances of the EncoderBuffer struct. This can be used to reuse buffers when encoding multiple images.

type FormatError

type FormatError string

A FormatError reports that the input is not a valid PNG.

func (FormatError) Error

func (e FormatError) Error() string

type UnsupportedError

type UnsupportedError string

An UnsupportedError reports that the input uses a valid but unimplemented PNG feature.

func (UnsupportedError) Error

func (e UnsupportedError) Error() string