mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-21 08:47:28 +01:00
cmd/handsum: new tool for the Handsum file format
This commit is contained in:
1 parent
9a7e2a4d06
commit
12b404f58d
6 files changed
+536
No files matched your search
@@ -0,0 +1,345 @@
|
||||
// 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")
|
||||
)
|
||||
|
||||
// Encode writes src to w in the Handsum format.
|
||||
func Encode(w io.Writer, src image.Image) 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},
|
||||
}
|
||||
Reference in new issue
Block a user