kernels.go

// Package kernels provides dilation kernels and bitmap transforms for
// reshaping the per-pixel ink footprint of an Ncode bitmap before it is
// rendered into a PDF.
//
// The default NcodeSDK output places exactly one ink pixel per Ncode dot
// (isBold=false) or a 2×2 cluster (isBold=true). On office laser printers
// neither shape is universally optimal: the 1 px dot beats the printer's
// halftone screen and gets dropped, while the 2×2 cluster blocks too
// much background and reduces the legibility of the underlying artwork.
//
// The kernels in this file replace the cluster with sub-pixel-precise
// shapes that consistently survive print and remain inside the Anoto
// dot-period guarantee:
//
//   - Tri3Up / Tri3Down: 3-pixel triangles, alternated row-major to
//     average out any halftone interaction with a single orientation.
//     This is the recommended production default.
//   - Tri4Up / Tri4Down: 4-pixel filled triangles. Slightly more ink
//     than Tri3 — used as a fallback when Tri3 proves marginal.
//   - Diamond4: 4-pixel cardinal-flank diamond. Same ink count as the
//     SDK 2×2 cluster, but distributed so the printed footprint reads
//     visually lighter.
//
// All kernels keep their footprint within ±1 pixel of the original
// SDK nobold pixel, so the dilated cluster stays inside the same
// Anoto cell (~9 px pitch at 600 DPI) and the pen's IR camera reads
// the same Ncode coordinate. The Tri3Up/Tri3Down alternating pair and
// Diamond4 (alone) additionally satisfy the stronger property that
// the *exact* average pixel position equals the original SDK pixel.
package kernels

import "github.com/Post-Math/Ncode-SDK-for-Linux/pattern"

// Kernel is an offset list. Each (dx, dy) is added to a zero pixel's
// (x, y) to produce one of its dilated descendants. Out-of-bounds
// descendants are dropped during application.
type Kernel = [][2]int

var (
	// Tri3Up is the 3-pixel triangle pointing up (▲): center pixel +
	// two flanks on the row below.
	//
	//   . X .   ← (0, 0)
	//   X . X   ← (-1, 1), (1, 1)
	Tri3Up Kernel = [][2]int{{0, 0}, {-1, 1}, {1, 1}}

	// Tri3Down is the 3-pixel triangle pointing down (▽): center pixel
	// + two flanks on the row above. Mirror of Tri3Up.
	//
	//   X . X   ← (-1, -1), (1, -1)
	//   . X .   ← (0, 0)
	Tri3Down Kernel = [][2]int{{0, 0}, {-1, -1}, {1, -1}}

	// Tri4Up is the 4-pixel filled triangle pointing up: center pixel
	// + 3-pixel base on the row below.
	//
	//   . X .       ← (0, 0)
	//   X X X       ← (-1, 1), (0, 1), (1, 1)
	Tri4Up Kernel = [][2]int{{0, 0}, {-1, 1}, {0, 1}, {1, 1}}

	// Tri4Down is the 4-pixel filled triangle pointing down: 3-pixel
	// top row + center pixel below. Mirror of Tri4Up.
	//
	//   X X X       ← (-1, 0), (0, 0), (1, 0)
	//   . X .       ← (0, 1)
	Tri4Down Kernel = [][2]int{{-1, 0}, {0, 0}, {1, 0}, {0, 1}}

	// Diamond4 is the 4-pixel cardinal-flank diamond — same pixel
	// count as the SDK isBold 2×2 cluster but distributed so the
	// printed footprint reads visually lighter.
	//
	//   . X .       ← (0, -1)
	//   X . X       ← (-1, 0), (1, 0)
	//   . X .       ← (0, 1)
	Diamond4 Kernel = [][2]int{{0, -1}, {-1, 0}, {1, 0}, {0, 1}}
)

// ApplyAlternating returns a copy of bm where zero pixels alternate
// between kernelA and kernelB in row-major discovery order. With
// kernelA = Tri3Up and kernelB = Tri3Down, consecutive Anoto dots
// print as ▲▽▲▽…, distributing the cluster orientation across the
// page so any halftone-screen interaction averages out across the
// two shapes rather than locking to one.
//
// Both kernels must be non-empty; if either is empty, falls through to
// ApplyKernel(bm, kernelA).
func ApplyAlternating(bm pattern.Bitmap, kernelA, kernelB Kernel) pattern.Bitmap {
	if len(kernelA) == 0 || len(kernelB) == 0 {
		return ApplyKernel(bm, kernelA)
	}
	dst := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
	idx := 0
	for y := range bm.Height {
		for x := range bm.Width {
			if bm.PixelAt(x, y) != 0 {
				continue
			}
			kernel := kernelA
			if idx%2 == 1 {
				kernel = kernelB
			}
			idx++
			for _, k := range kernel {
				nx, ny := x+k[0], y+k[1]
				if nx >= 0 && nx < bm.Width && ny >= 0 && ny < bm.Height {
					dst.SetPixel(nx, ny, 0)
				}
			}
		}
	}
	return dst
}

// ApplyKernel returns a copy of bm where every zero pixel is duplicated
// at every (dx, dy) offset in kernel. Out-of-bounds offsets drop
// silently. Useful for small-cluster shapes (3-pixel L, 4-pixel diamond,
// …) that the bulk helpers cannot express because their kernels are
// circumscribed.
//
// kernel == nil → identity copy (no-op).
func ApplyKernel(bm pattern.Bitmap, kernel Kernel) pattern.Bitmap {
	if len(kernel) == 0 {
		out := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
		copy(out.Data, bm.Data)
		return out
	}
	dst := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
	for y := range bm.Height {
		for x := range bm.Width {
			if bm.PixelAt(x, y) != 0 {
				continue
			}
			for _, k := range kernel {
				nx, ny := x+k[0], y+k[1]
				if nx >= 0 && nx < bm.Width && ny >= 0 && ny < bm.Height {
					dst.SetPixel(nx, ny, 0)
				}
			}
		}
	}
	return dst
}

// ApplySquare returns a copy of bm where every zero pixel is expanded
// to an n×n filled square anchored at the original pixel's top-left
// corner. n=1 is a no-op. n=2 produces the same 2×2 footprint SDK
// isBold=true emits, n=3 a 3×3 cluster, etc.
func ApplySquare(bm pattern.Bitmap, n int) pattern.Bitmap {
	if n <= 1 {
		out := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
		copy(out.Data, bm.Data)
		return out
	}
	dst := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
	for y := range bm.Height {
		for x := range bm.Width {
			if bm.PixelAt(x, y) != 0 {
				continue
			}
			for dy := range n {
				for dx := range n {
					nx, ny := x+dx, y+dy
					if nx >= 0 && nx < bm.Width && ny >= 0 && ny < bm.Height {
						dst.SetPixel(nx, ny, 0)
					}
				}
			}
		}
	}
	return dst
}

// ApplyDisc returns a copy of bm where every zero pixel is expanded to
// a filled disc of radius r (in pixels) centred on the original pixel.
// r=0 is a no-op. r=1 produces a 5-pixel plus sign. r=2 a 13-pixel
// near-circular blob.
func ApplyDisc(bm pattern.Bitmap, r float64) pattern.Bitmap {
	if r <= 0 {
		out := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
		copy(out.Data, bm.Data)
		return out
	}
	rInt := int(r) + 1
	rSq := r * r
	kernel := make([]struct{ dx, dy int }, 0, (2*rInt+1)*(2*rInt+1))
	for dy := -rInt; dy <= rInt; dy++ {
		for dx := -rInt; dx <= rInt; dx++ {
			if float64(dx*dx+dy*dy) <= rSq {
				kernel = append(kernel, struct{ dx, dy int }{dx, dy})
			}
		}
	}
	dst := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
	for y := range bm.Height {
		for x := range bm.Width {
			if bm.PixelAt(x, y) != 0 {
				continue
			}
			for _, k := range kernel {
				nx, ny := x+k.dx, y+k.dy
				if nx >= 0 && nx < bm.Width && ny >= 0 && ny < bm.Height {
					dst.SetPixel(nx, ny, 0)
				}
			}
		}
	}
	return dst
}

// ReduceClusterTopLefts returns a copy of bm where each connected
// zero-pixel cluster is collapsed to its single top-left pixel; every
// other previously-zero pixel becomes 1 (background). The result is
// what the SDK would have emitted with isBold=false (one ink pixel per
// Ncode dot), regardless of the isBold flag that produced bm.
//
// Detection rule: a zero pixel is a cluster's top-left iff its
// immediate left and top neighbours are background. SDK isBold=true
// emits 2×2 clusters where the top-left pixel sits at the original
// nobold dot position; reducing to that pixel therefore aligns the
// bold and nobold paths on identical grid coordinates.
//
// Limitation: the algorithm relies on at least one row + one column
// of background between every pair of bold clusters. The full Anoto
// pattern guarantees a minimum cell pitch of ~9 px at 600 DPI, so
// adjacent clusters always have ≥7 background pixels between them.
func ReduceClusterTopLefts(bm pattern.Bitmap) pattern.Bitmap {
	out := pattern.NewBlankBitmap(bm.Width, bm.Height, bm.DPI)
	for y := range bm.Height {
		for x := range bm.Width {
			if bm.PixelAt(x, y) != 0 {
				continue
			}
			if x > 0 && bm.PixelAt(x-1, y) == 0 {
				continue
			}
			if y > 0 && bm.PixelAt(x, y-1) == 0 {
				continue
			}
			out.SetPixel(x, y, 0)
		}
	}
	return out
}