Class TrajectoryAnalyzer

java.lang.Object
cloud.opencode.base.captcha.security.TrajectoryAnalyzer
public final class TrajectoryAnalyzer extends Object
Trajectory Analyzer — Analyzes user interaction trajectories for bot detection 轨迹分析器 — 分析用户交互轨迹以检测机器人

This class examines trajectory data (coordinate points, timestamps) to distinguish human interactions from automated bot behavior. It uses multiple heuristics including speed variance, jitter analysis, and direction change counting.

此类检查轨迹数据（坐标点、时间戳）以区分人类交互和自动化机器人行为。 它使用多种启发式方法，包括速度方差、抖动分析和方向变化计数。

Features | 主要功能:

  • Speed variance analysis - 速度方差分析
  • Micro-jitter detection - 微抖动检测
  • Direction change counting - 方向变化计数
  • Completion time validation - 完成时间验证

Usage Examples | 使用示例:

TrajectoryAnalyzer analyzer = new TrajectoryAnalyzer();
TrajectoryData data = new TrajectoryData(points, timestamps, 1500L);
TrajectoryResult result = analyzer.analyze(data);
if (result != TrajectoryResult.HUMAN) {
    // Reject as bot
}

Security | 安全性:

  • Thread-safe: Yes (stateless, no mutable fields) - 线程安全: 是（无状态，无可变字段）
  • Null-safe: No (data must not be null) - 空值安全: 否（数据不能为null）

Performance | 性能:

  • Analysis: O(n) where n is the number of trajectory points - 分析: O(n)，n 为轨迹点数
Since:
JDK 25, opencode-base-captcha V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • TrajectoryAnalyzer

      public TrajectoryAnalyzer()

  • Method Details

    • analyze

      public TrajectoryAnalyzer.TrajectoryResult analyze(TrajectoryData data)
      Analyzes trajectory data and returns a result indicating whether the trajectory appears human or bot-like. 分析轨迹数据并返回结果，指示轨迹是否看起来像人类或机器人。

      The analysis proceeds through the following checks in order:

      分析按以下顺序进行检查：

      1. Insufficient data check (fewer than 5 points)
      2. Too-fast completion check (less than 200L ms)
      3. Constant speed detection (speed variance / mean < 0.1)
      4. No-jitter detection (jitter std dev < 0.5 pixels)
      5. Linear trajectory detection (fewer than 2 direction changes)
      Parameters:
      data - the trajectory data to analyze | 要分析的轨迹数据
      Returns:
      the analysis result | 分析结果
      Throws:
      NullPointerException - if data is null | 如果 data 为 null