> For the complete documentation index, see [llms.txt](https://infinitode-docs.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://infinitode-docs.gitbook.io/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-presets-and-outputs.md). # qrforge Presets & Outputs qrforge reference for the 22 built-in presets, every output format, the CLI, and the Color, Gradient and Pixmap helper classes. ## Presets A preset is a named set of [style options](/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-style-options.md) that can be passed anywhere a style is accepted: `qrforge.save("hi", "out.png", "neon")`, `qr.use_style("neon")`, `qr.styled("neon")`, `qr.render("neon")` or `qrforge.presets.get("neon")`. ```python import qrforge qrforge.presets.names() # ['badge', 'blueprint', 'brutal', 'circuit', 'classic', 'confetti', 'cross', # 'dots', 'film', 'glitch', 'gold', 'halftone', 'ice', 'leaf', 'minimal', # 'neon', 'retro', 'rounded', 'soft', 'starry', 'sunset', 'vapor'] ``` | Preset | Look | Highlights | | ----------- | -------------------------- | ---------------------------------------------------------------------------------------------------- | | `classic` | Plain black-on-white QR. | Square modules, full scale. | | `dots` | Rounded, friendly. | Dot modules, rounded eyes. | | `rounded` | Soft modern. | Rounded modules (`module_radius=0.3`) and eyes. | | `soft` | Softer still. | Squircle modules and squircle eyes. | | `confetti` | Playful and colourful. | Random mixture of dot/diamond/star/hexagon/leaf modules with jitter, four-colour gradient, `seed=3`. | | `neon` | Dark, luminous. | Cyan → purple → pink gradient on near-black, rounded modules, `glow` + `grain`. | | `sunset` | Warm gradient. | Orange → red → purple linear gradient on cream. | | `blueprint` | Technical drawing. | Pale blue on navy, `scanlines` for a plan-paper texture. | | `brutal` | High-contrast, hard edges. | Black on off-white with a module stroke. | | `vapor` | Retro-futurist. | Conic magenta/cyan/green gradient on deep purple, `chromatic` aberration. | | `film` | Analog print. | Warm duotone + grain + vignette on paper. | | `halftone` | Newspaper print. | Classic geometry plus the `halftone` shader. | | `gold` | Luxurious. | Gold gradient on near-black with grain and vignette. | | `ice` | Cold and clean. | White → blue radial gradient on navy with `glow`. | | `leaf` | Botanical. | Green gradient, leaf-shaped modules rotated 45°, leaf eye dots. | | `circuit` | Circuit board. | Mint on near-black, smaller square modules, horizontal bars for function modules, glow. | | `retro` | Vintage terminal/print. | Sepia + scanlines + grain on aged paper. | | `glitch` | Digital glitch art. | White on near-black with `glitch` + `chromatic`. | | `minimal` | Delicate. | Small circles (`module_scale=0.62`) with thin, larger-ringed eyes. | | `badge` | Label / sticker. | Rounded dark modules on a white card with padding, rounded corners and a drop shadow. | | `starry` | Night sky. | White star modules over a radial navy → black background with subtle grain. | | `cross` | Bold and graphic. | Red crosses with cross-shaped eyes on cream. | {% hint style="info" %} Want to see them? The [qrforge Gallery](/documentation/package-documentation/qrforge-package-documentation/qrforge-gallery.md#preset-gallery) renders all 22 presets as real, verified PNGs — each one encodes the same payload, so they are directly comparable. {% endhint %} Every field of a preset can be overridden: ```python import qrforge # override at render time qrforge.save("hi", "out.png", "neon", fg="#00ff88", scale=12) # or build the Style and edit it style = qrforge.presets.get("sunset", bg="#000000") style = style.merged(module_scale=0.8) # register your own preset, usable by name like the built-ins qrforge.presets.register("midnight", module_shape="star", fg="#8ef6ff", bg="#05070f", shaders=("glow:radius=2,amount=0.7",)) qrforge.save("hello", "midnight.png", "midnight", scale=12) ``` | Member | Description | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `presets.get(name, **overrides)` | Return the `Style` for a preset name, with optional overrides. Names are normalised (`"Ice"`, `"ice"` and `"icy blue"`-style spaces/hyphens are handled). | | `presets.names()` | Sorted list of preset names. | | `presets.register(name, **options)` | Add or replace a preset with the given style options. | | `qrforge.preset(name)` | Shortcut for `presets.get(name)`. | *** ## Output formats | Format | How to get it | Type | Dependencies | | ----------------------- | ---------------------------------------------------------- | ------------------------ | ------------------------ | | PNG | `qr.save("out.png")`, `qr.png()`, `qr.render().to_bytes()` | Raster | none (pure-Python codec) | | SVG | `qr.save("out.svg")`, `qr.svg()` | Vector | none | | PDF | `qr.save("out.pdf")`, `qr.pdf()` | Vector | none | | HTML | `qr.save("out.html")` | Vector (standalone page) | none | | Text | `qr.save("out.txt")` | Text blocks | none | | ANSI | `qr.save("out.ansi")`, `qr.terminal()` | Terminal text | none | | Pillow image | `qr.to_pil()` | Raster object | Pillow | | WebP / BMP / GIF / TIFF | `qr.save("out.webp")` etc. | Raster | Pillow | ```python import qrforge qr = qrforge.QR("https://example.com", ec="h").use_style("neon", scale=12) qr.save("out.png") # PNG qr.save("out.svg") # SVG qr.save("out.pdf") # PDF qr.save("out.html") # HTML page with the SVG inlined qr.save("out.txt") # plain text qr.save("out.ansi") # ANSI colour text qr.save("out.webp") # WebP, BMP, GIF, TIFF … (Pillow required) # the rendered buffer is RGBA, so JPEG output goes through RGB first qr.to_pil(scale=12).convert("RGB").save("out.jpg") png_bytes, svg_text, pdf_bytes = qr.png(), qr.svg(), qr.pdf() print(qr.terminal()) print(qr.ascii("##", " ")) ``` {% hint style="info" %} `qr.save("out.jpg")` raises `OSError: cannot write mode RGBA as JPEG` in 1.0.1 (and `ValueError: only PNG can be written without Pillow` when Pillow is not installed at all). Convert the Pillow image to RGB (as above) or save WebP/BMP/GIF/TIFF instead. {% endhint %} {% hint style="info" %} `render()` returns an [`Artwork`](/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-api-functions.md#artwork) — the richest output object, with `save()`, `to_bytes()`, `to_pil()`, `to_data_uri()` and Jupyter display hooks. {% endhint %} ### What each renderer honours | Style feature | Raster (PNG, Pillow) | SVG | PDF | Terminal | | ---------------------------------------------------------- | -------------------- | ------------------------------- | ----------------------------------------- | --------------- | | Module shape, scale, gap | yes | yes | yes (sampled from the shape outline) | no (block grid) | | Module rotation, radius, jitter | yes | yes | no | no | | Function-module shape / colour | yes | yes | no | no | | Eye shape, ring, dot, scale, colour | yes | yes | no (always black/white squares) | no | | Colours and gradients | yes | yes | sampled per module | yes | | Texture | yes | yes (`contain` pads with white) | no | no | | Logo (including `logo_position`) | yes | yes (always centred) | no | no | | `bg_image`, `bg_opacity`, `bg_radius`, `padding`, `shadow` | yes | yes | background colour only; `padding` ignored | no | | `quiet_zone` | yes | yes | yes | yes | | `supersample` | yes | n/a (vector) | no | no | | Shaders | most | most (see below) | no | no | {% hint style="info" %} The PDF renderer is deliberately simple: it emits the background colour, the module shapes, the quiet zone and module-sampled gradients. Logos, textures, shadows, shaders, padding and eye styling are not applied, and the finder patterns are always drawn as black-and-white squares. Page size is `(modules + 2 × quiet_zone) × 8` points. {% endhint %} ### Shader coverage per output | Shaders | Raster | SVG | | -------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------- | | `grain`, `noise`, `vignette`, `duotone`, `posterize`, `sepia`, `greyscale`, `invert`, `wave`, `chromatic`, `glow`, `bloom` | yes | yes (filters/overlays) | | `twist`, `swirl`, `bulge`, `glitch`, `halftone` | yes | skipped | | `scanlines`, `outline`, `stroke` | not applied in 1.0.1 | yes | *** ## Command line ``` python -m qrforge [data] [-o OUTPUT] [-p PRESET] [-e {L,M,Q,H}] [-v VERSION] [-m MASK] [-s SCALE] [--shape SHAPE] [--fg FG] [--bg BG] [--logo LOGO] [--shader SHADER] [--seed SEED] [--terminal] [--info] [--list-presets] [--list-shapes] [--list-shaders] [--version-info] ``` The installed console script `qrforge` accepts exactly the same arguments. | Option | Description | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `data` | The text to encode (positional). | | `-o`, `--output` | Output file: `.png`, `.svg`, `.pdf`, `.txt` or `.html`. Without it, qrforge prints the symbol to the terminal. | | `-p`, `--preset` | A named preset; see `--list-presets`. | | `-e`, `--ec` | Error correction level: `L`, `M`, `Q` or `H` (uppercase). Default `M`. | | `-v`, `--version` | Force a QR version (1–40). | | `-m`, `--mask` | Force a mask pattern (0–7). | | `-s`, `--scale` | Pixels per module. Default `10`. | | `--shape` | Module shape, or a comma-separated list for a random mix. | | `--fg` | Foreground colour, or a comma-separated gradient (`--fg "#00ff88,#0077ff"`). | | `--bg` | Background colour, or `none` / `transparent`. | | `--logo` | Path to a logo image. | | `--shader` | A shader; repeat the option to stack several. | | `--seed` | Seed for randomised effects. | | `--terminal` | Print the symbol to the terminal. | | `--info` | Print encoding details (version, level, mask, size, segments, …). | | `--list-presets`, `--list-shapes`, `--list-shaders` | Print the available names. | | `--version-info` | Print the qrforge version. | ```bash # save a styled PNG and a vector SVG qrforge "https://example.com" -o out.png -p neon -s 12 -e H python -m qrforge "https://example.com" -o out.svg --shape dot --fg "#00ff88,#0077ff" # print in the terminal, or inspect the encoding qrforge "hi" --terminal qrforge "hi" --info # discover what is available qrforge --list-presets --list-shapes --list-shaders ``` {% hint style="warning" %} Error correction levels must be uppercase (`-e H`, not `-e h`), and running the CLI without `data` prints the help text and exits with status 1. {% endhint %} *** ## Color `qrforge.Color` is an RGBA colour with 8 bits per channel. Anything that accepts a colour accepts a `Color`, a hex string (`#rgb`, `#rrggbb`, `#rrggbbaa`), `rgb()/rgba()` / `hsl()/hsla()` strings, a CSS colour name, an integer, a 3/4-tuple, or `None` (transparent). ```python import qrforge from qrforge import Color color = Color.parse("hsl(210, 100%, 50%)") color.rgba # (…, …, …, 255) color.hex() # '#…' color.css # '#…' or 'rgba(r, g, b, a)' color.hsl() # (h, s, l) color.mix("#ffffff", 0.5) color.lighten(0.2), color.darken(0.2), color.rotate(30) color.with_alpha(0.5) color.luminance, color.contrast("#ffffff"), color.is_dark() qr = qrforge.QR("colour helpers").use_style(fg=Color.parse("tomato"), bg=Color(10, 10, 20, 255)) ``` | Member | Description | | ------------------------------------------------------------------------ | ---------------------------------------------- | | `Color(r=0, g=0, b=0, a=255)` | Build a colour from channel values. | | `Color.parse(value)` | Coerce any supported colour value. | | `color.rgba`, `color.rgb`, `color.alpha`, `color.is_opaque` | Channel properties. | | `color.hex(with_alpha=False)`, `color.css`, `color.hsl()` | String/tuple conversions. | | `color.with_alpha(alpha)`, `color.mix(other, t)` | Derived colours. | | `color.lighten(amount)`, `color.darken(amount)`, `color.rotate(degrees)` | HSL adjustments. | | `color.luminance`, `color.contrast(other)`, `color.is_dark()` | Contrast helpers (WCAG ratio from `contrast`). | Module-level helpers: `qrforge.color.parse(value)` and `qrforge.color.blend(base, top, opacity=1.0)`. *** ## Gradient `Gradient` (and `SolidFill`) are the colour sources behind `fg`, `bg`, `eye_fg`, `function_fg`, `logo_bg` and `stroke`. ```python import qrforge from qrforge import Gradient, SolidFill # constructors Gradient.linear("#ff9a3c", "#ff4d6d", "#7b2ff7", angle=135) Gradient.radial("#ffffff", "#1f6feb", center=(0.5, 0.35), radius=0.8) Gradient.conic("#ff71ce", "#01cdfe", "#05ffa1", start_angle=90) # or the mapping form accepted anywhere a style is Gradient.parse({"kind": "linear", "angle": 45, "colors": [(0.0, "#000000"), (0.6, "#00ff88"), (1.0, "#ffffff")]}) SolidFill("#00ff88") qrforge.SolidFill("#00ff88").at(0, 0) ``` | Member | Description | | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Gradient(stops, kind="linear", angle=135, center=(0.5, 0.5), radius=0.75, inner=0.0, start_angle=0.0, spread="pad", focal=None)` | Full constructor. `kind` is `"linear"`, `"radial"` or `"conic"`; `spread` is `"pad"`, `"reflect"` or `"repeat"`; stops may be colours or `(position, colour)` pairs. | | `Gradient.linear(*colors, angle=135, **kwargs)` | Linear gradient constructor. | | `Gradient.radial(*colors, center=(0.5, 0.5), radius=0.75, inner=0.0, **kwargs)` | Radial gradient constructor. | | `Gradient.conic(*colors, center=(0.5, 0.5), start_angle=0.0, **kwargs)` | Conic gradient constructor. | | `Gradient.parse(spec, default_angle=135)` | From a mapping or a list of colours. | | `gradient.at(u, v)` | Sample the colour at normalised coordinates. | | `gradient.svg_paint(uid, x, y, w, h, defs)` | SVG paint (conic gradients are emulated with a wedge pattern). | | `gradient.spread`, `gradient.focal`, `gradient.inner` | Gradient geometry. | In style dicts, a gradient accepts the keys `colors` (or `stops`), `kind`, `angle`, `center`, `radius`, `inner`, `start_angle`, `spread` and `focal`. `qrforge.gradient.resolve(spec, default_angle=135)` is the function the renderers use to turn a colour spec into a `ColorSource`. *** ## Pixmap `qrforge.Pixmap` is qrforge's own RGBA image buffer. It also contains the dependency-free PNG codec, so it is what `to_png()` and `Pixmap.open("…png")` use. ```python from qrforge import Pixmap image = Pixmap(64, 64, (255, 90, 0, 255)) # width, height, colour image.save("logo.png") # PNG, no dependencies required image.to_png(compress=6) # PNG bytes loaded = Pixmap.open("logo.png") # path, bytes, file-like or PIL image scaled = loaded.resized(128, 128, "cover") # stretch | cover | contain rotated = loaded.rotated(15) copy = loaded.copy() copy.fill("#101014") ``` | Member | Description | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `Pixmap(width, height, color=None, data=None)` | Create a buffer (optionally from an existing `bytearray`). | | `Pixmap.new(width, height, color=None)` | Create a buffer with a fill colour. | | `Pixmap.open(source)` | Load from a path, bytes, file-like object, `Pixmap` or PIL image (non-PNG needs Pillow). | | `Pixmap.from_pil(image)` | Convert a Pillow image. | | `image.get(x, y)`, `image.set(x, y, rgba)` | Read/write a pixel. | | `image.fill(color)` | Fill the whole buffer. | | `image.copy()` | Duplicate the buffer. | | `image.in_bounds(x, y)` | Bounds check. | | `image.sample(x, y)` | Bilinear sample at float coordinates. | | `image.blit(other, x, y, opacity=1.0, mask=None)` | Composite another pixmap over this one. | | `image.paste_cover(other, opacity=1.0)` | Scale to cover and composite. | | `image.resized(width, height, mode="stretch")` | Bilinear resize (`stretch`, `cover`, `contain`). | | `image.rotated(degrees)` | Rotate about the centre (transparent corners). | | `image.map_pixels(fn)` | Apply `fn(x, y, rgba) -> rgba` to every pixel. | | `image.to_png(compress=6)`, `image.save(path, compress=6)` | PNG encoding (`.png` native, other extensions need Pillow). | | `image.to_pil()` | Convert to a Pillow image. | | `image.width`, `image.height`, `image.data` | The raw RGBA `bytearray`. | Module-level helpers: `qrforge.image.encode_png(width, height, data, compress=6)` and `qrforge.image.decode_png(raw)`. *** ## Module map | Module | Contents | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `qrforge` | Convenience exports (`QR`, `Style`, `Color`, `Gradient`, `Pixmap`, `preset`, `shape`, `shader`, `expression`, …) and the version. | | `qrforge.api` | `QR`, `QRCode`, `Artwork`, `make`, `save`, `svg`, `png`, `terminal`. | | `qrforge.style` | `Style`, `parse`, `options`. | | `qrforge.presets` | `get`, `names`, `register`. | | `qrforge.shapes` | `Shape`, `SHAPES`, `ALIASES`, SDF helpers, `get`, `names`, `register`, `custom`. | | `qrforge.shaders` | `Shader`, `FunctionShader`, `Context`, `build`, `names`, `expression`, `shader`, filters. | | `qrforge.color` | `Color`, `parse`, `blend`. | | `qrforge.gradient` | `Gradient`, `SolidFill`, `ColorSource`, `Stop`, `resolve`. | | `qrforge.image` | `Pixmap`, `encode_png`, `decode_png`. | | `qrforge.matrix` | `QRMatrix`, `build`, masks, penalty scoring, roles. | | `qrforge.encoder` | Segmentation, version selection, codeword generation. | | `qrforge.gf` | Galois-field arithmetic, Reed–Solomon encode/correct. | | `qrforge.tables` | Spec tables (sizes, alignment, block layouts, count bits). | | `qrforge.verify` | `decode`, `DecodeResult`, format/codeword readers. | | `qrforge.render` | `raster`, `svg`, `pdf`, `ansi` renderers. | | `qrforge.cli` | `build_parser`, `main` (used by `python -m qrforge`). | | `qrforge.exceptions` | `QRForgeError`, `DataTooLong`, `StyleError`, `UnsupportedFeature`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://infinitode-docs.gitbook.io/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-presets-and-outputs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.