com.itextpdf.kernel.contrast

Class ContrastAnalyzer

java.lang.Object

com.itextpdf.kernel.contrast.ContrastAnalyzer

public class ContrastAnalyzer
extends Object

Analyzes color contrast ratios between text and backgrounds in PDF pages. This class is designed to help identify accessibility issues related to insufficient contrast between text and background colors, which is important for WCAG compliance.

Features

*Text-to-Background Contrast Analysis: Calculates contrast ratios between text and all overlapping background elements on a page. *Individual Character Analysis: Optional character-by-character analysis for improved accuracy (enabled by default). *Multiple Background Handling: Correctly handles cases where text overlaps multiple backgrounds by analyzing all intersecting backgrounds. *Color Space Support: Supports DeviceRGB, DeviceGray, and DeviceCMYK color spaces. Other color spaces may not be fully supported. *Geometric Calculations: Uses polygon intersection algorithms to accurately determine which backgrounds affect which text elements. *Default Background: Assumes a white background for text that doesn't overlap any explicit background elements.

Current Limitations

*Clipping Path Support: Clipped-out text is currently still processed and analyzed. The analyzer does not respect clipping paths, so text that would be invisible due to clipping will still appear in the contrast results. *Layer Visibility : Content on PDF layers (Optional Content Groups) is always analyzed regardless of layer visibility state. Content on hidden layers will be included in the analysis as if they were visible. *Complex Color Spaces: Advanced color spaces (Lab, ICC-based, Separation, DeviceN, etc.) may not convert accurately to RGB for contrast calculations. *Transparency/Opacity: Does not account for opacity or transparency effects. All elements are treated as fully opaque. *Images as Backgrounds: Currently only analyzes vector path backgrounds. Images used as backgrounds are not considered in the contrast analysis. *Text Rendering Modes: Only analyzes fill color. Stroke color for outlined text is not considered. *Text on Text: Text on Text not supported. *Performance: Character-by-character analysis can be computationally expensive for pages with large amounts of text. *Images Text drawn over images is not analyzed for contrast currently.l

See Also:

ContrastResult, ContrastResult.OverlappingArea, ColorContrastCalculator

Constructor Summary

Constructors

Constructor and Description
ContrastAnalyzer(boolean checkForIndividualCharacters) Creates a new ContrastAnalyzer with default settings.

Method Summary

Modifier and Type	Method and Description
List<ContrastResult>	checkPageContrast(PdfPage page) Analyzes the contrast ratios between text and backgrounds on the given PDF page.
ContrastAnalyzer	setCheckForIndividualCharacters(boolean checkForIndividualCharacters) Sets whether to check contrast for individual characters.
void	setMaxAmountOfPointInPolygon(int maxAmountOfPointInPolygon) Sets the maximum number of points allowed in a polygon for contrast calculations.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ContrastAnalyzer

public ContrastAnalyzer(boolean checkForIndividualCharacters)

Creates a new ContrastAnalyzer with default settings.

Parameters:

checkForIndividualCharacters - true to analyze each character separately, false to analyze whole text as it would be processed by the PDF renderer. @see ContrastAnalyzer#setCheckForIndividualCharacters(boolean)

Method Detail

setMaxAmountOfPointInPolygon

public void setMaxAmountOfPointInPolygon(int maxAmountOfPointInPolygon)

Sets the maximum number of points allowed in a polygon for contrast calculations.

This setting helps prevent performance issues when processing complex shapes. If either the text or background polygon exceeds this number of points, the contrast calculation between them will be skipped. This is particularly useful for handling complex vector graphics The default value is 30 points.

Parameters:

maxAmountOfPointInPolygon - the maximum number of points allowed in a polygon

setCheckForIndividualCharacters

public final ContrastAnalyzer setCheckForIndividualCharacters(boolean checkForIndividualCharacters)

Sets whether to check contrast for individual characters.

When enabled (default), each character in a text string is analyzed separately for contrast. This provides more accurate results as different characters may have different backgrounds, but it significantly impacts performance on pages with large amounts of text.

When disabled, entire text render operations are analyzed as a single unit, which is faster but may miss contrast issues that only affect specific characters within a text string.

Parameters:

checkForIndividualCharacters - true to analyze each character separately, false to analyze whole text as it would be processed by the PDF renderer

Returns:

the ContrastAnalyzer instance for method chaining

checkPageContrast

public List<ContrastResult> checkPageContrast(PdfPage page)

Analyzes the contrast ratios between text and backgrounds on the given PDF page.

This method processes all text and background elements on the page, calculating contrast ratios for each text element against all overlapping backgrounds. The analysis includes:

*Extracting all text render operations and their bounding boxes *Extracting all path render operations that serve as backgrounds *Computing geometric intersections between text and backgrounds *Calculating contrast ratios using WCAG formulas *Handling cases where text overlaps multiple backgrounds

Parameters:

page - the PDF page to analyze for contrast issues

Returns:

a list of contrast results, one for each text element that has overlapping backgrounds. Returns an empty list if no text elements with backgrounds are found.

Throws:

PdfException - if unsupported shape segments are encountered during analysis