CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/pypi-qrcode

QR Code image generator with customizable image formats, error correction levels, and styling options

42%

Overall

Evaluation — 42%

↓ 0.86x

Agent success when using this tile

Overview
Eval results
Files

styling.mddocs/

Styling and Customization

Advanced styling capabilities for QR codes including custom module shapes, color masks, embedded images, gradients, and various drawing patterns through the StyledPilImage factory and associated styling components.

Capabilities

Styled PIL Image Factory

The StyledPilImage factory provides comprehensive styling capabilities with support for custom module drawers, color masks, and embedded images.

from qrcode.image.styledpil import StyledPilImage

class StyledPilImage:
    """
    Advanced styled PIL image factory with extensive customization options.
    
    Features:
    - Custom module drawer shapes
    - Color masks and gradients  
    - Embedded images/logos
    - Antialiasing support
    - High-quality rendering
    """
    
    kind = "PNG"
    needs_processing = True
    
    def __init__(self, *args, module_drawer=None, eye_drawer=None, 
                 color_mask=None, embeded_image=None, embeded_image_path=None,
                 embeded_image_resample=None, **kwargs):
        """
        Initialize styled PIL image factory.
        
        Parameters:
        - module_drawer: Custom drawer for QR code modules
        - eye_drawer: Custom drawer for position detection patterns (eyes)
        - color_mask: Color mask for advanced coloring effects
        - embeded_image: PIL Image object to embed in center
        - embeded_image_path (str): Path to image file to embed
        - embeded_image_resample: PIL resampling filter for embedded image
        """

Basic Usage Example:

import qrcode
from qrcode.image.styledpil import StyledPilImage
from qrcode.image.styles.moduledrawers import CircleModuleDrawer
from qrcode.image.styles.colormasks import SolidFillColorMask

# High error correction recommended for styled QR codes
qr = qrcode.QRCode(
    error_correction=qrcode.constants.ERROR_CORRECT_H,
    image_factory=StyledPilImage
)
qr.add_data('Styled QR Code')
qr.make()

img = qr.make_image(
    module_drawer=CircleModuleDrawer(),
    color_mask=SolidFillColorMask()
)
img.save('styled_qr.png')

Module Drawers

Custom shapes for individual QR code modules (the small squares that make up the QR code).

from qrcode.image.styles.moduledrawers import (
    SquareModuleDrawer, CircleModuleDrawer, GappedSquareModuleDrawer,
    RoundedModuleDrawer, VerticalBarsDrawer, HorizontalBarsDrawer
)

class SquareModuleDrawer:
    """Standard square modules (default)."""

class GappedSquareModuleDrawer:
    """Square modules with gaps between them."""
    def __init__(self, size_ratio=0.8):
        """
        Parameters:
        - size_ratio (float): Size of squares relative to module space (0.0-1.0)
        """

class CircleModuleDrawer:
    """Circular modules."""
    def __init__(self, size_ratio=0.8):
        """
        Parameters:
        - size_ratio (float): Size of circles relative to module space (0.0-1.0)
        """

class RoundedModuleDrawer:
    """Square modules with rounded corners."""
    def __init__(self, radius_ratio=0.5):
        """
        Parameters:
        - radius_ratio (float): Corner radius relative to module size (0.0-1.0)
        """

class VerticalBarsDrawer:
    """Vertical bar modules."""

class HorizontalBarsDrawer:
    """Horizontal bar modules."""

Module Drawer Examples:

import qrcode
from qrcode.image.styledpil import StyledPilImage
from qrcode.image.styles.moduledrawers import (
    CircleModuleDrawer, GappedSquareModuleDrawer, RoundedModuleDrawer
)

qr = qrcode.QRCode(image_factory=StyledPilImage)
qr.add_data('Module Shapes')
qr.make()

# Circular modules
img1 = qr.make_image(module_drawer=CircleModuleDrawer())
img1.save('circles.png')

# Gapped squares
img2 = qr.make_image(module_drawer=GappedSquareModuleDrawer(size_ratio=0.6))
img2.save('gapped.png')

# Rounded corners
img3 = qr.make_image(module_drawer=RoundedModuleDrawer(radius_ratio=0.3))
img3.save('rounded.png')

Color Masks

Advanced coloring systems for applying colors, gradients, and effects to QR codes.

from qrcode.image.styles.colormasks import (
    QRColorMask, SolidFillColorMask, RadialGradiantColorMask, 
    SquareGradiantColorMask, ImageColorMask
)

class QRColorMask:
    """
    Base class for color masking effects.
    
    Attributes:
    - back_color: Background color (RGB tuple)
    - has_transparency: Whether mask supports transparency
    """
    
    back_color = (255, 255, 255)  # White background
    has_transparency = False
    
    def get_fg_pixel(self, image, x, y):
        """
        Get foreground color for pixel at (x, y).
        
        Parameters:
        - image: PIL Image being processed
        - x, y (int): Pixel coordinates
        
        Returns:
        tuple: RGB or RGBA color tuple
        """

class SolidFillColorMask:
    """Solid color fill mask."""
    def __init__(self, back_color=(255, 255, 255), front_color=(0, 0, 0)):
        """
        Parameters:
        - back_color (tuple): Background RGB color
        - front_color (tuple): Foreground RGB color
        """

class RadialGradiantColorMask:
    """Radial gradient from center to edge."""
    def __init__(self, back_color=(255, 255, 255), 
                 center_color=(0, 0, 0), edge_color=(0, 0, 255)):
        """
        Parameters:
        - back_color (tuple): Background color
        - center_color (tuple): Color at center
        - edge_color (tuple): Color at edges
        """

class SquareGradiantColorMask:
    """Square gradient from center outward."""

class ImageColorMask:
    """Use another image as color source."""
    def __init__(self, color_mask_image):
        """
        Parameters:
        - color_mask_image: PIL Image to use as color source
        """

Color Mask Examples:

import qrcode
from qrcode.image.styledpil import StyledPilImage
from qrcode.image.styles.colormasks import (
    SolidFillColorMask, RadialGradiantColorMask
)
from PIL import Image

qr = qrcode.QRCode(image_factory=StyledPilImage)
qr.add_data('Colorful QR')
qr.make()

# Solid colors
solid_mask = SolidFillColorMask(
    back_color=(255, 255, 255),  # White background
    front_color=(0, 100, 200)    # Blue foreground
)
img1 = qr.make_image(color_mask=solid_mask)
img1.save('solid_color.png')

# Radial gradient
gradient_mask = RadialGradiantColorMask(
    back_color=(255, 255, 255),  # White background
    center_color=(255, 0, 0),    # Red center
    edge_color=(0, 0, 255)       # Blue edges
)
img2 = qr.make_image(color_mask=gradient_mask)
img2.save('gradient.png')

Embedded Images

Support for embedding logos or images in the center of QR codes with automatic sizing and positioning.

# Embedded image parameters in StyledPilImage
def __init__(self, *args, embeded_image=None, embeded_image_path=None,
             embeded_image_resample=None, **kwargs):
    """
    Parameters:
    - embeded_image: PIL Image object to embed
    - embeded_image_path (str): Path to image file to embed  
    - embeded_image_resample: PIL resampling filter (default: LANCZOS)
    
    Notes:
    - Image is automatically sized to ~1/4 of QR code width
    - Position is automatically centered
    - High error correction recommended (ERROR_CORRECT_H)
    - Supports alpha transparency
    """

Usage Example:

import qrcode
from qrcode.image.styledpil import StyledPilImage
from PIL import Image

# High error correction for logo coverage
qr = qrcode.QRCode(
    error_correction=qrcode.constants.ERROR_CORRECT_H,
    image_factory=StyledPilImage
)
qr.add_data('https://example.com')
qr.make()

# Embed from file path
img1 = qr.make_image(embeded_image_path='logo.png')
img1.save('qr_with_logo.png')

# Embed PIL Image object
logo = Image.open('logo.png')
img2 = qr.make_image(embeded_image=logo)
img2.save('qr_with_pil_logo.png')

# Custom resampling filter
img3 = qr.make_image(
    embeded_image_path='logo.png',
    embeded_image_resample=Image.Resampling.NEAREST
)
img3.save('qr_pixelated_logo.png')

Eye Customization

Separate styling for the position detection patterns (corner squares/"eyes") of QR codes.

# Eye drawer parameter in StyledPilImage
def __init__(self, *args, eye_drawer=None, **kwargs):
    """
    Parameters:
    - eye_drawer: Custom drawer for position detection patterns
    
    Notes:
    - If not specified, uses same drawer as modules
    - Eyes should remain recognizable for QR code scanning
    - Be careful with heavy customization of eyes
    """

Usage Example:

import qrcode
from qrcode.image.styledpil import StyledPilImage
from qrcode.image.styles.moduledrawers import CircleModuleDrawer, SquareModuleDrawer

qr = qrcode.QRCode(image_factory=StyledPilImage)
qr.add_data('Custom Eyes')
qr.make()

# Circular modules with square eyes
img = qr.make_image(
    module_drawer=CircleModuleDrawer(),
    eye_drawer=SquareModuleDrawer()
)
img.save('mixed_styles.png')

SVG Drawer Aliases

SVG image factories also support custom drawers through aliases.

from qrcode.image.svg import SvgImage

# Built-in SVG drawer aliases
drawer_aliases = {
    "circle": ("SvgCircleDrawer", {}),
    "gapped-circle": ("SvgCircleDrawer", {"size_ratio": 0.8}),
    "gapped-square": ("SvgSquareDrawer", {"size_ratio": 0.8}),
}

Usage Example:

import qrcode
from qrcode.image.svg import SvgImage

qr = qrcode.QRCode(image_factory=SvgImage)
qr.add_data('SVG Styling')
qr.make()

# Use drawer aliases
img = qr.make_image(module_drawer="gapped-circle")
img.save('svg_gapped_circles.svg')

Advanced Styling Combinations

Combining multiple styling features for complex QR code designs.

Complex Styling Example:

import qrcode
from qrcode.image.styledpil import StyledPilImage
from qrcode.image.styles.moduledrawers import RoundedModuleDrawer, SquareModuleDrawer
from qrcode.image.styles.colormasks import RadialGradiantColorMask
from PIL import Image

# Create highly styled QR code
qr = qrcode.QRCode(
    version=None,
    error_correction=qrcode.constants.ERROR_CORRECT_H,  # High for logo
    box_size=15,                                        # Larger for detail
    border=4,
    image_factory=StyledPilImage
)

qr.add_data('https://example.com/styled')
qr.make()

# Complex styling combination
gradient_mask = RadialGradiantColorMask(
    back_color=(240, 240, 240),   # Light gray background
    center_color=(255, 100, 50),  # Orange center  
    edge_color=(50, 50, 200)      # Blue edges
)

img = qr.make_image(
    module_drawer=RoundedModuleDrawer(radius_ratio=0.4),  # Rounded modules
    eye_drawer=SquareModuleDrawer(),                      # Square eyes
    color_mask=gradient_mask,                             # Gradient colors
    embeded_image_path='company_logo.png'                 # Logo overlay
)

img.save('premium_qr.png')

Performance Considerations

Styling features have different performance characteristics:

  • Module Drawers: Minimal performance impact
  • Color Masks: Moderate impact (pixel-by-pixel processing)
  • Embedded Images: Light impact (simple overlay)
  • Complex Gradients: Higher impact (mathematical calculations per pixel)
  • Antialiasing: Higher impact (4x resolution processing)

Optimization Tips:

# For best performance
qr = qrcode.QRCode(
    box_size=10,                    # Smaller = faster
    image_factory=StyledPilImage
)

# Simple styling (fastest)
img = qr.make_image(
    module_drawer=SquareModuleDrawer(),
    color_mask=SolidFillColorMask(front_color=(0, 0, 200))
)

# Complex styling (slower but higher quality)
img = qr.make_image(
    module_drawer=CircleModuleDrawer(size_ratio=0.9),
    color_mask=RadialGradiantColorMask(),
    embeded_image_path='logo.png'
)

Install with Tessl CLI

npx tessl i tessl/pypi-qrcode@7.4.0
What are skills?

docs

console-interface.md

constants.md

core-generation.md

image-formats.md

index.md

styling.md

tile.json