ActionResult Components Quick Reference

Component Overview

ActionResult v2.0 delegates to specialized components for different responsibilities. This quick reference helps you find the right component for your needs.

Component Directory

Core Match Operations → MatchCollection

MatchCollection matches = result.getMatchCollection();

• Add/remove matches
• Sort by score, size, distance
• Filter by criteria
• Get best match
• Get statistics
• Set operations (union, intersection, minus)

Common Operations:

matches.add(match1, match2);
matches.sortByScoreDescending();
matches.filterByMinScore(0.8);
Optional<Match> best = matches.getBest();

Statistical Analysis → MatchStatistics

MatchStatistics stats = result.getMatchCollection().getStatistics();

• Average/min/max scores
• Median region/location
• Standard deviation
• Confidence levels
• Bounding boxes
• Density calculations

Common Operations:

double avgScore = stats.getAverageScore();
Optional<Region> median = stats.getMedianRegion();
ConfidenceLevel confidence = stats.getConfidence();

Timing & Duration → TimingData

TimingData timing = result.getTimingData();

• Start/stop timing
• Calculate duration
• Track time segments
• Format time output

Common Operations:

timing.start();
timing.stop();
Duration elapsed = timing.getElapsed();
timing.addSegment("search", searchDuration);

Text Extraction → TextExtractionResult

TextExtractionResult text = result.getTextResult();

• Accumulated text
• Selected text
• Match-specific text
• Text merging

Common Operations:

text.addText("extracted text");
text.setSelectedText("highlighted");
String combined = text.getCombinedText();

State Tracking → StateTracker

StateTracker states = result.getStateTracker();

• Active states
• State-match mapping
• Activation counts
• Most active state

Common Operations:

states.recordActiveState("LoginScreen");
boolean isActive = states.isStateActive("LoginScreen");
Optional<String> mostActive = states.getMostActiveState();

Region Management → RegionManager

RegionManager regions = result.getRegionManager();

• Define regions
• Named regions
• Union/intersection
• Area-based operations

Common Operations:

regions.defineRegion(new Region(x, y, w, h));
regions.defineNamedRegion("button", buttonRegion);
Optional<Region> union = regions.getUnion();

Movement Tracking → MovementTracker

MovementTracker movements = result.getMovementTracker();

• Record movements
• Calculate distances
• Path analysis
• Bounding boxes

Common Operations:

movements.recordMovement(start, end);
double totalDistance = movements.getTotalDistance();
boolean isClosed = movements.isClosedPath(5.0);

Analysis Data → ActionAnalysis

ActionAnalysis analysis = result.getActionAnalysis();

• Scene analyses
• Binary masks
• Custom analysis storage
• Type-safe retrieval

Common Operations:

analysis.addSceneAnalysis(sceneAnalysis);
analysis.setMask(binaryMask);
analysis.addCustomAnalysis("profile", colorProfile);

Performance Metrics → ActionMetrics

ActionMetrics metrics = result.getActionMetrics();

• Execution time
• Retry tracking
• Phase timings
• Efficiency scores

Common Operations:

metrics.recordExecutionTime(duration);
metrics.recordRetry(retryDuration);
metrics.recordPhase("validation", validationTime);
double efficiency = metrics.getEfficiencyScore();

Execution History → ExecutionHistory

ExecutionHistory history = result.getExecutionHistory();

• Action records
• Success/failure tracking
• Timeline generation
• Success rates

Common Operations:

history.recordStep(actionRecord);
double successRate = history.getSuccessRate();
String timeline = history.formatTimeline();

Quick Lookup Table

I want to...	Use Component	Method
Add a match	MatchCollection	add(match)
Sort matches	MatchCollection	sortByScoreDescending()
Filter matches	MatchCollection	filterByMinScore(0.8)
Get best match	MatchCollection	getBest()
Get match statistics	MatchStatistics	getAverageScore()
Track timing	TimingData	start(), stop()
Store extracted text	TextExtractionResult	addText(string)
Track active states	StateTracker	recordActiveState(name)
Define regions	RegionManager	defineRegion(region)
Record movements	MovementTracker	recordMovement(movement)
Add scene analysis	ActionAnalysis	addSceneAnalysis(analysis)
Track performance	ActionMetrics	recordExecutionTime(ms)
Record history	ExecutionHistory	recordStep(record)

Component Creation

Components are automatically created when accessed through ActionResult:

ActionResult result = new ActionResult();

// Components created on demand
result.add(match);              // Creates MatchCollection
result.addString("text");        // Creates TextExtractionResult  
result.addDefinedRegion(region); // Creates RegionManager
// etc.

Direct Component Access

For advanced operations, access components directly:

// Basic facade usage
result.sortMatchObjects();
List<Match> matches = result.getMatchList();

// Advanced component usage
MatchCollection collection = result.getMatchCollection();
collection.sort(SortStrategy.DISTANCE_FROM_LOCATION);
MatchStatistics stats = collection.getStatistics();
double density = stats.getDensity();

Builder Pattern

Use ActionResultBuilder for clean construction:

ActionResult result = new ActionResultBuilder()
    .withSuccess(true)
    .withMatches(matchList)
    .withTiming(startTime, endTime)
    .withActiveState("MainMenu")
    .withText("Button clicked")
    .build();

Component Interactions

graph TD
    AR[ActionResult Facade]
    MC[MatchCollection]
    MS[MatchStatistics]
    TD[TimingData]
    TER[TextExtractionResult]
    ST[StateTracker]
    RM[RegionManager]
    MT[MovementTracker]
    AA[ActionAnalysis]
    AM[ActionMetrics]
    EH[ExecutionHistory]
    
    AR --> MC
    AR --> TD
    AR --> TER
    AR --> ST
    AR --> RM
    AR --> MT
    AR --> AA
    AR --> AM
    AR --> EH
    MC --> MS
    
    style AR fill:#f9f,stroke:#333,stroke-width:4px
    style MC fill:#bbf,stroke:#333,stroke-width:2px
    style MS fill:#bfb,stroke:#333,stroke-width:2px

Performance Tips

1. Access components once: Store reference if using multiple times
2. Use appropriate methods: Component methods are optimized
3. Leverage statistics: Don't recalculate what's already computed
4. Clear when done: Call clear() on components to free memory
5. Use builders: More efficient than multiple setter calls

Common Patterns

Pattern: Analyze Match Quality

MatchStatistics stats = result.getMatchCollection().getStatistics();
if (stats.getConfidence() == ConfidenceLevel.HIGH) {
    // High confidence in matches
    processMatches(result.getMatchList());
}

Pattern: Track Multi-Phase Timing

TimingData timing = result.getTimingData();
timing.addSegment("search", searchTime);
timing.addSegment("verify", verifyTime);
timing.addSegment("action", actionTime);
logger.info("Performance: {}", timing.format());

Pattern: State-Aware Processing

StateTracker tracker = result.getStateTracker();
if (tracker.isStateActive("ErrorDialog")) {
    handleError(tracker.getMatchesForState("ErrorDialog"));
}

See Also

• ActionResult Architecture - Complete architectural documentation
• ActionResult Migration Guide - Migration from v1.x to v2.0
• ActionConfig Overview - Action configuration documentation