Continuous Frame Acquisition: Dedicated thread for frame capture from VizionSDK
GStreamer Integration: Flexible video processing and output
Socket Control API: Runtime configuration via JSON commands over Unix Domain Socket
Camera Parameter Control: Exposure, white balance, brightness, contrast, etc.
Multiple Output Options: Display, UDP/TCP streaming, file recording, RTSP, MJPEG
Performance Monitoring: Real-time FPS statistics
Thread-Safe: Mutex-protected operations

Quick Start

Build

cmake -B build -S .
cmake --build build

Run

# Start VizionStreamer
./build/vizionStreamer

Start Streaming (Default Pipeline)

In another terminal:

# Start streaming with default pipeline (local display)
./scripts/start_stream.sh

# Stop streaming
./scripts/stop_stream.sh

That's it! The default pipeline videoconvert ! autovideosink is already configured.

Architecture

┌─────────────────┐
│  VizionSDK      │
│  Camera         │
└────────┬────────┘
         │ VxGetImage()
         ▼
┌─────────────────┐
│  Acquisition    │
│  Loop Thread    │  (StreamingEngine)
└────────┬────────┘
         │ Push frames
         ▼
┌─────────────────┐
│  GStreamer      │
│  Pipeline       │  (appsrc → processing → output)
└────────┬────────┘
         │
         ▼
    Display/Stream/File

┌─────────────────┐
│  Socket Server  │  ← JSON commands
│  (Control API)  │
└─────────────────┘

Control Scripts

Located in scripts/ directory:

Script	Description
`start_stream.sh`	Start streaming (use default or configured pipeline)
`stop_stream.sh`	Stop streaming
`get_status.sh`	Show streaming status and current pipeline
`get_formats.sh`	List available camera formats
`set_pipeline_display.sh`	Set pipeline for local display
`set_pipeline_udp.sh [host] [port]`	Set pipeline for UDP streaming
`set_pipeline_file.sh [path]`	Set pipeline for file recording
`set_pipeline_mjpeg.sh [port]`	Set pipeline for MJPEG HTTP streaming

See scripts/README.md for detailed usage.

Common Use Cases

Local Display

./build/vizionStreamer
# In another terminal:
./scripts/start_stream.sh

UDP Streaming to Remote Host

./build/vizionStreamer
# In another terminal:
./scripts/set_pipeline_udp.sh 192.168.1.100 5000
./scripts/start_stream.sh

# On receiving machine:
gst-launch-1.0 udpsrc port=5000 ! application/x-rtp,encoding-name=H264 ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! autovideosink

Record to File

./build/vizionStreamer
# In another terminal:
./scripts/set_pipeline_file.sh /tmp/recording.mp4
./scripts/start_stream.sh
# Let it run, then:
./scripts/stop_stream.sh

MJPEG HTTP Streaming

./build/vizionStreamer
# In another terminal:
./scripts/set_pipeline_mjpeg.sh 8080
./scripts/start_stream.sh

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

Socket Control API

Full API documentation: SOCKET_API.md

Socket Path: /tmp/vizion_control.sock

Available Commands

get_formats - List camera formats
set_format - Change resolution/framerate/format
start_stream - Start streaming
stop_stream - Stop streaming
get_status - Get streaming status
set_pipeline - Configure GStreamer pipeline
set_exposure - Configure exposure
set_whitebalance - Configure white balance
set_brightness - Adjust brightness
set_contrast - Adjust contrast
set_saturation - Adjust saturation
set_sharpness - Adjust sharpness
set_gamma - Adjust gamma
set_gain - Adjust gain
set_ehdr_mode - Enable/disable eHDR (compatible cameras only)
set_ehdr_exposure_min - Set eHDR minimum exposure frames
set_ehdr_exposure_max - Set eHDR maximum exposure frames
set_ehdr_ratio_min - Set eHDR minimum exposure ratio
set_ehdr_ratio_max - Set eHDR maximum exposure ratio
get_ehdr_status - Get current eHDR settings

Example

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

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

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

GStreamer Pipeline Examples

Display

videoconvert ! autovideosink

UDP H.264 Streaming

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

File Recording

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

TCP Streaming

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

MJPEG HTTP

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

Tee (Display + Record)

tee name=t ! queue ! videoconvert ! autovideosink t. ! queue ! x264enc ! mp4mux ! filesink location=out.mp4

Dependencies

VizionSDK: Camera interface (located at /opt/vizionsdk)
GStreamer 1.0: Video processing (gstreamer-1.0, gstreamer-app-1.0)
CMake: Build system (>= 3.20)
C++23: Compiler support
socat: For socket communication (control scripts)

Install Dependencies (Debian/Ubuntu)

sudo apt install build-essential cmake pkg-config socat \
    libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly gstreamer1.0-x

Project Structure

vizionStreamer/
├── main.cpp                    # Main application
├── SocketServer.{h,cpp}        # Unix domain socket server
├── CameraController.{h,cpp}    # Command processing & camera control
├── StreamingEngine.{h,cpp}     # Acquisition loop & streaming
├── GStreamerPipeline.{h,cpp}   # GStreamer pipeline wrapper
├── CMakeLists.txt              # Build configuration
├── config/
│   └── VxConfig.conf           # VizionSDK configuration
├── scripts/                    # Control scripts
│   ├── README.md
│   ├── start_stream.sh
│   ├── stop_stream.sh
│   ├── get_status.sh
│   ├── set_pipeline_*.sh
│   └── get_formats.sh
├── SOCKET_API.md               # Complete API documentation
└── README.md                   # This file

Configuration Files

VxConfig.conf

Automatically copied to build directory during build. Contains VizionSDK camera configuration.

Performance

The acquisition loop displays statistics every second:

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

Typical performance:

Local Display: 30 FPS @ 1080p
UDP Streaming: 30 FPS @ 1080p with H.264 encoding
File Recording: Limited by disk I/O

Troubleshooting

No cameras found

Check camera connection
Run /opt/vizionsdk/init_driver.sh if needed
Check dmesg for USB errors

Pipeline fails to start

Verify GStreamer plugins are installed
Test pipeline manually: gst-launch-1.0 videotestsrc ! YOUR_PIPELINE
Check pipeline syntax

Socket connection refused

Ensure VizionStreamer is running
Check socket exists: ls -l /tmp/vizion_control.sock
Verify permissions

Low FPS

Reduce resolution or framerate
Use hardware encoding if available (vaapih264enc instead of x264enc)
Check CPU usage

License

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0).

You are free to:

Share — copy and redistribute the material in any medium or format
Adapt — remix, transform, and build upon the material

Under the following terms:

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
NonCommercial — You may not use the material for commercial purposes.
ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

Full license text: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode

Disclaimer

This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

Third-Party Dependencies

This software uses the following dependencies:

VizionSDK - See VizionSDK license terms at /opt/vizionsdk/
GStreamer - Licensed under LGPL

Support

For issues and questions, refer to:

SOCKET_API.md - Complete API reference
scripts/README.md - Script usage guide
VizionSDK documentation at /opt/vizionsdk/