Camera Integration

Turqoa ingests live video streams from IP cameras deployed across gate lanes, perimeter zones, and terminal areas. Camera feeds provide the raw visual data that powers OCR, damage detection, intrusion detection, and container identification.

Camera Requirements

All cameras integrated with Turqoa must meet the following baseline specifications:

Attribute	Gate Lane Cameras	Perimeter Cameras	Yard Cameras
Minimum resolution	4 MP (2688 x 1520)	2 MP (1920 x 1080)	2 MP (1920 x 1080)
Recommended resolution	8 MP (3840 x 2160)	4 MP (2688 x 1520)	4 MP (2688 x 1520)
Minimum framerate	15 fps	10 fps	10 fps
Recommended framerate	25 fps	15 fps	15 fps
Lens type	Fixed or varifocal	Varifocal or PTZ	PTZ
Protocol	ONVIF Profile S + T	ONVIF Profile S	ONVIF Profile S
Compression	H.264 / H.265	H.264 / H.265	H.264 / H.265

ONVIF Protocol Setup

Turqoa discovers and manages cameras through the ONVIF protocol. Ensure ONVIF is enabled on each camera before configuration.

Enabling ONVIF on the Camera

Access the camera's web interface.
Navigate to Network > Advanced > Integration Protocol.
Enable ONVIF and set a dedicated ONVIF user with Media and PTZ privileges.
Note the ONVIF service port (default: 80 or 8080).

Registering a Camera in Turqoa

# camera-config.yaml
cameras:
  - id: gate-lane-01-left
    name: "Gate Lane 1 - Left Side"
    type: gate
    onvif:
      host: 192.168.10.101
      port: 80
      username: ${CAM_ONVIF_USER}
      password: ${CAM_ONVIF_PASS}
    stream:
      profile: main
      codec: h265
      resolution: 3840x2160
      fps: 25
    zone: gate-lane-01
    position: left

Auto-Discovery

Turqoa can discover ONVIF cameras on the local network automatically:

turqoa cameras discover --subnet 192.168.10.0/24

This scans the subnet for ONVIF-compliant devices and outputs their IP, model, and firmware version.

RTSP Stream Configuration

Each camera exposes one or more RTSP streams. Turqoa connects to the main stream for AI processing and optionally to a sub-stream for live monitoring.

rtsp://<camera-ip>:<port>/Streaming/Channels/101   # Main stream (high-res)
rtsp://<camera-ip>:<port>/Streaming/Channels/102   # Sub stream (low-res)

Stream Parameters

Parameter	Main Stream (AI)	Sub Stream (Monitoring)
Resolution	Full (4K / 4MP)	720p or 1080p
Framerate	25 fps	10 fps
Bitrate	8-16 Mbps	1-2 Mbps
Codec	H.265 (preferred)	H.264
GOP size	25-50 frames	20-30 frames

Multi-Camera Network

A typical gate lane uses 4-6 cameras to capture all required angles:

Position	Purpose	Count per Lane
Front	License plate, driver face	1
Left side	Container number, damage, chassis	1
Right side	Container number, damage, chassis	1
Top	Container top, seal, ISO code	1
Rear	Rear container number, hazmat placard	1 (optional)
Overview	Full lane context	1 (optional)

Network Design

Dedicate a separate VLAN for camera traffic to isolate bandwidth from business network traffic.
Use PoE+ switches (IEEE 802.3at) capable of delivering 30W per port for powered cameras.
Ensure minimum 1 Gbps uplink from camera switches to the Turqoa processing server.
Calculate bandwidth per lane: 6 cameras x 12 Mbps average = 72 Mbps per gate lane.

Night Vision and IR Considerations

Gate operations run 24/7. Cameras must perform reliably in low-light and complete darkness.

IR illumination --- Use cameras with built-in IR LEDs rated for at least 30m range. Gate lane cameras should have 50m+ IR range.
IR cut filter --- Ensure the camera has an automatic IR cut filter that switches between day and night modes.
Supplemental lighting --- For OCR accuracy, install dedicated LED illuminators at gate lanes. White light at 200+ lux ensures consistent character recognition.
WDR (Wide Dynamic Range) --- Required for gate lanes where headlights and shadows create extreme contrast. 120 dB WDR minimum recommended.

Note: AI model accuracy for OCR and damage detection drops measurably below 100 lux without supplemental lighting. Always validate detection accuracy during nighttime commissioning.