Detection Rules

Detection rules define what Terminal Security looks for within each zone. Turqoa provides a library of built-in detection types that can be configured, tuned, and combined to match your terminal's specific security requirements.

Detection Types

Perimeter Breach

Detects unauthorized crossing of a defined boundary. Uses virtual tripwire technology drawn over camera views to identify direction-aware boundary crossings.

detection_rules:
  - type: perimeter_breach
    config:
      direction: inbound          # inbound, outbound, both
      min_object_size: 0.02       # Minimum detection size (fraction of frame)
      object_types:
        - person
        - vehicle
      ignore_zones:               # Areas within the tripwire to ignore
        - gate_entrance            # Legitimate entry point
      sensitivity: 0.8

Parameter	Range	Default	Description
`direction`	inbound/outbound/both	both	Which crossing direction triggers alert
`min_object_size`	0.01–0.50	0.02	Minimum object size relative to frame
`sensitivity`	0.1–1.0	0.8	Detection sensitivity (higher = more sensitive)
`debounce_ms`	0–5000	1000	Time before re-triggering for same object

Loitering

Detects individuals or vehicles remaining in an area longer than a defined threshold. The system tracks object presence over time using re-identification across frames.

detection_rules:
  - type: loitering
    config:
      object_types:
        - person
      time_threshold: 300s        # 5 minutes
      area:
        type: full_zone           # full_zone or custom_region
      alert_on_exceed: true
      track_re_entry: true        # Re-entering within cooldown continues timer
      re_entry_cooldown: 600s

Unattended Object

Detects objects (bags, packages, containers) left unattended in a zone for longer than a threshold. Uses background subtraction combined with object classification.

detection_rules:
  - type: unattended_object
    config:
      time_threshold: 120s
      min_object_size: 0.01
      max_object_size: 0.30       # Ignore large objects (vehicles, containers)
      exclude_types:
        - vehicle
        - container
      sensitivity: 0.7

Note: The unattended object detector requires a stable camera view. PTZ cameras must be locked to a preset position for this detection type to function reliably.

Crowd Formation

Detects unusual gatherings of people that exceed normal density thresholds for an area. Uses person counting and density estimation.

detection_rules:
  - type: crowd_formation
    config:
      person_threshold: 10        # Alert when > 10 people detected
      density_threshold: 0.5      # People per square meter
      sustained_duration: 60s     # Must persist for 60 seconds
      baseline_learning: true     # Learn normal patterns over time
      baseline_period: 7d

Unauthorized Vehicle

Detects vehicles in areas where they are not permitted, or vehicles that do not match an authorized list.

detection_rules:
  - type: unauthorized_vehicle
    config:
      vehicle_types:
        - car
        - motorcycle
      allowed_vehicle_types:
        - forklift
        - straddle_carrier
        - terminal_truck
      use_plate_allowlist: true
      allowlist_source: tos        # Check against TOS vehicle registry

PPE Compliance

Detects personnel not wearing required personal protective equipment in designated areas.

detection_rules:
  - type: ppe_compliance
    config:
      required_ppe:
        - hard_hat
        - high_visibility_vest
      detection_confidence: 0.75
      grace_period: 10s           # Allow brief non-compliance (e.g., adjusting hat)
      alert_priority: medium

Rule Configuration

Rule Priorities

When multiple detection rules are active in a zone, their alerts are prioritized:

zones:
  - id: zone-yard-block-a
    detection_rules:
      - type: perimeter_breach
        priority: critical
      - type: unauthorized_vehicle
        priority: high
      - type: loitering
        priority: medium
      - type: ppe_compliance
        priority: low

Rule Combinations

Rules can be combined with logical operators to create compound detection conditions:

compound_rules:
  - name: suspicious_after_hours_activity
    operator: all                  # All conditions must trigger
    rules:
      - type: loitering
        config:
          time_threshold: 120s
      - type: schedule_check
        config:
          time: after_hours
    action:
      alert_priority: critical
      notify: security_team

Sensitivity Tuning

Sensitivity settings control the trade-off between detection rate and false positive rate. Each detection type has a sensitivity parameter ranging from 0.1 (least sensitive) to 1.0 (most sensitive).

Recommended Starting Points

Detection Type	Indoor	Outdoor (Day)	Outdoor (Night)
Perimeter breach	0.8	0.7	0.6
Loitering	0.7	0.6	0.5
Unattended object	0.7	0.6	0.5
Crowd formation	0.8	0.7	0.6
PPE compliance	0.8	0.7	N/A

Note: Night sensitivity is typically set lower due to reduced image quality. Using IR or thermal cameras allows night sensitivity to match daytime levels.

Auto-Tuning

Turqoa can automatically adjust sensitivity based on false positive feedback:

turqoa security tune \
  --site "my-terminal" \
  --zone zone-yard-block-a \
  --period 14d \
  --target-fps 2.0    # Target: fewer than 2 false positives per day

The auto-tuner analyzes operator dismissals and acknowledged alerts over the specified period to recommend optimal sensitivity levels.

False Positive Management

False positives are inevitable in video analytics. Turqoa provides several mechanisms to minimize and manage them:

Exclusion Zones

Define areas within a camera view where detections should be ignored (e.g., a flag blowing in the wind, a rotating sign):

cameras:
  - id: cam-perimeter-east
    exclusion_zones:
      - name: "Flagpole area"
        polygon: [[100, 50], [150, 50], [150, 200], [100, 200]]
      - name: "Road outside fence"
        polygon: [[0, 400], [640, 400], [640, 480], [0, 480]]

Environmental Filters

Suppress detections caused by environmental conditions:

detection_rules:
  - type: perimeter_breach
    config:
      environmental_filters:
        wind_compensation: true
        rain_compensation: true
        shadow_suppression: true
        reflection_suppression: true

Feedback Loop

Operators can mark alerts as false positives in the Command Center. These labels feed back into the detection system:

Operator dismisses an alert and selects "False Positive"
The system records the image, detection parameters, and environmental conditions
Over time, the feedback data is used to refine detection models and sensitivity settings

# View false positive statistics
turqoa security fp-stats --site "my-terminal" --period 30d

Custom Detection Rules

For scenarios not covered by built-in detection types, Turqoa supports custom rules using the detection scripting API:

custom_rules:
  - name: forklift_speed_violation
    description: "Detect forklifts exceeding speed limit in pedestrian zone"
    trigger: object_tracked
    condition: |
      object.type == "forklift" and
      object.speed_estimate > 15 and
      object.zone == "pedestrian_corridor"
    action:
      alert_priority: high
      notify: safety_officer
      record_clip: 30s

Warning: Custom detection rules that involve speed estimation require cameras with known calibration parameters (focal length, mounting height, angle). Use turqoa security calibrate-camera to set these values before deploying speed-based rules.