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

= Usage
:w3-url: https://www.w3.org
:enwp-url: https://en.wikipedia.org
:enwp-article-url: {enwp-url}/wiki
:github-url: https://github.com
:css-color-4-url: {w3-url}/TR/css-color-4/
:bmp-url: {enwp-article-url}/BMP_file_format
:dds-url: {enwp-article-url}/DirectDraw_Surface
:farbfeld-url: https://tools.suckless.org/farbfeld/
:gif-url: {enwp-article-url}/GIF
:radiance-rgbe-url: {enwp-article-url}/RGBE_image_format
:ico-url: {enwp-article-url}/ICO_(file_format)
:jpeg-url: https://jpeg.org/jpeg/
:openexr-url: https://openexr.com/
:png-url: {enwp-article-url}/PNG
:pnm-url: https://netpbm.sourceforge.net/doc/pnm.html
:qoi-url: https://qoiformat.org/
:svg-url: {w3-url}/Graphics/SVG/
:tga-url: {enwp-article-url}/Truevision_TGA
:tiff-url: {enwp-article-url}/TIFF
:webp-url: https://developers.google.com/speed/webp/
:oxipng-repo-url: {github-url}/shssoichiro/oxipng
:svgcleaner-repo-url: {github-url}/RazrFalcon/svgcleaner
:imagemagick-url: https://imagemagick.org/

== Basic usage

.Encode a string in a QR code
[source,sh]
----
qrtool encode "QR code" > output.png
----

.Generate this image
image::basic.png[Output]

.Decode a QR code from this image
[source,sh]
----
qrtool decode output.png
----

.Output
....
QR code
....

== SVG generation

Use `-t` option to change the format of the generated image. The format is
`png` (default), `svg` or `terminal` (to the terminal as UTF-8 string).

[source,sh]
----
qrtool encode -o output.svg -t svg "QR code"
----

.Generate this image
image::decode.svg[Output]

== Micro QR code generation

Use `--variant` option to change the variant of the generated QR code. The
variant is `normal` (default) or `micro` (Micro QR code).

[source,sh]
----
qrtool encode -v 3 --variant micro "QR code" > output.png
----

.Generate this image
image::micro.png[Output]

== Colored output

Use `--foreground` and `--background` options to change the foreground and
background colors of the generated image. These options takes a
{css-color-4-url}[CSS color string] such as `brown`, `#a52a2a` or
`rgb(165 42 42)`. The default foreground color is black and the background
color is white of CSS's named colors.

[source,sh]
----
qrtool encode --foreground brown --background lightslategray "QR code" > output.png
----

.Generate this image
image::rgb.png[Output]

== Supported input image formats

.`qrtool decode` supports decoding a QR code from the following image formats
* {bmp-url}[BMP]
* {dds-url}[DDS]
* {farbfeld-url}[Farbfeld]
* {gif-url}[GIF]
* {radiance-rgbe-url}[Radiance RGBE]
* {ico-url}[ICO]footnote:[CUR is also supported.]
* {jpeg-url}[JPEG]
* {openexr-url}[OpenEXR]
* {png-url}[PNG]
* {pnm-url}[PNM]
* {qoi-url}[QOI]
* {svg-url}[SVG]footnote:[SVGZ is also supported.]
* {tga-url}[TGA]
* {tiff-url}[TIFF]
* {webp-url}[WebP]

To support decoding from SVG image, the `decode-from-svg` feature must be
enabled at compile time. Note that the SVG image is rasterized before scanning.

Image formats other than PNG can be disabled by disabling the `default`
feature, and can be enabled individually.

Use `-t` option to specify the image format. If this option is not specified,
the image format is determined based on the extension or the magic number.

.Input this WebP image
image::lossless.webp[Input]

.Decode a QR code from the WebP image
[source,sh]
----
qrtool decode input.webp
# or
qrtool decode -t webp input.webp
----

.Output
....
QR code
....

== Generate shell completion

`--generate-completion` option generates shell completions to stdout.

.The following shells are supported
* `bash`
* `elvish`
* `fish`
* `nushell`
* `powershell`
* `zsh`

.Example
[source,sh]
----
qrtool --generate-completion bash > qrtool.bash
----

== Integration with other programs

Both `qrtool encode` and `qrtool decode` can read from stdin and output to
stdout.

=== Optimize the output image

The image output by `qrtool encode` is not optimized. For example, a PNG image
is always output as the 32-bit RGBA format. If you want to reduce the image
size or optimize the image, use an optimizer such as
{oxipng-repo-url}[`oxipng`] or {svgcleaner-repo-url}[`svgcleaner`].

.Optimize the output PNG image
[source,sh]
----
qrtool encode "QR code" | oxipng - > output.png
----

.Optimize the output SVG image
[source,sh]
----
qrtool encode -t svg "QR code" | svgcleaner -c - > output.svg
----

TIP: If the `optimize-output-png` feature is enabled, you can also use
`--optimize-png` option and `--zopfli` option of this command to optimize
output PNG image.

=== Reading and writing unsupported image formats

If you want to save the encoded image in an image format other than PNG or SVG,
or decode an image in an unsupported image format, convert it using a converter
such as {imagemagick-url}[ImageMagick].

.Read `Cargo.toml` from stdin and save the encoded result as a JPEG XL image
[source,sh]
----
cat Cargo.toml | qrtool encode | magick png:- output.jxl
----

.Decode this image and print the result using `bat`
[source,sh]
----
magick output.jxl png:- | qrtool decode | bat -l toml
----
