Validation

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

Composition Validator

Composition validation for frame and centerpiece features.

This module provides validation logic for QR code composition features including frame shapes, centerpiece reserves, and quiet zone enhancements.

Note: This module was previously named phase4.py. The CompositionValidator class was previously named Phase4Validator. Both old names are retained as deprecated aliases for backward compatibility.

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

Optional[QRScanabilityHarness]

class segnomms.validation.composition.CompositionValidator(qr_version, error_level, matrix_size)[source]

Bases: object

Validates QR code composition including frames and centerpieces.

This class provides comprehensive validation for frame shapes, centerpiece reserves, and their interaction with existing QR code features. It validates that composition choices maintain QR code scannability.

Note

This class was previously named Phase4Validator. The old name is retained as a deprecated alias for backward compatibility.

Example

>>> validator = CompositionValidator(
...     qr_version=7, error_level='M', matrix_size=45
... )
>>> # Or using Pydantic model
>>> config = CompositionValidatorConfig(
...     qr_version=7, error_level='m', matrix_size=45
... )
>>> validator = CompositionValidator(**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 composition 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

segnomms.validation.composition.Phase4Validator

alias of CompositionValidator

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

Note

The CompositionValidator class was previously named Phase4Validator. The old name is retained as a deprecated alias for backward compatibility.

Validation Classes

class segnomms.validation.composition.CompositionValidator(qr_version, error_level, matrix_size)[source]

Bases: object

Validates QR code composition including frames and centerpieces.

This class provides comprehensive validation for frame shapes, centerpiece reserves, and their interaction with existing QR code features. It validates that composition choices maintain QR code scannability.

Note

This class was previously named Phase4Validator. The old name is retained as a deprecated alias for backward compatibility.

Example

>>> validator = CompositionValidator(
...     qr_version=7, error_level='M', matrix_size=45
... )
>>> # Or using Pydantic model
>>> config = CompositionValidatorConfig(
...     qr_version=7, error_level='m', matrix_size=45
... )
>>> validator = CompositionValidator(**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 composition 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 import CompositionValidator
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 = CompositionValidator(
    qr_version=qr.version, error_level='M', matrix_size=qr.symbol_size()[0]
)
result = validator.validate_all(config)

for warning in result.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