qrcode

README

QRCode Package

This package is a implementation of QR code encoding in Go. It offers an idiomatic Go implementation of QR code encoding, requires only an golang.org/x/text dependency, maintainable by the Go team.

Features

• all modes (numeric, alphanumeric, byte, kanji, eci)
• Micro QR codes
• export to PNG/JPEG/GIF
• ECI (Extended Channel Interpretation)
• requires only an golang.org/x/text dependency
• covered by unit/functional tests

Installation

go get github.com/verte-zerg/qrcode

Usage

Import

import "github.com/verte-zerg/qrcode"

Create QR code

qr, err := qrcode.Create("https://example.com", nil)
if err != nil {
    panic(err)
}

Plot QR code

file, err := os.Create("qrcode.png")
if err != nil {
    panic(err)
}

defer file.Close()

if err := qr.Plot(file, nil); err != nil {
    fmt.Println(err)
}

Options

The qrcode.Create function accepts an Options struct as a second argument. The Options struct has the following fields:

type QRCodeOptions struct {
	// Encoding is the encoding mode.
	// Default: calculated based on the content (numeric, alphanumeric, byte, kanji or utf-8 with ECI)
	Mode encode.EncodingMode

	// Level is the error correction level.
	// Default: ErrorCorrectionLevelLow.
	ErrorLevel ErrorCorrectionLevel

	// Version is the version of the QR Code.
	// Default: calculated based on the content.
	Version int

	// Enable micro QR code
	// Default: false
	MicroQR bool
}

You can specify the encoding mode, error correction level, version and enable micro QR code.

Supported encoding modes:

• encode.EncodingModeNumeric
• encode.EncodingModeAlphanumeric
• encode.EncodingModeByte
• encode.EncodingModeKanji
• encode.EncodingModeECI

Supported error correction levels:

• ErrorCorrectionLevelLow
• ErrorCorrectionLevelMedium
• ErrorCorrectionLevelQuartile
• ErrorCorrectionLevelHigh

If Micro QR code is enabled, the version must be between M1 and M4. Micro QR code version constants:

• M1 (-1)
• M2 (-2)
• M3 (-3)
• M4 (-4)

If you want to use specific ECI mode, you can use qrcode.CreateMultiMode function. The function can build QR code with several blocks of data with different modes.

import (
    "github.com/verte-zerg/qrcode"
    "github.com/verte-zerg/qrcode/encode"
)

func main() {
	encodeBlocks := []*encode.EncodeBlock{
		{
			Mode: encode.EncodingModeNumeric,
			Data: "1234567890",
		},
		{
			Mode:             encode.EncodingModeECI,
			Data:             "привет мир",
			SubMode:          encode.EncodingModeByte,  // The mode must be always equal to EncodingModeByte for ECI
			AssignmentNumber: encode.ISO8859_5, // cyrillic
		},
	}

	qr, err := CreateMultiMode(encodeBlocks, nil)
	if err != nil {
		panic(err)
	}

	file, err := os.Create("qrcode_mix.png")
	if err != nil {
		panic(err)
	}

	defer file.Close()

	if err := qr.Plot(file, nil); err != nil {
		panic(err)
	}
}

The list of supported ECI assignments can be found in the encode package.

You can specify several plot options using the PlotOptions struct:

type PlotOptions struct {
	// Scale is the scale for the QR Code image (in pixels).
	// The image will be len(data) * Scale x len(data) * Scale pixels.
	// Default: 4.
	Scale int

	// Border is the border for the QR Code image (in pixels).
	// Default: 0.
	Border int

	// OutputFormat is the format of the output image.
	// Default: PNG.
	OutputFormat OutputFormat
}

Supported output formats:

• PNG
• JPEG
• GIF

Functions

Create(content string, options *QRCodeOptions) (*QRCode, error) - creates a QR code with the specified content and options. CreateMultiMode(blocks []*encode.EncodeBlock, options *QRCodeOptionsMultiMode) (*QRCode, error) - creates a QR code with the specified blocks of data and options. (qr *QRCode) Plot(writer io.Writer, options *PlotOptions) error - plots the QR code with the specified options to the writer.

Roadmap

Features

• add predefined QR code types (vCard, WiFi, etc.)
• support other image formats (JPEG, GIF, etc.)
• data optimization algorithm
• custom data encoding
• structured append codes
• custom colors
• different shapes for the markers
• support adding a logo to the QR code

License

This package is licensed under the MIT License. See the LICENSE file for details.

Contributing

If you find a bug or want to contribute to the code or documentation, you can help by submitting an issue or a pull request.

Documentation

Index

• Constants
• Variables
• type Cell
• type CellType
• type ErrorCorrectionLevel
• type OutputFormat
• type PlotOptions
• type QRCode
  • func Create(content string, options *QRCodeOptions) (*QRCode, error)
  • func CreateMultiMode(blocks []*encode.EncodeBlock, options *QRCodeOptionsMultiMode) (*QRCode, error)
  • func (qr *QRCode) Plot(writer io.Writer, options *PlotOptions) error
• type QRCodeOptions
• type QRCodeOptionsMultiMode

Constants

const (
	// Output formats
	PNG  = "png"
	JPEG = "jpeg"
	GIF  = "gif"
)

const (
	// DEFAULT_SCALE is the default scale for the QR Code image.
	DEFAULT_SCALE = 4

	// DEFAULT_BORDER is the default border for the QR Code image.
	DEFAULT_BORDER = 0

	// DEFAULT_OUTPUT_FORMAT is the default output format for the QR Code image.
	DEFAULT_OUTPUT_FORMAT = PNG
)

const (
	// MicroQR versions
	M1 = -1
	M2 = -2
	M3 = -3
	M4 = -4
)

Variables

var ErrContentTooLong = fmt.Errorf("content is too long")

Types

type Cell

type Cell struct {
	Value bool
	Type  CellType
}

Cell represents a cell in the QR code matrix with a value and a type.

type CellType

type CellType int

const (
	CellTypeData CellType = iota
	CellTypeFormat
	CellTypeVersion
	CellTypeAlignmentPattern
	CellTypeSearchPattern
	CellTypeSyncPattern
	CellTypeDelimiter
)

Cell type represents the type of a cell in the QR code matrix.

type ErrorCorrectionLevel

type ErrorCorrectionLevel int

Level of error correction Low - 7% Medium - 15% Quartile - 25% High - 30%

const (
	ErrorCorrectionLevelLow ErrorCorrectionLevel = iota
	ErrorCorrectionLevelMedium
	ErrorCorrectionLevelQuartile
	ErrorCorrectionLevelHigh
)

type OutputFormat

type OutputFormat string

type PlotOptions

type PlotOptions struct {
	// Scale is the scale for the QR Code image (in pixels).
	// The image will be len(data) * Scale x len(data) * Scale pixels.
	Scale int

	// Border is the border for the QR Code image (in pixels).
	Border int

	// OutputFormat is the format of the output image.
	OutputFormat OutputFormat
}

type QRCode

type QRCode struct {
	// Content
	Content string

	// Data
	Data [][]Cell
	// contains filtered or unexported fields
}

QRCode is a struct that represents a QR Code.

func Create

func Create(content string, options *QRCodeOptions) (*QRCode, error)

Create creates a QR Code with the given content and options.

func CreateMultiMode

func CreateMultiMode(blocks []*encode.EncodeBlock, options *QRCodeOptionsMultiMode) (*QRCode, error)

CreateMultiMode creates a QR Code with multiple modes.

func (*QRCode) Plot

func (qr *QRCode) Plot(writer io.Writer, options *PlotOptions) error

Plot plots the QR Code to the given writer with the given options.

type QRCodeOptions

type QRCodeOptions struct {
	// Encoding is the encoding mode.
	// Default: calculated based on the content (can undestand only numeric, alphanumeric, byte, kanji or utf-8 with ECI)
	Mode encode.EncodingMode

	// Level is the error correction level.
	// Default: ErrorCorrectionLevelLow.
	ErrorLevel ErrorCorrectionLevel

	// Version is the version of the QR Code.
	// Default: calculated based on the content.
	Version int

	// Enable micro QR code
	// Default: false
	MicroQR bool
}

QRCodeOptions is a struct that represents the options for the QR Code.

type QRCodeOptionsMultiMode

type QRCodeOptionsMultiMode struct {
	// Level is the error correction level.
	// Default: ErrorCorrectionLevelLow.
	ErrorLevel ErrorCorrectionLevel

	// Version is the version of the QR Code.
	// Default: calculated based on the content.
	Version int

	// Enable micro QR code
	// Default: false
	MicroQR bool
}

QRCodeOptionsMultiMode is a struct that represents the options for building multi-mode QR Codes.