heic

Documentation

Overview

Package heic decodes HEIF images that carry HEVC-coded item data, the format commonly called HEIC.

Color

Decode returns RGB, converted with the matrix and range the file declares in its nclx color description. Options.ToYCbCr skips that and hands back the planes the bitstream carries: *image.YCbCr, *image.NYCbCrA with alpha, or *image.Gray for monochrome. Above 8 bits there is no such image type, so *image.NRGBA64 is returned anyway.

image.YCbCr reads its planes as full-range BT.601 whatever the file signals, which is rarely what a HEIC file means. DecodeColor reports what they actually are, so ToYCbCr is for reaching the samples rather than for display:

img, ci, err := heic.DecodeColor(r, heic.Options{ToYCbCr: true})

ColorInfo carries the CICP code points and the range flag, plus the ICC profile when the file has one. Matrix and FullRange are what the conversion to RGB uses. Primaries and Transfer are reported but not applied, so RGB output stays in the file's own color space.

Metadata

DecodeExif reads the Exif item a file describes its image with, and RawExif and RawXMP return the payloads unparsed.

Index

• Constants
• Variables
• func Decode(r io.Reader, opts ...Options) (image.Image, error)
• func DecodeConfig(r io.Reader) (image.Config, error)
• func RawExif(r io.Reader) ([]byte, error)
• func RawXMP(r io.Reader) ([]byte, error)
• type ColorInfo
  • func DecodeColor(r io.Reader, opts ...Options) (image.Image, ColorInfo, error)
• type Exif
  • func DecodeExif(r io.Reader) (*Exif, error)
• type HEIC
  • func DecodeAll(r io.Reader, opts ...Options) (*HEIC, error)
• type Options

Constants

const DefaultFrameSizeLimit = 16384 * 16384

DefaultFrameSizeLimit bounds the pixel area a header may ask to allocate.

Variables

var ErrInvalid = errors.New("heic: invalid file")

ErrInvalid is returned when a file is not a HEIF, or is malformed past the point where anything can be decoded from it.

var ErrNoExif = errors.New("avif: no exif data")

ErrNoExif is returned when the file carries no Exif item.

var ErrNoXMP = errors.New("avif: no xmp data")

ErrNoXMP is returned when the file carries no XMP item.

var ErrUnsupported = errors.New("heic: unsupported image")

ErrUnsupported is returned for a file this package cannot render but which is otherwise well formed: an essential property it does not implement, or a sample format it has no conversion for. A caller that has another decoder to fall back on should test for this one rather than ErrInvalid.

Functions

func Decode

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

Decode reads a HEIC image as *image.NRGBA, or *image.NRGBA64 above 8 bits.

func DecodeConfig

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

DecodeConfig returns the dimensions and color model without decoding the image data.

func RawExif

func RawExif(r io.Reader) ([]byte, error)

RawExif returns the TIFF payload of the Exif item, without the exif_tiff_header_offset the HEIC container puts in front of it. It aliases the input, so it is not a copy.

func RawXMP

func RawXMP(r io.Reader) ([]byte, error)

RawXMP returns the XMP packet of the file. It aliases the input, so it is not a copy.

Types

type ColorInfo

type ColorInfo struct {
	Primaries uint16
	Transfer  uint16
	Matrix    uint16
	FullRange bool
	// ICCP is the embedded ICC profile, for files that carry one in place of
	// an nclx description. It aliases the input, so it is not a copy.
	ICCP []byte
}

ColorInfo describes the color space an image was decoded from.

func DecodeColor

func DecodeColor(r io.Reader, opts ...Options) (image.Image, ColorInfo, error)

DecodeColor is Decode, and also reports the color space the image was decoded from.

type Exif

type Exif struct {
	// Orientation is the Exif orientation, 1 to 8, where 1 is upright.
	Orientation int
	// Width and Height are the dimensions the Exif tags report, which need
	// not be the dimensions the image decodes to.
	Width  int
	Height int

	// Make and Model name the camera, Software what wrote the file.
	Make     string
	Model    string
	Software string

	// DateTime and DateTimeOriginal are "YYYY:MM:DD HH:MM:SS", the first the
	// file's own time and the second the time the photo was taken.
	DateTime         string
	DateTimeOriginal string

	// ExposureTime is in seconds and FocalLength in millimetres.
	ExposureTime float64
	FNumber      float64
	ISOSpeed     int
	FocalLength  float64
	Flash        int

	// GPSLatitude and GPSLongitude are decimal degrees, positive north and
	// east. GPSAltitude is metres above sea level.
	GPSLatitude  float64
	GPSLongitude float64
	GPSAltitude  float64

	Copyright string
	Artist    string
}

Exif holds the Exif metadata decoded from an HEIC image.

func DecodeExif

func DecodeExif(r io.Reader) (*Exif, error)

DecodeExif reads the Exif metadata of an HEIC image. Tags the file omits stay zero. It returns ErrNoExif when the file carries no Exif item.

type HEIC

type HEIC struct {
	// Image holds the decoded frames, *image.NRGBA or *image.NRGBA64.
	Image []image.Image
	// Delay holds each frame's duration in seconds.
	Delay []float64
	// LoopCount controls how many times the animation restarts, following
	// image/gif: zero loops forever, -1 shows each frame once, and any other
	// value plays the animation LoopCount+1 times.
	LoopCount int
	// Color describes the color space the frames were decoded from.
	Color ColorInfo
}

HEIC holds the images of a file, which may be an image sequence.

func DecodeAll

func DecodeAll(r io.Reader, opts ...Options) (*HEIC, error)

DecodeAll returns every frame of an image sequence with its duration, and how many times the animation repeats. A still image gives one frame.

type Options

type Options struct {
	// AutoRotate applies the clap/irot/imir transforms, forcing NRGBA output
	// when it transforms.
	AutoRotate bool
	// FrameSizeLimit bounds a frame's area in pixels. Zero means
	// DefaultFrameSizeLimit; a negative value removes the limit.
	FrameSizeLimit int
	// ToYCbCr forces the image's native color space instead of NRGBA:
	// *image.YCbCr, *image.NYCbCrA when there is alpha, or *image.Gray when
	// the image is monochrome. Above 8 bits NRGBA64 is returned anyway.
	// image.YCbCr reads the planes as full-range BT.601 whatever the file
	// signals, so this is for reaching the samples, not for display.
	// DecodeColor reports what the samples actually are.
	ToYCbCr bool
	// Threads bounds the goroutines a decode may use, over the tiles of a grid
	// and the wavefront rows within each. Zero means GOMAXPROCS; one decodes
	// serially.
	Threads int
}

Options controls decoding.