Record Class TrajectoryData

java.lang.Object
java.lang.Record
cloud.opencode.base.captcha.security.TrajectoryData
Record Components:
points - the coordinate sequence | 坐标序列
timestamps - the corresponding timestamps in milliseconds | 对应时间戳（毫秒）
totalDurationMs - the total duration in milliseconds | 总耗时（毫秒）
public record TrajectoryData(List<TrajectoryData.Point> points, List<Long> timestamps, long totalDurationMs) extends Record
Trajectory Data — Records user interaction coordinate and timestamp sequences 轨迹数据 — 记录用户交互的坐标和时间戳序列

This record captures the full trajectory of a user's mouse or touch interaction, including coordinate points and their corresponding timestamps. It provides derived metrics such as speed, acceleration, direction changes, and jitter for bot detection.

此记录捕获用户鼠标或触摸交互的完整轨迹，包括坐标点及其对应的时间戳。 它提供派生指标，如速度、加速度、方向变化和抖动，用于机器人检测。

Features | 主要功能:

  • Immutable trajectory storage with defensive copies - 不可变轨迹存储（防御性拷贝）
  • Speed and acceleration calculation - 速度和加速度计算
  • Direction change detection - 方向变化检测
  • Jitter standard deviation measurement - 抖动标准差测量

Usage Examples | 使用示例:

List<TrajectoryData.Point> points = List.of(
    new TrajectoryData.Point(0, 0),
    new TrajectoryData.Point(10, 5),
    new TrajectoryData.Point(20, 8),
    new TrajectoryData.Point(30, 10)
);
List<Long> timestamps = List.of(0L, 100L, 200L, 300L);
TrajectoryData data = new TrajectoryData(points, timestamps, 300L);

List<Double> speeds = data.speeds();
double jitter = data.jitterStdDev();
int changes = data.directionChanges();

Security | 安全性:

  • Thread-safe: Yes (immutable record with defensive copies) - 线程安全: 是（不可变记录，防御性拷贝）
  • Null-safe: No (points and timestamps must not be null) - 空值安全: 否（点和时间戳不能为null）

Performance | 性能:

  • Construction: O(n) for defensive copy - 构造: O(n) 防御性拷贝
  • Speed/acceleration: O(n) per call - 速度/加速度: 每次调用 O(n)
  • Direction changes: O(n) per call - 方向变化: 每次调用 O(n)
  • Jitter: O(n) per call - 抖动: 每次调用 O(n)
Since:
JDK 25, opencode-base-captcha V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • TrajectoryData

      public TrajectoryData(List<TrajectoryData.Point> points, List<Long> timestamps, long totalDurationMs)
      Compact constructor with validation and defensive copies. 紧凑构造器，包含验证和防御性拷贝。
      Throws:
      NullPointerException - if points or timestamps is null | 如果 points 或 timestamps 为 null
      IllegalArgumentException - if sizes mismatch, fewer than 2 points, or totalDurationMs is negative | 如果大小不匹配、少于 2 个点或 totalDurationMs 为负数

  • Method Details

    • speeds

      public List<Double> speeds()
      Calculates speed sequence between consecutive points. 计算相邻点之间的速度序列。

      Speed is computed as Euclidean distance divided by time difference. If the time difference between two consecutive points is zero, the speed is reported as 0.

      速度计算为欧几里得距离除以时间差。如果两个连续点之间的时间差为零，则速度报告为 0。

      Returns:
      speeds in pixels per millisecond, with size = points.size() - 1 | 以像素/毫秒为单位的速度列表，大小 = points.size() - 1

    • accelerations

      public List<Double> accelerations()
      Calculates acceleration sequence from the speed sequence. 从速度序列计算加速度序列。

      Acceleration is computed as the change in speed divided by the time difference between the midpoints of the corresponding speed intervals. If the time difference is zero, the acceleration is reported as 0.

      加速度计算为速度变化除以对应速度区间中点之间的时间差。 如果时间差为零，则加速度报告为 0。

      Returns:
      accelerations, with size = points.size() - 2 | 加速度列表，大小 = points.size() - 2

    • directionChanges

      public int directionChanges()
      Counts direction changes in the trajectory. 计算轨迹中的方向变化次数。

      A direction change is counted when the angle between two consecutive movement vectors exceeds 15 degrees.

      当两个连续运动向量之间的角度超过 15 度时，计为一次方向变化。

      Returns:
      number of direction changes | 方向变化次数

    • jitterStdDev

      public double jitterStdDev()
      Calculates jitter standard deviation perpendicular to the main movement direction. 计算垂直于主运动方向的抖动标准差。

      The main movement direction is defined as the line from the first point to the last point. The jitter is the standard deviation of the perpendicular distances from all points to this line.

      主运动方向定义为从第一个点到最后一个点的连线。 抖动是所有点到此连线的垂直距离的标准差。

      Returns:
      jitter standard deviation in pixels | 抖动标准差（像素）

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • points

      public List<TrajectoryData.Point> points()
      Returns the value of the points record component.
      Returns:
      the value of the points record component

    • timestamps

      public List<Long> timestamps()
      Returns the value of the timestamps record component.
      Returns:
      the value of the timestamps record component

    • totalDurationMs

      public long totalDurationMs()
      Returns the value of the totalDurationMs record component.
      Returns:
      the value of the totalDurationMs record component