// SPDX-FileCopyrightText: 2022 Shun Sakai
//
// SPDX-License-Identifier: CC-BY-4.0

= qrtool-encode(1)
// Specify in UTC.
:docdate: 2025-10-29
:revnumber: 0.13.1
:doctype: manpage
:mansource: qrtool {revnumber}
:manmanual: General Commands Manual
ifndef::site-gen-antora[:includedir: ./include]
:qrcode-url: https://www.qrcode.com
:css-color-url: https://www.w3.org/TR/css-color-4/
:qrcode-codes: {qrcode-url}/codes
:normal-qr-code-url: {qrcode-codes}/model12.html
:micro-qr-code-url: {qrcode-codes}/microqr.html
:rmqr-code-url: {qrcode-codes}/rmqr.html

== NAME

qrtool-encode - encode input data in a QR code

== SYNOPSIS

*qrtool encode* [_OPTION_]... [_STRING_]

== DESCRIPTION

This command encodes input data in a {qrcode-url}[QR code] and outputs it as a
PNG image, a SVG image, a string, or other formats. By default, the result will
be output to standard output.

This command will read up to the first 7,090 bytes of the input data. The
amount of data that can be represented by a QR code depends on the mode,
version and error correction level. The storage capacity is maximized for
version 40 and error correction level L (40-L).

.Maximum character storage capacity (40-L)
|===
|Input mode |Max. characters |Possible characters

|Numeric
|7,089
|0-9

|Alphanumeric
|4,296
|0-9, A-Z (uppercase only), and few symbols (space, `$`, `%`, `*`, `+`, `-`,
`.`, `/`, `:`)

|Byte
|2,953
|Arbitrary binary data

|Kanji
|1,817
|Any double-byte JIS X 0208 character
|===

By default, this command encodes the input data in a QR code with a black
foreground and white background, but this can be changed by specifying
*--foreground* and/or *--background*. The {css-color-url}[CSS color string] can
be specified as a value for these options.

.List of methods to specify a color
|===
|Format |Examples

|Named colors
|`brown`, `lightslategray`

|Hexadecimal notations
|`#111`, `#eee8`, `#a52a2a`, `#7788997f`

|RGB functions
|`rgb(165 42 42)`, `rgb(119 136 153 / 49.8%)`

|HSL functions
|`hsl(248 39% 39.2%)`, `hsl(0 0% 66.3% / 49.8%)`

|HWB function
|`hwb(50.6 0% 0%)`, `hwb(0 66.3% 33.7% / 49.8%)`

|Oklab function
|`oklab(50.4% -0.0906 0.0069)`, `oklab(61.9% -0.0120 -0.0302 / 0.5)`

|Oklch function
|`oklch(59.41% 0.16 301.29)`, `oklch(61.9% 0.032 248.35 / 49.8%)`
|===

In addition to a {normal-qr-code-url}[normal QR code], this command can also
encode the input data in a {micro-qr-code-url}[Micro QR code] and a
{rmqr-code-url}[rMQR code].

== POSITIONAL ARGUMENTS

_STRING_::

  Input data. If _STRING_ is not specified, data will be read from standard
  input. _STRING_ must be a valid UTF-8 string. Use *--read-from* or read from
  standard input if taking other than a valid UTF-8 string. This positional
  argument conflicts with *--read-from*.

== OPTIONS

*-o*, *--output* _FILE_::

  Output the result to a file.

*-r*, *--read-from* _FILE_::

  Read input data from a file. This option conflicts with _STRING_.

*-s*, *--size* _NUMBER_::

  The module size in pixels. If this option is not specified, the module size
  is 8 when the output format is PNG, SVG, EPS, or PIC, and 1 otherwise.

*-l*, *--error-correction-level* _LEVEL_::

  Error correction level.

  The possible values are:{blank}:::

    *l*::::

      Level L. 7% of codewords can be restored.

    *m*::::

      Level M. 15% of codewords can be restored. This is the default value.

    *q*::::

      Level Q. 25% of codewords can be restored.

    *h*::::

      Level H. 30% of codewords can be restored.

*--level* _LEVEL_::

  Alias for *-l*, *--error-correction-level*.

*-v*, *--symbol-version* _NUMBER_ [_NUMBER_]::

  The version of the symbol. If this option is not specified, the minimum
  version required to store the data will be automatically chosen. For normal
  QR code, _NUMBER_ should be between *1* and *40*. For Micro QR code, _NUMBER_
  should be between *1* and *4*. For rMQR code, the first _NUMBER_ should be
  *7*, *9*, *11*, *13*, *15*, or *17*. The second _NUMBER_ should be *27*,
  *43*, *59*, *77*, *99*, or *139*. *27* can only be used with *11*, or *13*.
  If The type of QR code is other than rMQR code, the second _NUMBER_ is
  ignored.

*--symversion* _NUMBER_ [_NUMBER_]::

  Alias for *-v*, *--symbol-version*.

*-m*, *--margin* _NUMBER_::

  The width of margin. If this option is not specified, the margin will be 4
  for normal QR code and 2 for others.

*-t*, *--type* _FORMAT_::

  The format of the output.

  The possible values are:{blank}:::

    *png*::::

      Portable Network Graphics. This outputs 32-bit RGBA PNG image. This is
      the default value.

    *svg*::::

      Scalable Vector Graphics.

    *eps*::::

      Encapsulated PostScript.

    *pic*::::

      PIC markup language.

    *ansi*::::

      To the terminal using 4-bit ANSI escape sequences. This value is
      available if the `output-as-ansi` feature is enabled at compile time.

    *ansi256*::::

      To the terminal using 8-bit ANSI escape sequences. This value is
      available if the `output-as-ansi` feature is enabled at compile time.

    *ansi-true-color*::::

      To the terminal using 24-bit ANSI escape sequences. This value is
      available if the `output-as-ansi` feature is enabled at compile time.

    *ascii*::::

      To the terminal as ASCII string.

    *ascii-invert*::::

      To the terminal as ASCII string. This value inverts foreground and
      background colors of *ascii* and outputs the inverted string. *ASCIIi* is
      an alias for this value.

    *unicode*::::

      To the terminal as UTF-8 string. *terminal* and *UTF8* are aliases for
      this value.

    *unicode-invert*::::

      To the terminal as UTF-8 string. This value inverts foreground and
      background colors of *unicode* and outputs the inverted string. *UTF8i*
      is an alias for this value.

*--optimize-png* [_LEVEL_]::

  Set the optimization level for a PNG image. Lower levels are faster, higher
  levels provide better compression. If _LEVEL_ is not specified, it is assumed
  that the default level 2 is specified. This option is available if the
  `optimize-output-png` feature is enabled at compile time.

  The possible values are:{blank}:::

    *0*::::

      Level 0. This value is the minimum optimization level.

    *1*::::

      Level 1.

    *2*::::

      Level 2. This is the default value.

    *3*::::

      Level 3.

    *4*::::

      Level 4.

    *5*::::

      Level 5.

    *6*::::

      Level 6. This value is the maximum optimization level.

    *max*::::

      This value is an alias for the maximum optimization level.

*--zopfli* [_ITERATION_]::

  Use Zopfli to compress PNG image. Perform compression for the number of
  iterations specified by _ITERATION_. If _ITERATION_ is not specified, it is
  assumed that 15 is specified as the number of iterations. This option
  requires *--optimize-png*. This option is available if the
  `optimize-output-png` feature is enabled at compile time.

*--mode* _MODE_::

  The mode of the output. If this option is not specified, use the optimal
  encoding. This option requires *--symbol-version*.

  The possible values are:{blank}:::

    *numeric*::::

      All digits.

    *alphanumeric*::::

      Alphanumerics and few symbols.

    *byte*::::

      Arbitrary binary data.

    *kanji*::::

      Shift JIS text.

*--variant* _TYPE_::

  The type of QR code.

  The possible values are:{blank}:::

    *normal*::::

      Normal QR code. This is the default value.

    *micro*::::

      Micro QR code.

    *rmqr*::::

      rMQR code.

*--foreground* _COLOR_::

  Foreground color. _COLOR_ takes a CSS color string. Colored output is only
  available when the output format is PNG, SVG or any ANSI escape sequences.
  Note that lossy conversion may be performed depending on the color space
  supported by the method to specify a color, the color depth supported by the
  output format, etc. Default is black.

*--background* _COLOR_::

  Background color. _COLOR_ takes a CSS color string. Colored output is only
  available when the output format is PNG, SVG or any ANSI escape sequences.
  Note that lossy conversion may be performed depending on the color space
  supported by the method to specify a color, the color depth supported by the
  output format, etc. Default is white.

*--verbose*::

  Also print the metadata. It is output to stderr.

*-h*, *--help*::

  Print help message. The short flag (*-h*) will print a condensed help message
  while the long flag (*--help*) will print a detailed help message.

*-V*, *--version*::

  Print version number.

ifndef::site-gen-antora[include::{includedir}/section-exit-status.adoc[]]
ifdef::site-gen-antora[include::partial$man/man1/include/section-exit-status.adoc[]]

== NOTES

Source repository:{blank}::

  https://github.com/sorairolake/qrtool

== EXAMPLES

Encode the given string in a QR code:{blank}::

  $ *qrtool encode "QR code" > output.png*

Encode the given file and output to the specified image:{blank}::

  $ *qrtool encode -o output.png -r go.mod*

Encode to a SVG image:{blank}::

  $ *qrtool encode -t svg "QR code" > output.svg*

Encode to a Micro QR code:{blank}::

  $ *qrtool encode --variant micro "QR code" > output.png*

Encode with the specified colors:{blank}::

  $ *qrtool encode -o output.png --foreground brown --background lightslategray "QR code"*

ifndef::site-gen-antora[include::{includedir}/section-reporting-bugs.adoc[]]
ifdef::site-gen-antora[include::partial$man/man1/include/section-reporting-bugs.adoc[]]

ifndef::site-gen-antora[include::{includedir}/section-copyright.adoc[]]
ifdef::site-gen-antora[include::partial$man/man1/include/section-copyright.adoc[]]

== SEE ALSO

*oxipng*(1), *qrencode*(1), *qrtool*(1), *qrtool-completion*(1),
*qrtool-decode*(1)