Configuration

This module handles configuration and parameter validation for the plugin.

Configuration Models

Core configuration models.

This module contains the main RenderingConfig class that combines all other configuration models into a comprehensive configuration system.

class segnomms.config.models.core.RenderingConfig(**data)[source]

Bases: BaseModel

Main QR code rendering configuration.

This is the central configuration class that combines all aspects of QR code generation including geometry, visual styling, advanced features, and processing phases.

The configuration supports both Pydantic model initialization and a convenient kwargs-based factory method for backward compatibility.

Parameters:

scale (int)
border (int)
dark (str)
light (str)
safe_mode (bool)
geometry (GeometryConfig)
finder (FinderConfig)
patterns (PatternStyleConfig)
frame (FrameConfig)
centerpiece (CenterpieceConfig)
quiet_zone (QuietZoneConfig)
style (StyleConfig)
phase1 (Phase1Config)
phase2 (Phase2Config)
phase3 (Phase3Config)
advanced_qr (AdvancedQRConfig)
accessibility (AccessibilityConfig)
shape_options (Dict[str, Any] | None)
min_contrast_ratio (float)
enable_palette_validation (bool)
enforce_wcag_standards (bool)
metadata (Dict[str, Any] | None)

scale: Size of each module in pixels

border: Quiet zone border thickness in modules

dark: Primary foreground color (hex, rgb, or named)

light: Primary background color (hex, rgb, or named)

safe_mode: Enable safe fallback modes for production

geometry: Module geometry and shape configuration

finder: Finder pattern styling configuration

patterns: Pattern-specific styling configuration

frame: Frame shape and clipping configuration

centerpiece: Central reserve area configuration

quiet_zone: Quiet zone styling configuration

style: General styling and CSS configuration

phase1: Phase 1 processing configuration (enhanced shapes)

phase2: Phase 2 processing configuration (clustering)

phase3: Phase 3 processing configuration (contours)

advanced_qr: Advanced QR features configuration

accessibility: Accessibility features configuration

shape_options: Additional shape-specific parameters

min_contrast_ratio: Minimum WCAG contrast ratio requirement

enable_palette_validation: Validate color accessibility

enforce_wcag_standards: Enforce WCAG AA/AAA compliance

Example

Creating configuration with model syntax:

config = RenderingConfig(
    scale=10,
    dark="#1a1a2e",
    light="#ffffff",
    geometry=GeometryConfig(
        shape="rounded",
        corner_radius=0.3
    ),
    style=StyleConfig(interactive=True)
)

Creating configuration from kwargs (backward compatible):

config = RenderingConfig.from_kwargs(
    scale=10,
    dark="#1a1a2e",
    light="#ffffff",
    shape="rounded",
    corner_radius=0.3,
    interactive=True
)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

scale: int

border: int

dark: str

light: str

safe_mode: bool

geometry: GeometryConfig

finder: FinderConfig

patterns: PatternStyleConfig

frame: FrameConfig

centerpiece: CenterpieceConfig

quiet_zone: QuietZoneConfig

style: StyleConfig

phase1: Phase1Config

phase2: Phase2Config

phase3: Phase3Config

advanced_qr: AdvancedQRConfig

accessibility: AccessibilityConfig

shape_options: Optional[Dict[str, Any]]

min_contrast_ratio: float

enable_palette_validation: bool

enforce_wcag_standards: bool

metadata: Optional[Dict[str, Any]]

classmethod validate_colors(v)[source]

Validate color format.

Return type:: str
Parameters:: v (str)

classmethod from_kwargs(**kwargs)[source]

Create RenderingConfig from flat kwargs for backward compatibility.

This factory method allows creating configuration using the traditional flat parameter approach while internally organizing into the structured configuration model.

Parameters:: **kwargs (Any) – Flat configuration parameters
Return type:: RenderingConfig
Returns:: RenderingConfig instance with organized configuration

Example

config = RenderingConfig.from_kwargs(: scale=10, border=4, dark=”#1a1a2e”, light=”#ffffff”, shape=”rounded”, corner_radius=0.3, merge=”soft”, connectivity=”8-way”, interactive=True, centerpiece_enabled=True, centerpiece_size=0.15

)

validate_palette()[source]

Validate the color palette using enhanced validation.

Return type:: PaletteValidationResult

get_contrast_ratio()[source]

Get contrast ratio between primary dark and light colors.

Return type:: Optional[float]

meets_contrast_requirements()[source]

Check if primary colors meet minimum contrast requirements.

Return type:: bool

to_kwargs()[source]

Convert configuration back to kwargs format.

Returns flat kwargs dictionary suitable for passing to from_kwargs.

Return type:: Dict[str, Any]

classmethod json_schema()[source]

Generate JSON Schema for the configuration.

Return type:: Dict[str, Any]
Returns:: JSON Schema dictionary for external tools and documentation

to_json()[source]

Serialize configuration to JSON string.

Return type:: str
Returns:: JSON string representation of the configuration

classmethod from_json(json_str)[source]

Create configuration from JSON string.

Parameters:: json_str (str) – JSON string representation
Return type:: RenderingConfig
Returns:: RenderingConfig instance

class segnomms.config.models.core.PerformanceConfig(**data)[source]

Bases: BaseModel

Performance and optimization settings.

Parameters:

enable_caching (bool)
max_cache_size (int)
enable_parallel_processing (bool)
memory_limit_mb (int | None)
debug_timing (bool)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enable_caching: bool

max_cache_size: int

enable_parallel_processing: bool

memory_limit_mb: Optional[int]

debug_timing: bool

class segnomms.config.models.core.DebugConfig(**data)[source]

Bases: BaseModel

Debug and development settings.

Parameters:

debug_mode (bool)
debug_stroke (bool)
debug_colors (Dict[str, str])
save_intermediate_results (bool)
verbose_logging (bool)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

debug_mode: bool

debug_stroke: bool

debug_colors: Dict[str, str]

save_intermediate_results: bool

verbose_logging: bool

Main Configuration Class

class segnomms.config.models.core.RenderingConfig(**data)[source]

Bases: BaseModel

Main QR code rendering configuration.

This is the central configuration class that combines all aspects of QR code generation including geometry, visual styling, advanced features, and processing phases.

The configuration supports both Pydantic model initialization and a convenient kwargs-based factory method for backward compatibility.

Parameters:

scale (Annotated[int, Ge(ge=1), Le(le=100)])
border (Annotated[int, Ge(ge=0), Le(le=20)])
dark (str)
light (str)
safe_mode (bool)
geometry (GeometryConfig)
finder (FinderConfig)
patterns (PatternStyleConfig)
frame (FrameConfig)
centerpiece (CenterpieceConfig)
quiet_zone (QuietZoneConfig)
style (StyleConfig)
phase1 (Phase1Config)
phase2 (Phase2Config)
phase3 (Phase3Config)
advanced_qr (AdvancedQRConfig)
accessibility (AccessibilityConfig)
shape_options (Dict[str, Any] | None)
min_contrast_ratio (Annotated[float, Ge(ge=1.0), Le(le=21.0)])
enable_palette_validation (bool)
enforce_wcag_standards (bool)
metadata (Dict[str, Any] | None)

scale: Size of each module in pixels

border: Quiet zone border thickness in modules

dark: Primary foreground color (hex, rgb, or named)

light: Primary background color (hex, rgb, or named)

safe_mode: Enable safe fallback modes for production

geometry: Module geometry and shape configuration

finder: Finder pattern styling configuration

patterns: Pattern-specific styling configuration

frame: Frame shape and clipping configuration

centerpiece: Central reserve area configuration

quiet_zone: Quiet zone styling configuration

style: General styling and CSS configuration

phase1: Phase 1 processing configuration (enhanced shapes)

phase2: Phase 2 processing configuration (clustering)

phase3: Phase 3 processing configuration (contours)

advanced_qr: Advanced QR features configuration

accessibility: Accessibility features configuration

shape_options: Additional shape-specific parameters

min_contrast_ratio: Minimum WCAG contrast ratio requirement

enable_palette_validation: Validate color accessibility

enforce_wcag_standards: Enforce WCAG AA/AAA compliance

Example

Creating configuration with model syntax:

config = RenderingConfig(
    scale=10,
    dark="#1a1a2e",
    light="#ffffff",
    geometry=GeometryConfig(
        shape="rounded",
        corner_radius=0.3
    ),
    style=StyleConfig(interactive=True)
)

Creating configuration from kwargs (backward compatible):

config = RenderingConfig.from_kwargs(
    scale=10,
    dark="#1a1a2e",
    light="#ffffff",
    shape="rounded",
    corner_radius=0.3,
    interactive=True
)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

scale: int

border: int

dark: str

light: str

safe_mode: bool

geometry: GeometryConfig

finder: FinderConfig

patterns: PatternStyleConfig

frame: FrameConfig

centerpiece: CenterpieceConfig

quiet_zone: QuietZoneConfig

style: StyleConfig

phase1: Phase1Config

phase2: Phase2Config

phase3: Phase3Config

advanced_qr: AdvancedQRConfig

accessibility: AccessibilityConfig

shape_options: Optional[Dict[str, Any]]

min_contrast_ratio: float

enable_palette_validation: bool

enforce_wcag_standards: bool

metadata: Optional[Dict[str, Any]]

classmethod validate_colors(v)[source]

Validate color format.

Return type:: str
Parameters:: v (str)

classmethod from_kwargs(**kwargs)[source]

Create RenderingConfig from flat kwargs for backward compatibility.

This factory method allows creating configuration using the traditional flat parameter approach while internally organizing into the structured configuration model.

Parameters:: **kwargs (Any) – Flat configuration parameters
Return type:: RenderingConfig
Returns:: RenderingConfig instance with organized configuration

Example

config = RenderingConfig.from_kwargs(: scale=10, border=4, dark=”#1a1a2e”, light=”#ffffff”, shape=”rounded”, corner_radius=0.3, merge=”soft”, connectivity=”8-way”, interactive=True, centerpiece_enabled=True, centerpiece_size=0.15

)

validate_palette()[source]

Validate the color palette using enhanced validation.

Return type:: PaletteValidationResult

get_contrast_ratio()[source]

Get contrast ratio between primary dark and light colors.

Return type:: Optional[float]

meets_contrast_requirements()[source]

Check if primary colors meet minimum contrast requirements.

Return type:: bool

to_kwargs()[source]

Convert configuration back to kwargs format.

Returns flat kwargs dictionary suitable for passing to from_kwargs.

Return type:: Dict[str, Any]

classmethod json_schema()[source]

Generate JSON Schema for the configuration.

Return type:: Dict[str, Any]
Returns:: JSON Schema dictionary for external tools and documentation

to_json()[source]

Serialize configuration to JSON string.

Return type:: str
Returns:: JSON string representation of the configuration

classmethod from_json(json_str)[source]

Create configuration from JSON string.

Parameters:: json_str (str) – JSON string representation
Return type:: RenderingConfig
Returns:: RenderingConfig instance

The RenderingConfig class is the main configuration object that controls all aspects of QR code rendering.

Example Usage

from segnomms.config import RenderingConfig

# Create configuration from kwargs
config = RenderingConfig.from_kwargs(
    shape='connected',
    scale=20,
    dark='#1e40af',
    light='#dbeafe',
    safe_mode=False
)

# Access configuration values
print(config.shape)      # 'connected'
print(config.scale)      # 20
print(config.dark)       # '#1e40af'

Configuration Parameters

Core Parameters

Parameter	Type	Default	Description
shape	str	‘square’	Shape type for QR modules
scale	int	10	Size of each module in pixels
border	int	4	Quiet zone size in modules
dark	str	‘black’	Color for dark modules
light	str	‘white’	Color for light modules
safe_mode	bool	True	Use simple shapes for special patterns

SVG Parameters

Parameter	Type	Default	Description
xmldecl	bool	True	Include XML declaration
svgclass	str	‘interactive-qr’	CSS class for SVG element
lineclass	str	None	CSS class for path elements
title	str	‘Interactive QR Code’	SVG title element
desc	str	Auto	SVG description element
svgid	str	‘qr-code’	ID for SVG element

Phase Configuration

The plugin uses a three-phase rendering approach:

Phase 1 - Clustering

class segnomms.config.models.phases.Phase1Config(**data)[source]

Configuration for Phase 1: Enhanced 8-neighbor detection.

This phase handles context-aware shape rendering based on neighboring modules.

Parameters:

enabled (bool)
use_enhanced_shapes (bool)
roundness (float)
size_ratio (float)
flow_weights (Dict[str, float])

enabled: Whether Phase 1 processing is enabled

use_enhanced_shapes: Use enhanced shape variants

roundness: Corner roundness factor (0.0-1.0)

size_ratio: Module size relative to grid size (0.1-1.0)

flow_weights: Weight factors for different module types

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enabled: bool

use_enhanced_shapes: bool

roundness: float

size_ratio: float

flow_weights: Dict[str, float]

Phase 2 - Shape Rendering

class segnomms.config.models.phases.Phase2Config(**data)[source]

Configuration for Phase 2: Connected component clustering.

This phase groups connected modules for optimized rendering.

Parameters:

enabled (bool)
use_cluster_rendering (bool)
cluster_module_types (List[str])
min_cluster_size (int)
density_threshold (float)
aspect_ratio_tolerance (float)

enabled: Whether Phase 2 processing is enabled

use_cluster_rendering: Render clusters as single shapes

cluster_module_types: Module types to include in clustering

min_cluster_size: Minimum modules required to form a cluster

density_threshold: Minimum density for valid clusters (0.0-1.0)

aspect_ratio_tolerance: Maximum deviation from square clusters (0.0-1.0)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enabled: bool

use_cluster_rendering: bool

cluster_module_types: List[str]

min_cluster_size: int

density_threshold: float

aspect_ratio_tolerance: float

Phase 3 - SVG Assembly

class segnomms.config.models.phases.Phase3Config(**data)[source]

Configuration for Phase 3: Marching squares with Bezier curves.

This phase creates smooth contours around module groups.

Parameters:

enabled (bool)
use_marching_squares (bool)
contour_module_types (List[str])
contour_mode (ContourMode)
contour_smoothing (float)
bezier_optimization (OptimizationLevel)
tension (float)
point_reduction (float)

enabled: Whether Phase 3 processing is enabled

use_marching_squares: Apply marching squares algorithm

contour_module_types: Module types to generate contours for

contour_mode: Contour rendering strategy

contour_smoothing: Smoothing factor for contours (0.0-1.0)

bezier_optimization: Optimization level for curve generation

tension: Bezier curve tension (0.0-1.0)

point_reduction: Factor for reducing control points (0.0-1.0)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enabled: bool

use_marching_squares: bool

contour_module_types: List[str]

contour_mode: ContourMode

contour_smoothing: float

bezier_optimization: OptimizationLevel

tension: float

point_reduction: float

Plugin Configuration

class segnomms.config.models.core.DebugConfig(**data)[source]

Debug and development settings.

Parameters:

debug_mode (bool)
debug_stroke (bool)
debug_colors (Dict[str, str])
save_intermediate_results (bool)
verbose_logging (bool)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

debug_mode: bool

debug_stroke: bool

debug_colors: Dict[str, str]

save_intermediate_results: bool

verbose_logging: bool

Phase 4 Configuration

Phase 4 introduces advanced features for professional QR code generation.

Frame Configuration

class segnomms.config.models.visual.FrameConfig(**data)[source]

Frame shape configuration for QR codes.

Parameters:

shape (Literal['square', 'circle', 'rounded-rect', 'squircle', 'custom'])
corner_radius (float)
clip_mode (Literal['clip', 'fade', 'scale'])
custom_path (str | None)
fade_distance (float)
scale_distance (float)

shape: Frame shape type (‘square’, ‘circle’, ‘rounded-rect’, ‘squircle’, ‘custom’)

corner_radius: Corner radius for rounded-rect (0.0-1.0)

clip_mode: How to apply frame (‘clip’ for hard edge, ‘fade’ for gradient)

custom_path: SVG path string for custom frame shapes

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

shape: Literal['square', 'circle', 'rounded-rect', 'squircle', 'custom']

corner_radius: float

clip_mode: Literal['clip', 'fade', 'scale']

custom_path: Optional[str]

fade_distance: float

scale_distance: float

validate_custom_path()[source]

Validate that custom_path is provided for custom frame shapes.

Return type:: Self

Controls the outer boundary shape of QR codes. Available frame shapes:

square: Standard rectangular boundary (default)
circle: Circular boundary with automatic radius calculation
rounded-rect: Rectangle with customizable corner radius
squircle: Modern superellipse shape (between square and circle)
custom: User-defined SVG path for unique shapes

Centerpiece Configuration

class segnomms.config.models.visual.CenterpieceConfig(**data)[source]

Centerpiece reserve area configuration.

Parameters:

enabled (bool)
shape (Literal['rect', 'circle', 'squircle'])
size (float)
offset_x (float)
offset_y (float)
margin (int)
mode (ReserveMode)
placement (PlacementMode)

enabled: Whether to reserve center area

shape: Shape of reserved area (‘rect’, ‘circle’, ‘squircle’)

size: Size relative to QR code (0.0-0.5)

offset_x: Horizontal offset (-0.5 to 0.5) - used when placement is ‘custom’

offset_y: Vertical offset (-0.5 to 0.5) - used when placement is ‘custom’

margin: Module margin around reserved area

mode: Reserve area interaction mode (knockout or imprint)

placement: Placement mode for positioning (custom, center, corners, edges)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enabled: bool

shape: Literal['rect', 'circle', 'squircle']

size: float

offset_x: float

offset_y: float

margin: int

mode: ReserveMode

placement: PlacementMode

validate_enabled_fields()[source]

Additional validation when centerpiece is enabled.

Return type:: Self

Manages logo area reservation in the center of QR codes. The centerpiece area is automatically cleared of QR modules while preserving critical patterns like finder patterns and timing patterns.

Size Guidelines by Error Correction Level:

L Level (7% recovery): Max 5% centerpiece - very conservative
M Level (15% recovery): Max 8% centerpiece - good for small logos
Q Level (25% recovery): Max 15% centerpiece - medium logos
H Level (30% recovery): Max 20% centerpiece - large logos

Quiet Zone Configuration

class segnomms.config.models.visual.QuietZoneConfig(**data)[source]

Quiet zone styling configuration.

Parameters:

color (str)
style (Literal['solid', 'gradient', 'none'])
gradient (Dict[str, Any] | None)

color: Fill color for quiet zone

style: Style type (‘solid’, ‘gradient’, ‘none’)

gradient: Gradient definition for style=’gradient’

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

color: str

style: Literal['solid', 'gradient', 'none']

gradient: Optional[Dict[str, Any]]

validate_gradient_required()[source]

Validate that gradient is provided for gradient style.

Return type:: Self

Enhances the quiet zone (border area) around QR codes with solid colors or gradient backgrounds for improved visual appeal and branding.

Shape Options

Shape-specific parameters can be passed through shape_options:

config = RenderingConfig.from_kwargs(
    shape='star',
    shape_options={
        'star_points': 8,
        'inner_ratio': 0.3
    }
)

Or passed directly as kwargs:

config = RenderingConfig.from_kwargs(
    shape='star',
    star_points=8,
    inner_ratio=0.3
)

Phase 4 Configuration Examples

Circle frame with centerpiece:

config = RenderingConfig.from_kwargs(
    frame_shape='circle',
    centerpiece_enabled=True,
    centerpiece_shape='circle',
    centerpiece_size=0.15,
    border=6
)

Professional business card configuration:

config = RenderingConfig.from_kwargs(
    scale=20,
    border=6,
    frame_shape='rounded-rect',
    frame_corner_radius=0.2,
    centerpiece_enabled=True,
    centerpiece_shape='circle',
    centerpiece_size=0.12,
    quiet_zone_style='gradient',
    quiet_zone_gradient={
        'type': 'radial',
        'colors': ['#ffffff', '#f8f9fa']
    },
    shape='squircle',
    merge='soft'
)

Direct configuration object creation:

from segnomms.config import (
    RenderingConfig, FrameConfig, CenterpieceConfig, QuietZoneConfig
)

# Create individual config objects
frame_config = FrameConfig(
    shape='squircle',
    clip_mode='fade'
)

centerpiece_config = CenterpieceConfig(
    enabled=True,
    shape='circle',
    size=0.14,
    margin=3
)

quiet_zone_config = QuietZoneConfig(
    style='gradient',
    gradient={
        'type': 'linear',
        'colors': ['#f8f9fa', '#e9ecef']
    }
)

# Combine into main config
config = RenderingConfig(
    scale=18,
    border=5,
    frame=frame_config,
    centerpiece=centerpiece_config,
    quiet_zone=quiet_zone_config
)