qrcode

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 17, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package qrcode provides QR code generation (with optional logo overlay) and decoding. Generation uses github.com/boombuler/barcode; decoding uses github.com/makiuchi-d/gozxing (a Go port of ZXing). Logo overlay uses the local imageutil package for compositing.

Index

Constants

View Source
const TokenPrefix = "LB1."

TokenPrefix is prepended to every signed/encrypted QR token so that verifiers can quickly distinguish a secure token from plain text.

Variables

This section is empty.

Functions

func Decode

func Decode(img image.Image) (string, error)

Decode reads a QR code from an image and returns the decoded text. If no QR code is found, an error is returned.

func DecodeBytes

func DecodeBytes(data []byte) (string, error)

DecodeBytes decodes a QR code from raw image bytes (PNG, JPEG, etc.).

func DecodeFile

func DecodeFile(path string) (string, error)

DecodeFile reads an image file and decodes the QR code from it.

func Decrypt

func Decrypt(token string, key []byte) (string, error)

Decrypt decodes a token produced by Encrypt and returns the original plaintext payload.

func Encrypt

func Encrypt(payload string, key []byte) (string, error)

Encrypt produces a base64url-encoded token containing the AES-GCM encrypted payload. The token can be embedded in a QR code. Only someone with the same key can decrypt and read the content. The key must be 16, 24, or 32 bytes (AES-128/192/256).

func Generate

func Generate(text string, level ErrorCorrectionLevel, size int) (image.Image, error)

Generate creates a QR code image from the given text. The returned image is scaled to size×size pixels (nearest-neighbor). If size is 0, the unscaled 1-module-per-pixel barcode is returned.

func GenerateFancy

func GenerateFancy(text string, level ErrorCorrectionLevel, opts FancyOptions) ([]byte, error)

GenerateFancy creates a styled QR code and returns it as a PNG-encoded byte slice.

func GenerateFancyImage

func GenerateFancyImage(text string, level ErrorCorrectionLevel, opts FancyOptions) (image.Image, error)

GenerateFancyImage creates a styled QR code and returns it as an image.Image (decoded from the internally-generated PNG).

func GeneratePNG

func GeneratePNG(text string, level ErrorCorrectionLevel, size int) ([]byte, error)

GeneratePNG creates a QR code and encodes it as PNG bytes.

func GenerateSecure

func GenerateSecure(payload string, encryptKey, signKey []byte, level ErrorCorrectionLevel, size int) (image.Image, error)

GenerateSecure generates a QR code whose content is an encrypted + signed token (produced by Secure).

func GenerateSigned

func GenerateSigned(payload string, secret []byte, level ErrorCorrectionLevel, size int) (image.Image, error)

GenerateSigned generates a QR code whose content is a signed token (produced by Sign). This is a convenience for anti-counterfeit labels.

func GenerateWithLogo(text string, level ErrorCorrectionLevel, size int, logo image.Image, logoSize int) (image.Image, error)

GenerateWithLogo creates a QR code with a logo image composited at the center. The logo is scaled to logoSize×logoSize pixels (if logoSize > 0, otherwise it defaults to ~20% of the QR size). A white background plate is drawn behind the logo for readability. The QR code should use at least ECLQuartile or ECLHigh when embedding a logo to maintain scannability.

func GenerateWithLogoFile

func GenerateWithLogoFile(text string, level ErrorCorrectionLevel, size int, logoPath string, logoSize int) (image.Image, error)

GenerateWithLogoFile is like GenerateWithLogo but loads the logo from a file path.

func GenerateWithLogoPNG

func GenerateWithLogoPNG(text string, level ErrorCorrectionLevel, size int, logo image.Image, logoSize int) ([]byte, error)

GenerateWithLogoPNG creates a QR code with a logo and encodes it as PNG.

func IsSecureToken

func IsSecureToken(s string) bool

IsSecureToken returns true if the string looks like a token produced by Sign, Encrypt, or Secure (i.e. it has the TokenPrefix).

func Save

func Save(text, path string, level ErrorCorrectionLevel, size int) error

Save generates a QR code and writes it to a PNG file.

func SaveFancy

func SaveFancy(text, path string, level ErrorCorrectionLevel, opts FancyOptions) error

SaveFancy creates a styled QR code and writes it to a PNG file.

func SaveWithLogo(text, path string, level ErrorCorrectionLevel, size int, logo image.Image, logoSize int) error

SaveWithLogo generates a QR code with a logo and writes it to a PNG file.

func SaveWithLogoFile

func SaveWithLogoFile(text, outputPath string, level ErrorCorrectionLevel, size int, logoPath string, logoSize int) error

SaveWithLogoFile generates a QR code with a logo loaded from a file and writes the result to a PNG file.

func Secure

func Secure(payload string, encryptKey, signKey []byte) (string, error)

Secure produces a token that first AES-GCM encrypts the payload (confidentiality) and then HMAC-signs the ciphertext (integrity). This is the recommended approach for anti-counterfeit labels where both secrecy and tamper detection are required.

The encryptKey must be 16/24/32 bytes; the signKey must be non-empty.

func Sign

func Sign(payload string, secret []byte) (string, error)

Sign produces a base64url-encoded token containing the payload and its HMAC-SHA256 signature. The token can be embedded in a QR code. Anyone with the secret key can later verify the payload's integrity.

func Unseal

func Unseal(token string, encryptKey, signKey []byte, maxAge time.Duration) (string, error)

Unseal verifies and decrypts a token produced by Secure, returning the original plaintext payload. Returns an error if the signature is invalid or decryption fails.

func Verify

func Verify(token string, secret []byte, maxAge time.Duration) (string, error)

Verify checks a token produced by Sign and returns the original payload if the signature is valid. Returns an error if the token is malformed, the signature does not match, or (if maxAge > 0) the token is older than maxAge.

Types

type ColorStop

type ColorStop struct {
	Color color.Color
	T     float64
}

ColorStop represents a single color at position T (0.0 to 1.0).

type ErrorCorrectionLevel

type ErrorCorrectionLevel int

ErrorCorrectionLevel controls the redundancy of the QR code. Higher levels allow more damage (or a larger logo overlay) while remaining readable.

const (
	// ECLLow recovers ~7% of data. Smallest QR, least tolerance.
	ECLLow ErrorCorrectionLevel = iota
	// ECLMedium recovers ~15%. Good general-purpose default.
	ECLMedium
	// ECLQuartile recovers ~25%. Recommended when embedding a logo.
	ECLQuartile
	// ECLHigh recovers ~30%. Maximum tolerance; largest QR.
	ECLHigh
)

type FancyOptions

type FancyOptions struct {
	// Module shape for data blocks. Default: ShapeRectangle.
	Module ModuleShape
	// Finder (corner) shape. Default: FinderSquare.
	Finder FinderShape

	// Foreground color (modules). If FgGradient is set, this is ignored.
	// Default: black.
	FgColor color.Color
	// Background color. If BgTransparent is true, this is ignored.
	// Default: white.
	BgColor color.Color
	// BgTransparent makes the background transparent (PNG only).
	BgTransparent bool

	// FgGradient applies a linear gradient to the foreground modules.
	// If set, FgColor is ignored.
	FgGradient *LinearGradient

	Logo image.Image
	// LogoSizeMultiplier controls logo size relative to QR width.
	// Default is 4 (logo = 1/4 of QR). Use 5 for a smaller logo.
	LogoSizeMultiplier int
	// LogoSafeZone adds a white safe zone around the logo.
	LogoSafeZone bool

	// Halftone image — modules are rendered from this image, creating
	// an artistic QR. Optional.
	Halftone image.Image

	// ModuleWidth is the pixel width of each QR module. Default: 21.
	ModuleWidth uint8
	// BorderWidth is the quiet-zone width in pixels on all 4 sides.
	// Default: 0 (no extra border).
	BorderWidth int
}

FancyOptions controls the visual style of a fancy QR code. All fields are optional; zero values produce sensible defaults.

func FancyCirclePreset

func FancyCirclePreset(fg, bg color.Color) FancyOptions

FancyCirclePreset returns options for a clean circle-module QR with the given foreground and background colors.

func FancyGradientPreset

func FancyGradientPreset(gradient *LinearGradient) FancyOptions

FancyGradientPreset returns options for a circle-module QR with a linear gradient foreground.

func FancyHalftonePreset

func FancyHalftonePreset(src image.Image, fg color.Color) FancyOptions

FancyHalftonePreset returns options for a halftone QR where modules are rendered from the given source image.

func FancyLogoPreset

func FancyLogoPreset(logo image.Image) FancyOptions

FancyLogoPreset returns options for a QR with a logo at the center, rounded finder patterns, and circle modules.

type FinderShape

type FinderShape int

FinderShape describes the visual shape of the three corner finder patterns.

const (
	// FinderRounded renders rounded finder patterns.
	FinderRounded FinderShape = iota
	// FinderSquare renders square finder patterns (default).
	FinderSquare
)

type LinearGradient

type LinearGradient struct {
	Angle float64     // degrees, 0 = horizontal left→right
	Stops []ColorStop // color stops along the gradient
}

LinearGradient is a linear color gradient for QR foreground modules.

func NewLinearGradient

func NewLinearGradient(angle float64, stops ...ColorStop) *LinearGradient

NewLinearGradient creates a linear gradient with the given angle and color stops.

type ModuleShape

type ModuleShape int

ModuleShape describes the visual shape of each QR module (data bit).

const (
	// ShapeRectangle uses the default square modules.
	ShapeRectangle ModuleShape = iota
	// ShapeCircle renders each module as a filled circle.
	ShapeCircle
	// ShapeRounded renders each module as a rounded rectangle.
	ShapeRounded
	// ShapeLiquid renders connected modules as a single liquid blob.
	ShapeLiquid
	// ShapeHStripe renders each module as horizontal stripes.
	ShapeHStripe
	// ShapeVStripe renders each module as vertical stripes.
	ShapeVStripe
	// ShapeDiamond renders each module as a 45° rotated square.
	ShapeDiamond
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL