Package com.itextpdf.kernel.contrast

Class ColorContrastChecker

java.lang.Object
com.itextpdf.kernel.contrast.ColorContrastChecker
All Implemented Interfaces:
IValidationChecker
public class ColorContrastChecker extends Object implements IValidationChecker
A validation checker that analyzes color contrast in PDF documents to ensure compliance with Web Content Accessibility Guidelines (WCAG) standards.

This checker validates the contrast ratio between text and background colors to ensure readability for users with visual impairments. It supports both WCAG 2.0 Level AA and Level AAA conformance levels.

Features: @see ContrastAnalyzer for details.

Current Limitations @see ContrastAnalyzer for details.

  • Constructor Details

    • ColorContrastChecker

      public ColorContrastChecker (boolean checkIndividualGlyphs, boolean throwExceptionOnFailure)
      Creates a new ColorContrastChecker with the specified configuration.
      Parameters:
      checkIndividualGlyphs - if true, contrast is checked at the individual glyph level; if false, contrast is checked at the text block level. Individual glyph checking is more precise but may impact performance.
      throwExceptionOnFailure - if true, a PdfException is thrown when contrast requirements are not met; if false, warnings are logged instead.

  • Method Details

    • setMinimalPercentualCoverage

      public final void setMinimalPercentualCoverage (double minimalPercentualCoverage)
      Sets the minimal percentual coverage of text area that must be covered by a background element for its contrast ratio to be considered in the analysis.

      For example, if set to 0.1 (10%), only background elements that cover at least 10% of the text area will be included in the contrast analysis. This helps filter out insignificant backgrounds that do not meaningfully affect text readability. Like underlines or small decorative elements.

      Parameters:
      minimalPercentualCoverage - the minimal percentual coverage (between 0.0 and 1.0)

    • setCheckWcagAA

      public final ColorContrastChecker setCheckWcagAA (boolean checkWcagAA)
      Sets whether to check for WCAG AA compliance. WCAG AA requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text (18pt+ or 14pt+ bold).
      Parameters:
      checkWcagAA - true to enable WCAG AA compliance checking, false to disable
      Returns:
      this ColorContrastChecker instance for method chaining

    • setCheckWcagAAA

      public final ColorContrastChecker setCheckWcagAAA (boolean checkWcagAAA)
      Sets whether to check for WCAG AAA compliance. WCAG AAA requires a contrast ratio of at least 7:1 for normal text and 4.5:1 for large text (18pt+ or 14pt+ bold).
      Parameters:
      checkWcagAAA - true to enable WCAG AAA compliance checking, false to disable
      Returns:
      this ColorContrastChecker instance for method chaining

    • validate

      public void validate (IValidationContext validationContext)
      Validates the given context for color contrast compliance.

      This method is called by the validation framework to check color contrast when a PDF page is being validated. It only processes validation contexts of type ValidationType.PDF_PAGE.

      Specified by:
      validate in interface IValidationChecker
      Parameters:
      validationContext - the validation context containing the PDF page to validate

    • isPdfObjectReadyToFlush

      public boolean isPdfObjectReadyToFlush (PdfObject object)
      Determines if a PDF object is ready to be flushed to the output stream.

      This implementation always returns true as color contrast checking does not impose any restrictions on when objects can be flushed.

      Specified by:
      isPdfObjectReadyToFlush in interface IValidationChecker
      Parameters:
      object - the PDF object to check
      Returns:
      always true