vizionStreamer/README.md

# VizionStreamer

High-performance video streaming application for Technexion cameras with GStreamer integration and Unix Domain Socket control interface.

Depends on: https://github.com/TechNexion-Vision/vizionsdk

## Features

- **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

```bash
cmake -B build -S .
cmake --build build
```

### Run

```bash
# Start VizionStreamer
./build/vizionStreamer
```

### Start Streaming (Default Pipeline)

In another terminal:

```bash
# 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](scripts/README.md) for detailed usage.

## Common Use Cases

### Local Display
```bash
./build/vizionStreamer
# In another terminal:
./scripts/start_stream.sh
```

### UDP Streaming to Remote Host
```bash
./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
```bash
./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
```bash
./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_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

```bash
# 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)

```bash
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

**VizionStreamer**
Copyright (c) 2025 Maik Jurischka

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**
  Copyright (c) 2025 TechNexion Ltd.
  Licensed under MIT License
  https://github.com/TechNexion-Vision/vizionsdk/blob/main/LICENSE

- **GStreamer**
  Licensed under LGPL
  https://gstreamer.freedesktop.org/

## Support

For issues and questions, refer to:
- [SOCKET_API.md](SOCKET_API.md) - Complete API reference
- [scripts/README.md](scripts/README.md) - Script usage guide
- VizionSDK documentation at `/opt/vizionsdk/`