Skip to content

Commit c17a9b4

Browse files
larsllbjsowa
larsll
and
bjsowa
authored
Update README (#180)
* Updated README * Fix typo * Add correct branch for ROS1 * Add bash-syntax to installation command * Updated build instruction Co-authored-by: Błażej Sowa <[email protected]>
1 parent 95f9b70 commit c17a9b4

File tree

1 file changed

+176
-9
lines changed

1 file changed

+176
-9
lines changed

‎README.md‎

Lines changed: 176 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,184 @@
1-
web_video_server [![Build Status](https://api.travis-ci.org/RobotWebTools/web_video_server.png)](https://travis-ci.org/RobotWebTools/web_video_server)
2-
================
1+
# web_video_server - HTTP Streaming of ROS Image Topics in Multiple Formats
32

4-
#### HTTP Streaming of ROS Image Topics in Multiple Formats
5-
This node combines the capabilities of [ros_web_video](https://github.com/RobotWebTools/ros_web_video) and [mjpeg_server](https://github.com/RobotWebTools/mjpeg_server) into a single node.
3+
This node provides HTTP streaming of ROS image topics in various formats, making it easy to view robot camera feeds and other image topics in a web browser without requiring special plugins or extensions.
64

7-
For full documentation, see [the ROS wiki](http://ros.org/wiki/web_video_server).
5+
## Features
86

9-
[Doxygen](http://docs.ros.org/indigo/api/web_video_server/html/) files can be found on the ROS wiki.
7+
- Stream ROS image topics over HTTP in multiple formats:
8+
- MJPEG (Motion JPEG)
9+
- VP8 (WebM)
10+
- VP9 (WebM)
11+
- H264 (MP4)
12+
- PNG streams
13+
- ROS compressed image topics
14+
- Adjustable quality, size, and other streaming parameters
15+
- Web interface to browse available image topics
16+
- Single image snapshot capability
17+
- Support for different QoS profiles in ROS 2
1018

11-
This project is released as part of the [Robot Web Tools](http://robotwebtools.org/) effort.
19+
## Installation
1220

13-
### License
21+
### Dependencies
22+
23+
- ROS (Noetic) or ROS 2 (Humble+)
24+
- OpenCV
25+
- FFmpeg/libav
26+
- Boost
27+
- async_web_server_cpp
28+
29+
### Installing packages
30+
31+
For newer ROS2 distributions (humble, jazzy, rolling) it is possible to install web_video_server as a package:
32+
33+
```
34+
sudo apt install ros-${ROS_DISTRO}-web-video-server
35+
```
36+
37+
### Building from Source
38+
39+
Create a ROS workspace if you don't have one:
40+
```bash
41+
mkdir -p ~/ros_ws/src
42+
cd ~/ros_ws/src
43+
```
44+
45+
Clone this repository:
46+
```bash
47+
# ROS 2
48+
git clone https://github.com/RobotWebTools/web_video_server.git
49+
# ROS 1
50+
git clone https://github.com/RobotWebTools/web_video_server.git -b ros1
51+
```
52+
53+
Install dependencies with rosdep:
54+
```bash
55+
cd ~/ros_ws
56+
rosdep update
57+
rosdep install --from-paths src -i
58+
```
59+
60+
Build the package and source your workspace:
61+
```bash
62+
colcon build --packages-select web_video_server
63+
source install/setup.bash
64+
```
65+
66+
## Usage
67+
68+
### Starting the Server
69+
70+
```bash
71+
# ROS 1
72+
rosrun web_video_server web_video_server
73+
74+
# ROS 2
75+
ros2 run web_video_server web_video_server
76+
```
77+
78+
79+
### Configuration
80+
81+
#### Server Configuration Parameters
82+
83+
| Parameter | Type | Default | Possible Values | Description |
84+
|-----------|------|---------|----------------|-------------|
85+
| `port` | int | 8080 | Any valid port number | HTTP server port |
86+
| `address` | string | "0.0.0.0" | Any valid IP address | HTTP server address (0.0.0.0 allows external connections) |
87+
| `server_threads` | int | 1 | 1+ | Number of server threads for handling HTTP requests |
88+
| `ros_threads` | int | 2 | 1+ | Number of threads for ROS message handling |
89+
| `verbose` | bool | false | true, false | Enable verbose logging |
90+
| `default_stream_type` | string | "mjpeg" | "mjpeg", "vp8", "vp9", "h264", "png", "ros_compressed" | Default format for video streams |
91+
| `publish_rate` | double | -1.0 | -1.0 or positive value | Rate for republishing images (-1.0 means no republishing) |
92+
93+
#### Running with Custom Parameters
94+
95+
You can configure the server by passing parameters via the command line:
96+
97+
```bash
98+
# ROS 1
99+
rosrun web_video_server web_video_server _port:=8081 _address:=localhost _server_threads:=4
100+
101+
# ROS 2
102+
ros2 run web_video_server web_video_server --ros-args -p port:=8081 -p address:=localhost -p server_threads:=4
103+
```
104+
105+
### View Available Streams
106+
```
107+
http://localhost:8080/
108+
```
109+
The interface allows quick navigation between different topics and formats without having to manually construct URLs.
110+
111+
This page displays:
112+
- All available ROS image topics currently being published
113+
- Direct links to view each topic in different formats:
114+
- Web page with streaming image
115+
- Direct stream
116+
- Single image snapshot
117+
118+
### Stream an Image Topic
119+
120+
There are two ways to stream the Image, as a HTML page via
121+
```
122+
http://localhost:8080/stream_viewer?topic=/camera/image_raw
123+
```
124+
or as a HTTP multipart stream on
125+
126+
```
127+
http://localhost:8080/stream?topic=/camera/image_raw
128+
```
129+
#### URL Parameters for Streaming
130+
131+
The following parameters can be added to the stream URL:
132+
133+
| Parameter | Type | Default | Possible Values | Description |
134+
|-----------|------|---------|----------------|-------------|
135+
| `topic` | string | (required) | Any valid ROS image topic | The ROS image topic to stream |
136+
| `type` | string | "mjpeg" | "mjpeg", "vp8", "vp9", "h264", "png", "ros_compressed" | Stream format |
137+
| `width` | int | 0 | 0+ | Width of output stream (0 = original width) |
138+
| `height` | int | 0 | 0+ | Height of output stream (0 = original height) |
139+
| `quality` | int | 95 | 1-100 | Quality for MJPEG and PNG streams |
140+
| `bitrate` | int | 100000 | Positive integer | Bitrate for H264/VP8/VP9 streams in bits/second |
141+
| `invert` | flag | not present | present/not present | Invert image when parameter is present |
142+
| `default_transport` | string | "raw" | "raw", "compressed", "theora" | Image transport to use |
143+
| `qos_profile` | string | "default" | "default", "system_default", "sensor_data", "services_default" | QoS profile for ROS 2 subscribers |
144+
145+
Examples:
146+
147+
```
148+
# Stream an MJPEG at 640x480 with 90% quality
149+
http://localhost:8080/stream?topic=/camera/image_raw&type=mjpeg&width=640&height=480&quality=90
150+
151+
# Stream H264 with higher bitrate
152+
http://localhost:8080/stream?topic=/camera/image_raw&type=h264&bitrate=500000
153+
154+
# Stream with inverted image (rotated 180°)
155+
http://localhost:8080/stream?topic=/camera/image_raw&invert
156+
157+
```
158+
159+
### Get a Snapshot
160+
It is also possible to get a single image snapshot
161+
```
162+
http://localhost:8080/snapshot?topic=/camera/image_raw
163+
```
164+
#### URL Parameters for Snapshot
165+
166+
| Parameter | Type | Default | Possible Values | Description |
167+
|-----------|------|---------|----------------|-------------|
168+
| `topic` | string | (required) | Any valid ROS image topic | The ROS image topic to stream |
169+
| `width` | int | 0 | 0+ | Width of output picture (0 = original width) |
170+
| `height` | int | 0 | 0+ | Height of output picture (0 = original height) |
171+
| `quality` | int | 95 | 1-100 | Quality for JPEG snapshots |
172+
| `invert` | flag | not present | present/not present | Invert image when parameter is present |
173+
| `default_transport` | string | "raw" | "raw", "compressed", "theora" | Image transport to use |
174+
| `qos_profile` | string | "default" | "default", "system_default", "sensor_data", "services_default" | QoS profile for ROS 2 subscribers |
175+
176+
## About
177+
178+
This project is released as part of the [Robot Web Tools](https://robotwebtools.github.io/) effort.
179+
180+
## License
14181
web_video_server is released with a BSD license. For full terms and conditions, see the [LICENSE](LICENSE) file.
15182

16-
### Authors
183+
## Authors
17184
See the [AUTHORS](AUTHORS.md) file for a full list of contributors.

0 commit comments

Comments
 (0)