Files
wuffs/lib/handsum/handsum.go
T

355 lines
9.3 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// Copyright 2025 The Wuffs Authors.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//
// SPDX-License-Identifier: Apache-2.0 OR MIT
// ----------------
// Package handsum implements the Handsum image file format.
//
// This is a very lossy format for very small thumbnails. Very small in terms
// of image dimensions, up to 32×32 pixels, but also in terms of file size.
// Every Handsum image file is exactly 48 bytes (384 bits) long. This can imply
// using as little as 0.046875 bytes (0.375 bits) per pixel.
//
// Each Handsum image is essentially a scaled 16×16 pixel YCbCr 4:2:0 JPEG MCU
// (Minimum Coded Unit; 4 Luma and 2 Chroma blocks), keeping only the 15 lowest
// frequency DCT (Discrete Cosine Transform) coefficients. Each of the (6 × 15)
// = 90 coefficients are encoded as one nibble (4 bits) with fixed quantization
// factors, totalling 45 bytes. The initial 3 bytes holds a 16-bit magic
// signature, 2-bit version number and 6-bit aspect ratio.
//
// As of February 2025, the latest version is Version 0. All Version 0 files
// use the sRGB color profile.
package handsum
import (
"errors"
"image"
"image/color"
"io"
"github.com/google/wuffs/lib/lowleveljpeg"
"golang.org/x/image/draw"
)
// FileSize is the size (in bytes) of every Handsum image file.
const FileSize = 48
// MaxDimension is the maximum (inclusive) width or height of every Handsum
// image file.
//
// Every image is either (W × 32) or (32 × H) or both, for some positive W or H
// that is no greater than 32.
const MaxDimension = 32
// Magic is the byte string prefix of every Handsum image file.
//
// It's like how every JPEG image file starts with "\xFF\xD8".
const Magic = "\xFE\xD7"
func init() {
image.RegisterFormat("handsum", Magic, Decode, DecodeConfig)
}
var (
ErrBadArgument = errors.New("handsum: bad argument")
ErrNotAHandsumFile = errors.New("handsum: not a handsum file")
ErrUnsupportedFileVersion = errors.New("handsum: unsupported file version")
)
// EncodeOptions are optional arguments to Encode. The zero value is valid and
// means to use the default configuration.
//
// There are no fields for now, but there may be some in the future.
type EncodeOptions struct {
}
// Encode writes src to w in the Handsum format.
//
// options may be nil, which means to use the default configuration.
func Encode(w io.Writer, src image.Image, options *EncodeOptions) error {
if (w == nil) || (src == nil) {
return ErrBadArgument
}
srcB := src.Bounds()
srcW, srcH := srcB.Dx(), srcB.Dy()
if (srcW <= 0) || (srcH <= 0) {
return ErrBadArgument
}
aspectRatio := byte(0x1F)
if srcW > srcH { // Landscape.
a := ((int64(srcH) * 64) + int64(srcW)) / (2 * int64(srcW))
if a <= 0 {
a = 1
}
aspectRatio = byte(a-1) | 0x00
} else if srcW < srcH { // Portrait.
a := ((int64(srcW) * 64) + int64(srcH)) / (2 * int64(srcH))
if a <= 0 {
a = 1
}
aspectRatio = byte(a-1) | 0x20
}
dst := image.NewRGBA(image.Rectangle{Max: image.Point{X: 16, Y: 16}})
draw.BiLinear.Scale(dst, dst.Bounds(), src, src.Bounds(), draw.Src, nil)
dstU8s := lowleveljpeg.Array6BlockU8{}
dstU8s.ExtractFrom(dst, 0, 0)
dstI16s := lowleveljpeg.Array6BlockI16{}
dstI16s.ForwardDCTFrom(&dstU8s)
buf := [FileSize]byte{}
buf[0] = Magic[0]
buf[1] = Magic[1]
buf[2] = aspectRatio
bitOffset := 3 * 8
for i := range dstI16s {
bitOffset = encodeBlock(&buf, bitOffset, &dstI16s[i])
}
_, err := w.Write(buf[:])
return err
}
func encodeBlock(buf *[FileSize]byte, bitOffset int, b *lowleveljpeg.BlockI16) int {
for i := 0; i < nCoeffs; i++ {
e := uint8(0)
if i == 0 {
e = encodeDC(b[0])
} else {
e = encodeAC(b[zigzag[i]])
}
buf[bitOffset>>3] |= e << (bitOffset & 4)
bitOffset += 4
}
return bitOffset
}
func encodeDC(value int16) uint8 {
const w = dcBucketWidth
v := int32(value) + ((w * 8) + (w / 2))
v /= w
if v < 0x0 {
return 0x0
} else if v > 0xF {
return 0xF
}
return uint8(v)
}
func encodeAC(value int16) uint8 {
// Dividing by 2 is an arbitrary adjustment that's not mirrored on the
// decode side, but the results seem a little more vibrant.
const w = acBucketWidth / 2
v := int32(value) + ((w * 8) + (w / 2))
v /= w
if v < 0x0 {
return 0x0
} else if v > 0xF {
return 0xF
}
return uint8(v)
}
// Both DC and AC coefficients are quantized into 16 buckets (4 bits), but they
// use different bucket widths:
//
// Bucket DC AC
// 0x0 -1024 -128
// 0x1 -896 -112
// 0x2 -768 -96
// 0x3 -640 -80
// ... ... ...
// 0x7 -128 -16
// 0x8 0 0
// 0x9 +128 +16
// ... ... ...
// 0xE +768 +96
// 0xF +896 +112
const (
dcBucketWidth = 128
acBucketWidth = 16
)
// DecodeConfig reads a Handsum image configuration from r.
func DecodeConfig(r io.Reader) (image.Config, error) {
buf := [3]byte{}
if _, err := io.ReadFull(r, buf[:]); err != nil {
return image.Config{}, err
} else if (buf[0] != Magic[0]) || (buf[1] != Magic[1]) {
return image.Config{}, ErrNotAHandsumFile
} else if (buf[2] & 0xC0) != 0 {
return image.Config{}, ErrUnsupportedFileVersion
}
w, h := decodeWidthAndHeight(buf[2])
return image.Config{
ColorModel: color.RGBAModel,
Width: w,
Height: h,
}, nil
}
// Decode reads a Handsum image from r.
func Decode(r io.Reader) (image.Image, error) {
buf := [FileSize]byte{}
if _, err := io.ReadFull(r, buf[:]); err != nil {
return nil, err
} else if (buf[0] != Magic[0]) || (buf[1] != Magic[1]) {
return nil, ErrNotAHandsumFile
} else if (buf[2] & 0xC0) != 0 {
return nil, ErrUnsupportedFileVersion
}
bitOffset := 3 * 8
lumaQuadBlockU8 := lowleveljpeg.QuadBlockU8{}
bitOffset = decodeBlock(lumaQuadBlockU8[0x00:], 16, &buf, bitOffset)
bitOffset = decodeBlock(lumaQuadBlockU8[0x08:], 16, &buf, bitOffset)
bitOffset = decodeBlock(lumaQuadBlockU8[0x80:], 16, &buf, bitOffset)
bitOffset = decodeBlock(lumaQuadBlockU8[0x88:], 16, &buf, bitOffset)
smoothLumaBlockSeams(&lumaQuadBlockU8)
cbBlockU8 := lowleveljpeg.BlockU8{}
bitOffset = decodeBlock(cbBlockU8[:], 8, &buf, bitOffset)
cbQuadBlockU8 := lowleveljpeg.QuadBlockU8{}
cbQuadBlockU8.UpsampleFrom(&cbBlockU8)
crBlockU8 := lowleveljpeg.BlockU8{}
bitOffset = decodeBlock(crBlockU8[:], 8, &buf, bitOffset)
crQuadBlockU8 := lowleveljpeg.QuadBlockU8{}
crQuadBlockU8.UpsampleFrom(&crBlockU8)
src := &image.YCbCr{
Y: lumaQuadBlockU8[:],
Cb: cbQuadBlockU8[:],
Cr: crQuadBlockU8[:],
YStride: 16,
CStride: 16,
SubsampleRatio: image.YCbCrSubsampleRatio444,
Rect: image.Rectangle{Max: image.Point{X: 16, Y: 16}},
}
dstW, dstH := decodeWidthAndHeight(buf[2])
dst := image.NewRGBA(image.Rectangle{Max: image.Point{X: dstW, Y: dstH}})
draw.BiLinear.Scale(dst, dst.Bounds(), src, src.Bounds(), draw.Src, nil)
return dst, nil
}
func decodeWidthAndHeight(buf2 byte) (w int, h int) {
if (buf2 & 0x20) == 0 { // Landscape.
w = 32
h = 1 + int(buf2&0x1F)
} else { // Portrait.
w = 1 + int(buf2&0x1F)
h = 32
}
return w, h
}
func decodeBlock(dst []byte, stride int, src *[FileSize]byte, bitOffset int) int {
a := lowleveljpeg.BlockI16{}
{
nibble := (src[bitOffset>>3] >> (bitOffset & 4)) & 15
a[0] = (int16(nibble) - 8) * dcBucketWidth
bitOffset += 4
}
for i := 1; i < nCoeffs; i++ {
nibble := (src[bitOffset>>3] >> (bitOffset & 4)) & 15
a[zigzag[i]] = (int16(nibble) - 8) * acBucketWidth
bitOffset += 4
}
b := lowleveljpeg.BlockU8{}
b.InverseDCTFrom(&a)
for i := 0; i < 8; i++ {
di := i * stride
bi := i * 8
copy(dst[di:di+8], b[bi:bi+8])
}
return bitOffset
}
const nCoeffs = 15
// zigzag represents JPEG's zig-zag order for visiting coefficients. Handsum
// only uses the first (1 + 2 + 3 + 4 + 5) = 15 of JPEG's 64 coefficients.
//
// https://en.wikipedia.org/wiki/File:JPEG_ZigZag.svg
var zigzag = [nCoeffs]uint8{
0o00, 0o01, 0o10, 0o20, 0o11, 0o02, 0o03, 0o12, // 0, 1, 8, 16, 9, 2, 3, 10,
0o21, 0o30, 0o40, 0o31, 0o22, 0o13, 0o04, // 17, 24, 32, 25, 18, 11, 4,
}
func smoothLumaBlockSeams(b *lowleveljpeg.QuadBlockU8) {
for _, pair := range smoothingPairs {
v0 := uint32(b[pair[0]])
v1 := uint32(b[pair[1]])
b[pair[0]] = uint8(((3 * v0) + v1 + 2) / 4)
b[pair[1]] = uint8(((3 * v1) + v0 + 2) / 4)
}
v77 := uint32(b[0x77])
v78 := uint32(b[0x78])
v88 := uint32(b[0x88])
v87 := uint32(b[0x87])
b[0x77] = uint8(((9 * v77) + (3 * v78) + v88 + (3 * v87) + 8) / 16)
b[0x78] = uint8(((9 * v78) + (3 * v88) + v87 + (3 * v77) + 8) / 16)
b[0x88] = uint8(((9 * v88) + (3 * v87) + v77 + (3 * v78) + 8) / 16)
b[0x87] = uint8(((9 * v87) + (3 * v77) + v78 + (3 * v88) + 8) / 16)
}
// smoothingPairs are the seams of the four 8×8 Luma blocks in a 16×16 MCU. The
// central 4 pixels are handled separately.
var smoothingPairs = [28][2]uint8{
{0x07, 0x08},
{0x17, 0x18},
{0x27, 0x28},
{0x37, 0x38},
{0x47, 0x48},
{0x57, 0x58},
{0x67, 0x68},
{0x70, 0x80},
{0x71, 0x81},
{0x72, 0x82},
{0x73, 0x83},
{0x74, 0x84},
{0x75, 0x85},
{0x76, 0x86},
{0x79, 0x89},
{0x7A, 0x8A},
{0x7B, 0x8B},
{0x7C, 0x8C},
{0x7D, 0x8D},
{0x7E, 0x8E},
{0x7F, 0x8F},
{0x97, 0x98},
{0xA7, 0xA8},
{0xB7, 0xB8},
{0xC7, 0xC8},
{0xD7, 0xD8},
{0xE7, 0xE8},
{0xF7, 0xF8},
}