Tripwire Plugin

Tripwire detects tracked-object crossings against configured line segments. This page documents the source contract at RT 2026.2.1. The source has no configuration-descriptor implementation for Tripwire, so configuration must be validated on the target runtime before operational use.

Configuration

Tripwire reads a Tripwires object, keyed by tripwire ID. Each tripwire needs at least two vertices; each vertex is an object with x and y values. The direction accepts Both, Up, or Down case-insensitively.

{
  "Tripwires": {
    "entrance_line": {
      "vertices": [
        {"x": 100, "y": 200},
        {"x": 300, "y": 200}
      ],
      "direction": "Both",
      "cross_bandwidth": 0.015
    }
  }
}

The runtime reads these source-defined heuristic settings from each tripwire. The values below are source defaults, not a substitute for a scene-specific runtime test.

Parameter	Type	Default	Description
cross_bandwidth	float	0.015	Width of the crossing band
cooldown_bandwidth	float	0.0	Width required to leave before another crossing can be registered
cooldown_bandwidth_timeout	float	2.0	Cooldown-bandwidth timeout in seconds
min_halfplane_dwell_sec	float	0.75	Required dwell time on one side of the line
ema_time_constant_sec	float	0.25	Time constant for coordinate smoothing
ema_alpha	float	1.0	Legacy smoothing alternative; when present it disables the time-constant default
net_direction_window_sec	float	1.0	Direction-history window in seconds
crossing_confirmation_delay_sec	float	0.35	Delay before confirming a crossing

The older lowercase tripwires array and keys such as bandwidth, min_crossing_time, max_crossing_time, tailgating_threshold, min_track_hits, and speed_analysis are not the configuration keys read by this release source.

C++ API

TripwireManaged provides these public operations:

expected<std::string> createTripwire(
    std::string const& name,
    std::string const& group,
    std::vector<Point2f> const& shape,
    std::array<float, 4> const& color,
    std::string direction = "Both"
);
expected<void> registerKnownTripwires(bool skipRecalculate = false);
expected<void> processTripwires(
    std::map<std::string, std::vector<Point2f>> const& points,
    cmap const& options = {}
);
expected<cmap> getTripwires(int dictType = DICT_STATE);
expected<void> recalculateTripwire(std::string const& tripwireId);
expected<void> recalculateTripwires();
expected<void> deleteTripwireById(std::string const& tripwireId);
expected<void> resetTripwires();
expected<void> deleteTripwires();

createTripwire persists the generated ID, name, group, vertices, color, and direction under Tripwires. It is safer than manually constructing a configuration when application code already has a Tripwire instance.

Lua API

The Lua binding exposes processTripwires, createTripwire, registerKnownTripwires, getTripwires, resetTripwires, and deleteTripwires. Confirm the generated Lua interface for the exact release before integrating it into a solution script.

Runtime validation

Use an isolated scene with positive and negative crossing controls. Verify a crossing event, direction filtering, cooldown behavior, and the effect of every enabled heuristic. A saved configuration or a visible line alone does not prove an emitted crossing event. See Plugin source and runtime validation for the coverage procedure.