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
- func Decode(img image.Image) (string, error)
- func DecodeBytes(data []byte) (string, error)
- func DecodeFile(path string) (string, error)
- func Decrypt(token string, key []byte) (string, error)
- func Encrypt(payload string, key []byte) (string, error)
- func Generate(text string, level ErrorCorrectionLevel, size int) (image.Image, error)
- func GenerateFancy(text string, level ErrorCorrectionLevel, opts FancyOptions) ([]byte, error)
- func GenerateFancyImage(text string, level ErrorCorrectionLevel, opts FancyOptions) (image.Image, error)
- func GeneratePNG(text string, level ErrorCorrectionLevel, size int) ([]byte, error)
- func GenerateSecure(payload string, encryptKey, signKey []byte, level ErrorCorrectionLevel, ...) (image.Image, error)
- func GenerateSigned(payload string, secret []byte, level ErrorCorrectionLevel, size int) (image.Image, error)
- func GenerateWithLogo(text string, level ErrorCorrectionLevel, size int, logo image.Image, ...) (image.Image, error)
- func GenerateWithLogoFile(text string, level ErrorCorrectionLevel, size int, logoPath string, ...) (image.Image, error)
- func GenerateWithLogoPNG(text string, level ErrorCorrectionLevel, size int, logo image.Image, ...) ([]byte, error)
- func IsSecureToken(s string) bool
- func Save(text, path string, level ErrorCorrectionLevel, size int) error
- func SaveFancy(text, path string, level ErrorCorrectionLevel, opts FancyOptions) error
- func SaveWithLogo(text, path string, level ErrorCorrectionLevel, size int, logo image.Image, ...) error
- func SaveWithLogoFile(text, outputPath string, level ErrorCorrectionLevel, size int, logoPath string, ...) error
- func Secure(payload string, encryptKey, signKey []byte) (string, error)
- func Sign(payload string, secret []byte) (string, error)
- func Unseal(token string, encryptKey, signKey []byte, maxAge time.Duration) (string, error)
- func Verify(token string, secret []byte, maxAge time.Duration) (string, error)
- type ColorStop
- type ErrorCorrectionLevel
- type FancyOptions
- type FinderShape
- type LinearGradient
- type ModuleShape
Constants ¶
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 ¶
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 ¶
DecodeBytes decodes a QR code from raw image bytes (PNG, JPEG, etc.).
func DecodeFile ¶
DecodeFile reads an image file and decodes the QR code from it.
func Decrypt ¶
Decrypt decodes a token produced by Encrypt and returns the original plaintext payload.
func Encrypt ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Types ¶
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 to place at the center. Optional.
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 )