Validation

This module provides validation for Phase 4 QR code features to ensure scannability and safety.

Phase 4 Validator

Validation for Phase 4 frame and centerpiece features.

This module provides validation logic for the new Phase 4 features including frame shapes, centerpiece reserves, and quiet zone enhancements.

segnomms.validation.phase4.get_scanability_harness()[source]
Return type:

Optional[QRScanabilityHarness]

class segnomms.validation.phase4.Phase4Validator(qr_version, error_level, matrix_size)[source]

Bases: object

Validation for Phase 4 frame and centerpiece features.

This class provides comprehensive validation for frame shapes, centerpiece reserves, and their interaction with existing QR code features.

Example

>>> validator = Phase4Validator(
...     qr_version=7, error_level='M', matrix_size=45
... )
>>> # Or using Pydantic model
>>> config = Phase4ValidatorConfig(
...     qr_version=7, error_level='m', matrix_size=45
... )
>>> validator = Phase4Validator(**config.model_dump())
Parameters:

  • qr_version (int)

  • error_level (Literal['L', 'M', 'Q', 'H'])

  • matrix_size (int)

__init__(qr_version, error_level, matrix_size)[source]

Initialize the validator.

Parameters:

  • qr_version (int) – QR code version (1-40)

  • error_level (Literal['L', 'M', 'Q', 'H']) – Error correction level (‘L’, ‘M’, ‘Q’, ‘H’)

  • matrix_size (int) – Size of the QR matrix in modules

validate_frame_safety(frame_config, border_modules)[source]

Validate frame configuration for QR code safety.

Parameters:

  • frame_config (FrameConfig) – Frame configuration to validate

  • border_modules (int) – Number of border modules (quiet zone)

Return type:

List[str]

Returns:

List of warning messages (empty if all valid)

validate_centerpiece_safety(centerpiece_config)[source]

Validate centerpiece size against error correction capacity.

Parameters:

centerpiece_config (CenterpieceConfig) – Centerpiece configuration to validate

Return type:

List[str]

Returns:

List of error messages (empty if valid)

validate_contrast_ratio(config, min_ratio=3.0)[source]

Validate color contrast ratio for scanability.

Parameters:

  • config (RenderingConfig) – Rendering configuration containing colors

  • min_ratio (float) – Minimum acceptable contrast ratio (default: 3.0)

Return type:

List[str]

Returns:

List of error messages (empty if valid)

validate_module_size_scanability(config)[source]

Validate module size against scanability requirements.

Parameters:

config (RenderingConfig) – Rendering configuration

Return type:

List[str]

Returns:

List of warning messages

run_automated_scanability_test(config, minimum_success_rate=0.8, test_data='SegnoMMS Test')[source]

Run automated scanability testing harness.

Parameters:

  • config (RenderingConfig) – Rendering configuration to test

  • minimum_success_rate (float) – Minimum required success rate

  • test_data (str) – Data to encode for testing

Return type:

List[str]

Returns:

List of error messages (empty if passes)

validate_combined_features(config)[source]

Check for problematic feature combinations.

Parameters:

config (RenderingConfig) – Complete rendering configuration

Return type:

List[str]

Returns:

List of warning messages

get_recommendations(config)[source]

Get recommendations for optimal configuration.

Parameters:

config (RenderingConfig) – Rendering configuration to analyze

Return type:

List[str]

Returns:

List of recommendation messages

validate_all(config, min_contrast_ratio=3.0, run_scanability_tests=False, min_scanability_success_rate=0.8)[source]

Perform complete validation of Phase 4 features.

Parameters:

  • config (RenderingConfig) – Complete rendering configuration

  • min_contrast_ratio (float) – Minimum contrast ratio for scanability (default: 3.0)

  • run_scanability_tests (bool) – Whether to run automated scanning tests (default: False)

  • min_scanability_success_rate (float) – Minimum success rate for scanning tests (default: 0.8)

Return type:

ValidationResult

Returns:

ValidationResult with errors, warnings, and recommendations

The Phase4Validator class validates frame shapes and centerpiece configurations to prevent settings that might make QR codes unscannable.

Validation Classes

class segnomms.validation.phase4.Phase4Validator(qr_version, error_level, matrix_size)[source]

Bases: object

Validation for Phase 4 frame and centerpiece features.

This class provides comprehensive validation for frame shapes, centerpiece reserves, and their interaction with existing QR code features.

Example

>>> validator = Phase4Validator(
...     qr_version=7, error_level='M', matrix_size=45
... )
>>> # Or using Pydantic model
>>> config = Phase4ValidatorConfig(
...     qr_version=7, error_level='m', matrix_size=45
... )
>>> validator = Phase4Validator(**config.model_dump())
Parameters:

  • qr_version (int)

  • error_level (Literal['L', 'M', 'Q', 'H'])

  • matrix_size (int)

__init__(qr_version, error_level, matrix_size)[source]

Initialize the validator.

Parameters:

  • qr_version (int) – QR code version (1-40)

  • error_level (Literal['L', 'M', 'Q', 'H']) – Error correction level (‘L’, ‘M’, ‘Q’, ‘H’)

  • matrix_size (int) – Size of the QR matrix in modules

validate_frame_safety(frame_config, border_modules)[source]

Validate frame configuration for QR code safety.

Parameters:

  • frame_config (FrameConfig) – Frame configuration to validate

  • border_modules (int) – Number of border modules (quiet zone)

Return type:

List[str]

Returns:

List of warning messages (empty if all valid)

validate_centerpiece_safety(centerpiece_config)[source]

Validate centerpiece size against error correction capacity.

Parameters:

centerpiece_config (CenterpieceConfig) – Centerpiece configuration to validate

Return type:

List[str]

Returns:

List of error messages (empty if valid)

validate_contrast_ratio(config, min_ratio=3.0)[source]

Validate color contrast ratio for scanability.

Parameters:

  • config (RenderingConfig) – Rendering configuration containing colors

  • min_ratio (float) – Minimum acceptable contrast ratio (default: 3.0)

Return type:

List[str]

Returns:

List of error messages (empty if valid)

validate_module_size_scanability(config)[source]

Validate module size against scanability requirements.

Parameters:

config (RenderingConfig) – Rendering configuration

Return type:

List[str]

Returns:

List of warning messages

run_automated_scanability_test(config, minimum_success_rate=0.8, test_data='SegnoMMS Test')[source]

Run automated scanability testing harness.

Parameters:

  • config (RenderingConfig) – Rendering configuration to test

  • minimum_success_rate (float) – Minimum required success rate

  • test_data (str) – Data to encode for testing

Return type:

List[str]

Returns:

List of error messages (empty if passes)

validate_combined_features(config)[source]

Check for problematic feature combinations.

Parameters:

config (RenderingConfig) – Complete rendering configuration

Return type:

List[str]

Returns:

List of warning messages

get_recommendations(config)[source]

Get recommendations for optimal configuration.

Parameters:

config (RenderingConfig) – Rendering configuration to analyze

Return type:

List[str]

Returns:

List of recommendation messages

validate_all(config, min_contrast_ratio=3.0, run_scanability_tests=False, min_scanability_success_rate=0.8)[source]

Perform complete validation of Phase 4 features.

Parameters:

  • config (RenderingConfig) – Complete rendering configuration

  • min_contrast_ratio (float) – Minimum contrast ratio for scanability (default: 3.0)

  • run_scanability_tests (bool) – Whether to run automated scanning tests (default: False)

  • min_scanability_success_rate (float) – Minimum success rate for scanning tests (default: 0.8)

Return type:

ValidationResult

Returns:

ValidationResult with errors, warnings, and recommendations

Validation checks include:

  • Frame Safety: Ensures adequate borders for non-square frames

  • Centerpiece Size: Validates logo area size against error correction capacity

  • Configuration Conflicts: Detects incompatible feature combinations

  • QR Code Limits: Prevents configurations that exceed QR code capabilities

Error Correction Guidelines

The validator enforces safe centerpiece size limits based on error correction levels:

Centerpiece Size Limits

Error Level

Recovery

Max Centerpiece Size

L (Low)

~7%

5% - Very conservative

M (Medium)

~15%

8% - Good for small logos

Q (Quartile)

~25%

15% - Medium logos

H (High)

~30%

20% - Large logos

Frame Validation

Frame shape validation includes:

  • Border Requirements: Minimum quiet zone sizes for different frame shapes

  • Clipping Safety: Ensures critical patterns aren’t clipped by frame shapes

  • Custom Path Validation: Basic validation of custom SVG paths

Examples

Manual Validation:

from segnomms.validation.phase4 import Phase4Validator
from segnomms.config import RenderingConfig
import segno

# Create QR code and config
qr = segno.make("Test data", error='m')
config = RenderingConfig.from_kwargs(
    frame_shape='circle',
    border=3,  # May be too small
    centerpiece_enabled=True,
    centerpiece_size=0.2  # May be too large for M level
)

# Validate configuration
validator = Phase4Validator(qr, config)
warnings = validator.validate_all()

for warning in warnings:
    print(f"Warning: {warning}")

Automatic Validation:

# Validation happens automatically during rendering
from segnomms import write

qr = segno.make("Test", error='l')

# This will log warnings for unsafe configuration
with open('output.svg', 'w') as f:
    write(qr, f,
          frame_shape='circle',
          centerpiece_enabled=True,
          centerpiece_size=0.15,  # Too large for L level
          border=2)  # Too small for circle frame

Validation Results

Validation methods return lists of warning strings:

  • Empty list: Configuration is safe

  • Warning messages: Potential issues that may affect scannability

  • Recommendations: Suggested parameter adjustments

Common Warnings

Frame Shape Warnings:

  • “Circle/custom frames should use 5+ module quiet zone”

  • “Frame shape may clip important QR patterns”

Centerpiece Warnings:

  • “Centerpiece size exceeds safe limit for error level”

  • “Large centerpiece with aggressive merging may cause issues”

Configuration Conflicts:

  • “Custom frame path appears invalid”

  • “Centerpiece offset places logo outside QR bounds”

Best Practices

To avoid validation warnings:

  1. Use adequate borders: 5-6 modules for circle/custom frames

  2. Match error correction to centerpiece size: Use H level for large logos

  3. Test scannability: Always test with target scanning devices

  4. Conservative sizing: Start with smaller centerpieces and increase if needed