Visual Validation¶

Automatic detection of common rendering issues that are invisible in stdout-only environments (e.g. AI agent pipelines). Every check emits structured [VISUAL] log lines so agents can grep and auto-correct.

validate_figure runs all checks by default and is integrated into save_formats() (enabled via validate=True).

Available Checks¶

Check ID	Description	Severity
`overflow`	Artists whose bounding box exceeds the figure canvas	WARNING
`overlap`	Overlapping text labels within each axes	WARNING
`legend_overflow`	Legends occupying too much of the axes area	WARNING
`tick_crowding`	Overcrowded tick labels on either axis	WARNING
`empty_axes`	Axes with no visible data	INFO

Example¶

import matplotlib.pyplot as plt
import dartwork_mpl as dm

fig, ax = plt.subplots()
ax.plot([0, 1], [0, 1])

# Run all checks
warnings = dm.validate_figure(fig)
for w in warnings:
    print(w)

# Run specific checks only
warnings = dm.validate_figure(fig, checks=('overlap', 'tick_crowding'))

# Integrated in save_formats (on by default)
dm.save_formats(fig, 'output/fig', validate=True)

API¶

Core Validation¶

dartwork_mpl.validate_figure(fig: Figure, *, checks: tuple[str, ...] | None = None, quiet: bool = False) → list[VisualWarning][source]¶

Run comprehensive visual validation on a Matplotlib figure.

Parameters:

fig (matplotlib.figure.Figure) – The figure to inspect for visual defects.
checks (tuple[str, ...] | None, optional) – Check IDs to run. If None, all registered checks are executed. Supported IDs: OVERFLOW, OVERLAP, LEGEND_OVERFLOW, TICK_CROWD, EMPTY_AXES, MARGIN_ASYMMETRY, PIE_LABEL_OFFSET.
quiet (bool, optional) – If True, suppresses stdout output. Default is False.

Returns:

List of detected visual issues.

Return type:

list[VisualWarning]

Enhanced Validation with Auto-Fix¶

The validate_enhanced module provides advanced validation with automatic fix suggestions, particularly useful for AI agents and automated pipelines.

Enhanced validation with auto-fix suggestions for agents.

Extends the base validation with actionable fixes that agents can apply.

dartwork_mpl.validate_enhanced.check_agent_requirements(fig: Figure) → dict[str, bool][source]

Check if figure meets agent coding requirements.

Parameters:: fig (Figure) – Figure to check
Returns:: Requirement name -> pass/fail
Return type:: dict[str, bool]

dartwork_mpl.validate_enhanced.generate_validation_report(fig: Figure) → str[source]

Generate a comprehensive validation report for agents.

Parameters:: fig (Figure) – Figure to validate
Returns:: Formatted validation report
Return type:: str

dartwork_mpl.validate_enhanced.get_fix_suggestions(warning: VisualWarning) → list[str][source]

Generate fix suggestions for a visual warning.

Parameters:: warning (VisualWarning) – The warning to generate fixes for
Returns:: List of suggested fixes (code snippets)
Return type:: list[str]

dartwork_mpl.validate_enhanced.validate_with_fixes(fig: Figure, auto_apply: bool = False, verbose: bool = True) → tuple[list[VisualWarning], list[str]][source]

Validate figure and provide fix suggestions.

Parameters:

fig (Figure) – Figure to validate
auto_apply (bool) – Whether to attempt automatic fixes
verbose (bool) – Whether to print suggestions

Returns:

Warnings and applied fixes

Return type:

tuple[list[VisualWarning], list[str]]

Example with Auto-Fix¶

import dartwork_mpl as dm
from dartwork_mpl.validate_enhanced import validate_with_fixes

# Validate and get fix suggestions
issues, fixes = validate_with_fixes(fig)

# Apply suggested fixes
for fix in fixes:
    if fix['auto_fixable']:
        fix['apply'](fig, **fix['params'])

# Generate report for logging
report = generate_validation_report(issues, fixes)
print(report)