Files

Maik Jurischka a6cf510607 add eHDR controls

2025-12-19 09:12:54 +01:00

18 KiB

Raw Blame History

VizionStreamer Socket Control API

VizionStreamer can be controlled via a Unix Domain Socket interface. This allows external applications to configure camera parameters and stream settings at runtime.

Socket Connection

Socket Path: /tmp/vizion_control.sock
Protocol: Unix Domain Socket (SOCK_STREAM)
Message Format: JSON

Command Format

All commands follow this JSON structure:

{
  "command": "command_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Response Format

All responses follow this JSON structure:

Success Response:

{
  "status": "success",
  "message": "Optional success message"
}

Error Response:

{
  "status": "error",
  "message": "Error description"
}

Available Commands

1. Get Available Formats

Retrieve all supported video formats.

Command:

{
  "command": "get_formats"
}

Response:

{
  "status": "success",
  "formats": [
    {
      "width": 1920,
      "height": 1080,
      "framerate": 30,
      "format": "YUY2"
    },
    {
      "width": 1280,
      "height": 720,
      "framerate": 60,
      "format": "MJPG"
    }
  ]
}

Supported Formats: YUY2, UYVY, NV12, MJPG, BGR, RGB

2. Set Video Format

Change the video format (resolution, framerate, pixel format).

Note: Cannot be changed while streaming is active.

Command:

{
  "command": "set_format",
  "params": {
    "width": "1920",
    "height": "1080",
    "framerate": "30",
    "format": "YUY2"
  }
}

Response:

{
  "status": "success",
  "message": "Format set successfully"
}

3. Start Streaming

Start video streaming from the camera.

Command:

{
  "command": "start_stream"
}

Response:

{
  "status": "success",
  "message": "Streaming started"
}

4. Stop Streaming

Stop video streaming.

Command:

{
  "command": "stop_stream"
}

Response:

{
  "status": "success",
  "message": "Streaming stopped"
}

5. Set GStreamer Pipeline

Configure the GStreamer pipeline for video output. This determines where and how the video stream is processed/displayed.

Note: Cannot be changed while streaming is active.

Command:

{
  "command": "set_pipeline",
  "params": {
    "pipeline": "videoconvert ! x264enc ! rtph264pay ! udpsink host=192.168.1.100 port=5000"
  }
}

Response:

{
  "status": "success",
  "message": "Pipeline set successfully"
}

Common Pipeline Examples:

Display locally:
```
videoconvert ! autovideosink
```

Stream over UDP (H.264):

videoconvert ! x264enc tune=zerolatency ! rtph264pay ! udpsink host=192.168.1.100 port=5000

Stream over RTSP (requires gst-rtsp-server):

videoconvert ! x264enc ! rtph264pay name=pay0

Save to file:

videoconvert ! x264enc ! mp4mux ! filesink location=/tmp/output.mp4

Stream over TCP:

videoconvert ! x264enc ! h264parse ! mpegtsmux ! tcpserversink host=0.0.0.0 port=5000

MJPEG over HTTP:

videoconvert ! jpegenc ! multipartmux ! tcpserversink host=0.0.0.0 port=8080

6. Get Status

Get current streaming status and pipeline configuration.

Command:

{
  "command": "get_status"
}

Response:

{
  "status": "success",
  "streaming": true,
  "pipeline": "videoconvert ! autovideosink"
}

7. Set Exposure

Configure camera exposure settings.

Command:

{
  "command": "set_exposure",
  "params": {
    "mode": "manual",
    "value": "100"
  }
}

Parameters:

mode: "auto" or "manual"
value: Exposure value (only used in manual mode)

Response:

{
  "status": "success",
  "message": "Exposure set successfully"
}

8. Set White Balance

Configure white balance settings.

Command:

{
  "command": "set_whitebalance",
  "params": {
    "mode": "auto",
    "temperature": "4500"
  }
}

Parameters:

mode: "auto" or "manual"
temperature: Color temperature in Kelvin (only used in manual mode)

Response:

{
  "status": "success",
  "message": "White balance set successfully"
}

9. Set Brightness

Adjust camera brightness.

Command:

{
  "command": "set_brightness",
  "params": {
    "value": "50"
  }
}

Response:

{
  "status": "success",
  "message": "Brightness set successfully"
}

10. Set Contrast

Adjust camera contrast.

Command:

{
  "command": "set_contrast",
  "params": {
    "value": "32"
  }
}

Response:

{
  "status": "success",
  "message": "Contrast set successfully"
}

11. Set Saturation

Adjust color saturation.

Command:

{
  "command": "set_saturation",
  "params": {
    "value": "64"
  }
}

Response:

{
  "status": "success",
  "message": "Saturation set successfully"
}

12. Set Sharpness

Adjust image sharpness.

Command:

{
  "command": "set_sharpness",
  "params": {
    "value": "3"
  }
}

Response:

{
  "status": "success",
  "message": "Sharpness set successfully"
}

13. Set Gamma

Adjust gamma correction.

Command:

{
  "command": "set_gamma",
  "params": {
    "value": "100"
  }
}

Response:

{
  "status": "success",
  "message": "Gamma set successfully"
}

14. Set Gain

Adjust camera gain.

Command:

{
  "command": "set_gain",
  "params": {
    "value": "0"
  }
}

Response:

{
  "status": "success",
  "message": "Gain set successfully"
}

15. Set eHDR Mode

Enable or disable eHDR (Enhanced High Dynamic Range) mode.

Note: eHDR features are only available on specific camera models: VCI-AR0821/AR0822, VCS-AR0821/AR0822, VLS3-AR0821/AR0822, VLS-GM2-AR0821/AR0822, and TEVS-AR0821/AR0822.

Command:

{
  "command": "set_ehdr_mode",
  "params": {
    "mode": "0"
  }
}

Parameters:

mode: "0" to enable eHDR, "1" to disable eHDR

Response:

{
  "status": "success",
  "message": "eHDR mode set successfully"
}

16. Set eHDR Exposure Minimum

Set the minimum number of exposure frames for eHDR.

Command:

{
  "command": "set_ehdr_exposure_min",
  "params": {
    "value": "1"
  }
}

Parameters:

value: Minimum exposure frames (range: 1-4, default: 1)

Response:

{
  "status": "success",
  "message": "eHDR exposure min set successfully"
}

17. Set eHDR Exposure Maximum

Set the maximum number of exposure frames for eHDR.

Command:

{
  "command": "set_ehdr_exposure_max",
  "params": {
    "value": "4"
  }
}

Parameters:

value: Maximum exposure frames (range: 1-4, default: 4)

Response:

{
  "status": "success",
  "message": "eHDR exposure max set successfully"
}

18. Set eHDR Ratio Minimum

Set the minimum exposure ratio for eHDR.

Command:

{
  "command": "set_ehdr_ratio_min",
  "params": {
    "value": "12"
  }
}

Parameters:

value: Minimum exposure ratio (range: 1-128, default: 12)

Response:

{
  "status": "success",
  "message": "eHDR ratio min set successfully"
}

19. Set eHDR Ratio Maximum

Set the maximum exposure ratio for eHDR.

Command:

{
  "command": "set_ehdr_ratio_max",
  "params": {
    "value": "24"
  }
}

Parameters:

value: Maximum exposure ratio (range: 1-128, default: 24)

Response:

{
  "status": "success",
  "message": "eHDR ratio max set successfully"
}

20. Get eHDR Status

Retrieve all current eHDR settings.

Command:

{
  "command": "get_ehdr_status"
}

Response:

{
  "status": "success",
  "ehdr_mode": 0,
  "exposure_min": 1,
  "exposure_max": 4,
  "ratio_min": 12,
  "ratio_max": 24
}

Usage Examples

Complete Workflow Example

# 1. Set GStreamer pipeline for UDP streaming
echo '{"command":"set_pipeline","params":{"pipeline":"videoconvert ! x264enc tune=zerolatency ! rtph264pay ! udpsink host=192.168.1.100 port=5000"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# 2. Set video format
echo '{"command":"set_format","params":{"width":"1920","height":"1080","framerate":"30","format":"YUY2"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# 3. Configure camera settings
echo '{"command":"set_exposure","params":{"mode":"auto"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
echo '{"command":"set_brightness","params":{"value":"50"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# 3a. (Optional) Configure eHDR settings (for compatible cameras)
echo '{"command":"set_ehdr_mode","params":{"mode":"0"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
echo '{"command":"set_ehdr_exposure_min","params":{"value":"1"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
echo '{"command":"set_ehdr_exposure_max","params":{"value":"4"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
echo '{"command":"set_ehdr_ratio_min","params":{"value":"12"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
echo '{"command":"set_ehdr_ratio_max","params":{"value":"24"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# 4. Start streaming
echo '{"command":"start_stream"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# 5. Check status
echo '{"command":"get_status"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# 6. Stop streaming when done
echo '{"command":"stop_stream"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

GStreamer Pipeline Examples

# Stream to local display
echo '{"command":"set_pipeline","params":{"pipeline":"videoconvert ! autovideosink"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Stream over UDP (H.264)
echo '{"command":"set_pipeline","params":{"pipeline":"videoconvert ! x264enc tune=zerolatency ! rtph264pay ! udpsink host=192.168.1.100 port=5000"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Save to MP4 file
echo '{"command":"set_pipeline","params":{"pipeline":"videoconvert ! x264enc ! mp4mux ! filesink location=/tmp/output.mp4"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# MJPEG HTTP server
echo '{"command":"set_pipeline","params":{"pipeline":"videoconvert ! jpegenc ! multipartmux ! tcpserversink host=0.0.0.0 port=8080"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

Using `socat`

# Get available formats
echo '{"command":"get_formats"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Set video format
echo '{"command":"set_format","params":{"width":"1920","height":"1080","framerate":"30","format":"YUY2"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Start streaming
echo '{"command":"start_stream"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Set exposure to auto
echo '{"command":"set_exposure","params":{"mode":"auto"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Set brightness
echo '{"command":"set_brightness","params":{"value":"50"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Get status
echo '{"command":"get_status"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Stop streaming
echo '{"command":"stop_stream"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

eHDR Control Examples

# Enable eHDR mode
echo '{"command":"set_ehdr_mode","params":{"mode":"0"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Disable eHDR mode
echo '{"command":"set_ehdr_mode","params":{"mode":"1"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Configure eHDR exposure range
echo '{"command":"set_ehdr_exposure_min","params":{"value":"1"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
echo '{"command":"set_ehdr_exposure_max","params":{"value":"4"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Configure eHDR ratio range
echo '{"command":"set_ehdr_ratio_min","params":{"value":"12"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
echo '{"command":"set_ehdr_ratio_max","params":{"value":"24"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

# Get current eHDR settings
echo '{"command":"get_ehdr_status"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock

Using `nc` (netcat with Unix socket support)

echo '{"command":"get_formats"}' | nc -U /tmp/vizion_control.sock

Using Python

import socket
import json

def send_command(command, params=None):
    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect('/tmp/vizion_control.sock')

    cmd = {"command": command}
    if params:
        cmd["params"] = params

    sock.send(json.dumps(cmd).encode())
    response = sock.recv(4096).decode()
    sock.close()

    return json.loads(response)

# Examples
print(send_command("get_formats"))
print(send_command("set_format", {
    "width": "1920",
    "height": "1080",
    "framerate": "30",
    "format": "YUY2"
}))
print(send_command("set_exposure", {"mode": "auto"}))
print(send_command("start_stream"))

# eHDR control examples (for compatible cameras)
print(send_command("set_ehdr_mode", {"mode": "0"}))  # Enable eHDR
print(send_command("set_ehdr_exposure_min", {"value": "1"}))
print(send_command("set_ehdr_exposure_max", {"value": "4"}))
print(send_command("set_ehdr_ratio_min", {"value": "12"}))
print(send_command("set_ehdr_ratio_max", {"value": "24"}))
print(send_command("get_ehdr_status"))  # Get current eHDR settings

Using C++

#include <sys/socket.h>
#include <sys/un.h>
#include <unistd.h>
#include <string>
#include <iostream>

std::string sendCommand(const std::string& command) {
    int sock = socket(AF_UNIX, SOCK_STREAM, 0);

    struct sockaddr_un addr;
    memset(&addr, 0, sizeof(addr));
    addr.sun_family = AF_UNIX;
    strcpy(addr.sun_path, "/tmp/vizion_control.sock");

    connect(sock, (struct sockaddr*)&addr, sizeof(addr));
    send(sock, command.c_str(), command.length(), 0);

    char buffer[4096];
    int bytesRead = recv(sock, buffer, sizeof(buffer) - 1, 0);
    buffer[bytesRead] = '\0';

    close(sock);
    return std::string(buffer);
}

// Example usage
int main() {
    std::cout << sendCommand(R"({"command":"get_formats"})") << std::endl;
    std::cout << sendCommand(R"({"command":"set_brightness","params":{"value":"50"}})") << std::endl;

    // eHDR control examples (for compatible cameras)
    std::cout << sendCommand(R"({"command":"set_ehdr_mode","params":{"mode":"0"}})") << std::endl;
    std::cout << sendCommand(R"({"command":"set_ehdr_exposure_min","params":{"value":"1"}})") << std::endl;
    std::cout << sendCommand(R"({"command":"set_ehdr_exposure_max","params":{"value":"4"}})") << std::endl;
    std::cout << sendCommand(R"({"command":"get_ehdr_status"})") << std::endl;

    return 0;
}

Parameter Value Ranges

The valid ranges for camera parameters depend on the specific camera model. You can query the camera capabilities through the VizionSDK API or experimentally determine valid ranges.

Typical ranges (camera-dependent):

Brightness: 0-255
Contrast: 0-255
Saturation: 0-255
Sharpness: 0-255
Gamma: 72-500
Gain: 0-100
Exposure: 1-10000 (in auto mode, value is ignored)
White Balance Temperature: 2800-6500 Kelvin

eHDR ranges (for compatible cameras only):

eHDR Mode: 0 (enable) or 1 (disable)
eHDR Exposure Min: 1-4 (default: 1)
eHDR Exposure Max: 1-4 (default: 4)
eHDR Ratio Min: 1-128 (default: 12)
eHDR Ratio Max: 1-128 (default: 24)

Compatible eHDR Camera Models:

VCI-AR0821/AR0822
VCS-AR0821/AR0822
VLS3-AR0821/AR0822
VLS-GM2-AR0821/AR0822
TEVS-AR0821/AR0822

Error Handling

Always check the status field in the response:

response = send_command("set_format", {...})
if response["status"] == "error":
    print(f"Command failed: {response['message']}")
else:
    print("Command successful")

Thread Safety

The socket server handles one client connection at a time. Commands are processed sequentially with mutex protection to ensure thread safety with the camera operations.

GStreamer Integration

VizionStreamer uses GStreamer for video processing and output. The captured frames from the VizionSDK camera are continuously fed into a GStreamer pipeline in a separate acquisition thread.

How It Works

Continuous Acquisition Loop: A dedicated thread continuously captures frames from the camera using VxGetImage()
Frame Buffering: Captured frames are pushed into the GStreamer pipeline via appsrc
Pipeline Processing: GStreamer processes the frames according to the configured pipeline
Output: Frames are displayed, saved, or streamed based on the pipeline configuration

Performance Monitoring

The acquisition loop prints FPS statistics every second:

FPS: 30 | Total frames: 1234 | Frame size: 4147200 bytes

Receiving UDP Stream

If you configured a UDP streaming pipeline, receive it with:

# Using GStreamer
gst-launch-1.0 udpsrc port=5000 ! application/x-rtp,encoding-name=H264 ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! autovideosink

# Using FFplay
ffplay -fflags nobuffer -flags low_delay -framedrop udp://0.0.0.0:5000

# Using VLC
vlc udp://@:5000

Receiving MJPEG HTTP Stream

If you configured an MJPEG HTTP server pipeline:

# View in browser
firefox http://192.168.1.100:8080

# Using FFplay
ffplay http://192.168.1.100:8080

# Using curl to save frames
curl http://192.168.1.100:8080 > stream.mjpg

Notes

The socket file is automatically created when VizionStreamer starts
The socket file is removed when VizionStreamer exits cleanly
Format and pipeline changes require streaming to be stopped first
The acquisition loop runs continuously while streaming is active
Some parameters may not be supported on all camera models
Invalid parameter values will return an error response
GStreamer pipeline errors will be reported when starting the stream
Default pipeline: videoconvert ! autovideosink (display locally)
eHDR features require compatible camera models (VCI/VCS/VLS3/VLS-GM2/TEVS-AR0821/AR0822)
eHDR settings may be reset to defaults when the camera starts streaming (driver behavior)

18 KiB Raw Blame History

VizionStreamer Socket Control API

Socket Connection

Command Format

Response Format

Available Commands

1. Get Available Formats

2. Set Video Format

3. Start Streaming

4. Stop Streaming

5. Set GStreamer Pipeline

6. Get Status

7. Set Exposure

8. Set White Balance

9. Set Brightness

10. Set Contrast

11. Set Saturation

12. Set Sharpness

13. Set Gamma

14. Set Gain

15. Set eHDR Mode

16. Set eHDR Exposure Minimum

17. Set eHDR Exposure Maximum

18. Set eHDR Ratio Minimum

19. Set eHDR Ratio Maximum

20. Get eHDR Status

Usage Examples

Complete Workflow Example

GStreamer Pipeline Examples

Using socat

eHDR Control Examples

Using nc (netcat with Unix socket support)

Using Python

Using C++

Parameter Value Ranges

Error Handling

Thread Safety

GStreamer Integration

How It Works

Performance Monitoring

Receiving UDP Stream

Receiving MJPEG HTTP Stream

Notes

18 KiB

Raw Blame History

Using `socat`

Using `nc` (netcat with Unix socket support)