Frame Shapes

This module provides frame shape generators for Phase 4 QR code rendering.

Frame Shape Generator

Frame shape generators for QR codes.

This module provides generators for creating SVG clipping paths and masks for various frame shapes including circles, rounded rectangles, and squircles.

class segnomms.shapes.frames.FrameShapeGenerator[source]

Bases: object

Generates SVG paths and definitions for frame shapes.

This class provides static methods to generate various frame shapes as SVG elements for use in clipping paths and masks.

static generate_circle_clip(width, height, border=0)[source]

Generate circular clipping path.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • border (int) – Border size in pixels (unused for circle)

Return type:

str

Returns:

SVG circle element as string

static generate_rounded_rect_clip(width, height, border, corner_radius)[source]

Generate rounded rectangle clipping path.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • border (int) – Border size in pixels (unused)

  • corner_radius (float) – Corner radius as fraction (0.0-1.0)

Return type:

str

Returns:

SVG rect element with rounded corners as string

static generate_squircle_clip(width, height, border=0)[source]

Generate squircle (superellipse) clipping path.

A squircle is a mathematical shape between a square and a circle, defined by the superellipse equation with n=4.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • border (int) – Border size in pixels (unused)

Return type:

str

Returns:

SVG path element forming a squircle as string

static generate_fade_mask(width, height, shape, fade_distance, corner_radius=0.0, custom_path=None)[source]

Generate fade mask for soft edges.

Creates a gradient mask that provides a soft fade effect at the edges of the frame shape using SVG gradients and masks.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • shape (str) – Frame shape type (‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’)

  • fade_distance (float) – Fade distance in pixels

  • corner_radius (float) – Corner radius for rounded-rect (0.0-1.0)

  • custom_path (Optional[str]) – Custom SVG path for custom shapes

Return type:

str

Returns:

SVG gradient and mask elements as string

static generate_scale_transform(width, height, shape, scale_distance, corner_radius=0.0, custom_path=None)[source]

Generate scale transform for modules near frame edges.

Creates transform groups that gradually scale down modules as they approach the frame edge, creating a smooth transition effect.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • shape (str) – Frame shape type (‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’)

  • scale_distance (float) – Distance in pixels from edge where scaling begins

  • corner_radius (float) – Corner radius for rounded-rect (0.0-1.0)

  • custom_path (Optional[str]) – Custom SVG path for custom shapes

Return type:

Tuple[str, str]

Returns:

Tuple of (clip_path_url, scale_group_transform)

static validate_custom_path(path, width, height)[source]

Validate a custom SVG path.

Performs basic validation on custom SVG path strings to ensure they are likely to work as clipping paths.

Parameters:

  • path (str) – SVG path data string

  • width (int) – Expected width for the path

  • height (int) – Expected height for the path

Return type:

Tuple[bool, str]

Returns:

Tuple of (is_valid, error_message)

static scale_path_to_fit(path, current_box, target_width, target_height)[source]

Scale an SVG path to fit target dimensions.

This is a placeholder for path scaling functionality. In practice, this would parse the path and transform coordinates.

Parameters:

  • path (str) – Original SVG path string

  • current_box (Tuple[float, float, float, float]) – Current bounding box (x, y, width, height)

  • target_width (int) – Target width in pixels

  • target_height (int) – Target height in pixels

Return type:

str

Returns:

Scaled SVG path string

static create_frame_group(shape_type, width, height, config=None)[source]

Create a complete frame shape group.

Convenience method to create a frame shape element that can be directly inserted into an SVG.

Parameters:

  • shape_type (str) – Type of frame (‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’)

  • width (int) – Frame width in pixels

  • height (int) – Frame height in pixels

  • config (Optional[Dict[str, Any]]) – Additional configuration (corner_radius, custom_path, etc.)

Return type:

Element

Returns:

ET.Element containing the frame shape

The FrameShapeGenerator class provides static methods for generating SVG clipping paths and masks for various frame shapes.

Available Frame Shapes

class segnomms.shapes.frames.FrameShapeGenerator[source]

Bases: object

Generates SVG paths and definitions for frame shapes.

This class provides static methods to generate various frame shapes as SVG elements for use in clipping paths and masks.

static generate_circle_clip(width, height, border=0)[source]

Generate circular clipping path.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • border (int) – Border size in pixels (unused for circle)

Return type:

str

Returns:

SVG circle element as string

static generate_rounded_rect_clip(width, height, border, corner_radius)[source]

Generate rounded rectangle clipping path.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • border (int) – Border size in pixels (unused)

  • corner_radius (float) – Corner radius as fraction (0.0-1.0)

Return type:

str

Returns:

SVG rect element with rounded corners as string

static generate_squircle_clip(width, height, border=0)[source]

Generate squircle (superellipse) clipping path.

A squircle is a mathematical shape between a square and a circle, defined by the superellipse equation with n=4.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • border (int) – Border size in pixels (unused)

Return type:

str

Returns:

SVG path element forming a squircle as string

static generate_fade_mask(width, height, shape, fade_distance, corner_radius=0.0, custom_path=None)[source]

Generate fade mask for soft edges.

Creates a gradient mask that provides a soft fade effect at the edges of the frame shape using SVG gradients and masks.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • shape (str) – Frame shape type (‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’)

  • fade_distance (float) – Fade distance in pixels

  • corner_radius (float) – Corner radius for rounded-rect (0.0-1.0)

  • custom_path (Optional[str]) – Custom SVG path for custom shapes

Return type:

str

Returns:

SVG gradient and mask elements as string

static generate_scale_transform(width, height, shape, scale_distance, corner_radius=0.0, custom_path=None)[source]

Generate scale transform for modules near frame edges.

Creates transform groups that gradually scale down modules as they approach the frame edge, creating a smooth transition effect.

Parameters:

  • width (int) – Total SVG width in pixels

  • height (int) – Total SVG height in pixels

  • shape (str) – Frame shape type (‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’)

  • scale_distance (float) – Distance in pixels from edge where scaling begins

  • corner_radius (float) – Corner radius for rounded-rect (0.0-1.0)

  • custom_path (Optional[str]) – Custom SVG path for custom shapes

Return type:

Tuple[str, str]

Returns:

Tuple of (clip_path_url, scale_group_transform)

static validate_custom_path(path, width, height)[source]

Validate a custom SVG path.

Performs basic validation on custom SVG path strings to ensure they are likely to work as clipping paths.

Parameters:

  • path (str) – SVG path data string

  • width (int) – Expected width for the path

  • height (int) – Expected height for the path

Return type:

Tuple[bool, str]

Returns:

Tuple of (is_valid, error_message)

static scale_path_to_fit(path, current_box, target_width, target_height)[source]

Scale an SVG path to fit target dimensions.

This is a placeholder for path scaling functionality. In practice, this would parse the path and transform coordinates.

Parameters:

  • path (str) – Original SVG path string

  • current_box (Tuple[float, float, float, float]) – Current bounding box (x, y, width, height)

  • target_width (int) – Target width in pixels

  • target_height (int) – Target height in pixels

Return type:

str

Returns:

Scaled SVG path string

static create_frame_group(shape_type, width, height, config=None)[source]

Create a complete frame shape group.

Convenience method to create a frame shape element that can be directly inserted into an SVG.

Parameters:

  • shape_type (str) – Type of frame (‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’)

  • width (int) – Frame width in pixels

  • height (int) – Frame height in pixels

  • config (Optional[Dict[str, Any]]) – Additional configuration (corner_radius, custom_path, etc.)

Return type:

Element

Returns:

ET.Element containing the frame shape

Supported frame shapes include:

  • square: Standard rectangular QR code (default)

  • circle: Circular boundary with equal radius

  • rounded-rect: Rectangle with customizable corner radius

  • squircle: Modern superellipse shape (between square and circle)

  • custom: User-defined SVG path

Examples

Circular Frame:

from segnomms.shapes.frames import FrameShapeGenerator

# Generate circular clipping path
circle_clip = FrameShapeGenerator.generate_circle_clip(200, 200)
print(circle_clip)  # <circle cx="100" cy="100" r="100"/>

Rounded Rectangle:

# Generate rounded rectangle with 20% corner radius
rounded_clip = FrameShapeGenerator.generate_rounded_rect_clip(
    200, 200, border=10, corner_radius=0.2
)

Custom Frame Shape:

# Use with a custom SVG path via the main write() API
diamond_path = "M 100 0 L 200 100 L 100 200 L 0 100 Z"
# See usage with QR codes below for passing frame_custom_path

Usage with QR Codes

Frame shapes are typically used through the main write function:

import segno
from segnomms import write

qr = segno.make("https://example.com", error='h')

# Circle frame
with open('circle_frame.svg', 'w') as f:
    write(qr, f, frame_shape='circle', border=6)

# Rounded rectangle frame
with open('rounded_frame.svg', 'w') as f:
    write(qr, f,
          frame_shape='rounded-rect',
          frame_corner_radius=0.3,
          border=5)

# Custom diamond frame
with open('diamond_frame.svg', 'w') as f:
    write(qr, f,
          frame_shape='custom',
          frame_custom_path="M 100 0 L 200 100 L 100 200 L 0 100 Z",
          border=8)