Skip to content

updated gstreamer tutorial #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Fixstars-momoko merged 1 commit into from
Mar 18, 2025
Merged

updated gstreamer tutorial #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 79 additions & 39 deletions docs/tutorials/gstreamer/display-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,85 +4,125 @@ sidebar_position: 4

# Display Image with Gstreamer

This tutorial demonstrates how to use OpenCV with GStreamer, specifically leveraging the `appsink` element to capture and process video streams.
While the GStreamer API allows you to build and run pipelines for video capture and processing, combining the `appsink` element with OpenCV enables you to retrieve the output of a GStreamer pipeline directly into OpenCV for further manipulation.
This approach also supports various camera configurations, pixel formats, and frame sizes.
This tutorial introduces how to build and run a simple GStreamer pipeline to capture and display images from a camera.

While you can construct and execute pipelines for video capture and processing within any application with the GStreamer API, in this tutorial, we will demonstrate examples using the `gst-launch` console tool or integrating GStreamer with OpenCV, allowing for intuitive pipeline construction as a string.


## Tutorial

### Prerequisites
1. opencv-python with gstreamer backend ([Check this page to setup](../../external/OpenCV/how-to-build-opencv-with-gstreamer.md))
2. **windows**:
Install the C++ version of sensing-dev with `-InstallGstPlugins`. Make sure `GST_PLUGIN_PATH` is set.
3. **linux**:
Install the C++ version of sensing-dev with `--install-gst-tools`. Set the `GST_PLUGIN_PATH` environment variable and sensing-dev library_path:
```bash
export GST_PLUGIN_PATH=/opt/sensing-dev/lib/x86_64-linux-gnu/gstreamer-1.0
export LD_LIBRARY_PATH=/opt/sensing-dev/lib:/opt/sensing-dev/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
```
* Sensing-Dev SDK with GStreamer plugins and tools
* Windows: Install the C++ version of sensing-dev with `-InstallGstTools -InstallGstPlugins`. Make sure `GST_PLUGIN_PATH` is set.
* Linux: Install the C++ version of sensing-dev with `--install-gst-tools --install-gst-plugin`. Set the `GST_PLUGIN_PATH`.
* (When using OpenCV) OpenCV-Python with the GStreamer backend. Setup instructions can be found [here](../../external/OpenCV/how-to-build-opencv-with-gstreamer.md).
:::note
On Windows, the installation script automatically sets the environment variables.
On Linux, you need to manually configure the following environment variables:
```bash
export GST_PLUGIN_PATH=/opt/sensing-dev/lib/x86_64-linux-gnu/gstreamer-1.0
export LD_LIBRARY_PATH=/opt/sensing-dev/lib:/opt/sensing-dev/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
```
:::

### Configuration
Please adjust the camera_name, pixelformat, width, height, framerate based on your requirements. You can obtain these values by [arv-tool-0.8](../../external/aravis/arv-tools.md) in Sensing-Dev software package

```python
camera_name = 'replace-by-your-camera-name'
pixelformat = 'Mono8'
# pixelformat = 'BayerBG8'
width = 1920
height = 1080
framerate = 60
```

### Build a pipeline

The pipeline starts with `aravissrc`, which connects to the camera.
In a GStreamer pipeline, elements are connected using `!` to process and pass data through the pipeline.

The camera-name parameter specifies which camera to use.
| Element | description | parameters |
|---------------|---------------------------|-------------|
| aravissrc | camera data acquisition | camera-name |
| videoconvert | convert from raw to image | |
| autovideosink | display | |

#### Frame Processing:
The pipeline can be connected to the camera by setting the `aravissrc` element at the beginning.

##### For color images in Bayer format:
1. Convert the Bayer format to RGB using `bayer2rgb`.
2. Adjust the image format using `videoconvert` to ensure compatibility with OpenCV.
Additionally, formats can be specified using `video/x-raw` or `video/x-bayer`.

##### For grayscale images:
1. Support raw formats such as `GRAY8` (8-bit) or `GRAY16_LE` (16-bit).
2. Adjust the image format using `videoconvert`.
Here are a few examples:

#### Output to OpenCV:
##### Example for color images in Bayer format:
1. The camera image format is specified using `video/x-bayer` to define the Bayer format.
2. The Bayer format is converted to RGB using `bayer2rgb`.
3. To ensure compatibility, the image format is adjusted using `videoconvert`.

The final stage is `appsink`, which allows OpenCV to access the processed video frames.
Color (Bayer)(8-bit):
```bash
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-bayer,format=bggr,width=1920,height=1080,framerate=60/1 ! bayer2rgb ! videoconvert ! appsink
```

##### Example Pipelines:
1. Color (Bayer)(8-bit):
##### Example for grayscale images:
1. Raw formats such as `GRAY8` (8-bit) or `GRAY16_LE` (16-bit) are supported with `video/x-raw`.
2. The image format is adjusted using `videoconvert`.

Grayscale (8-bit)
```bash
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink
```
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-bayer,format=bggr,width=1920,height=1080,framerate=60/1 ! bayer2rgb ! videoconvert ! appsink

Grayscale (16-bit):
```bash
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-raw,format=GRAY16_LE,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink
```

2. Grayscale (8-bit)
:::note
Currently, this tutorial (GStreamer 1.20.3) does not support BayerBG10 and BayerBG12. The `bayer2rgb` element only supports 8-bit formats.
:::

### Execute the pipeline

The pipeline constructed above can be executed on the console using the `gst-launch` command-line tool.

Additionally, by replacing autovideosink with the `appsink` element, the Python OpenCV API becomes available, allowing the captured images to be displayed using OpenCV.

#### Option 1. Using gst-launch

When you install Sensing-Dev with the gst-plugins and tools options enabled, the `gst-launch-1.0` console tool becomes available.

By typing `gst-launch-1.0` on the command line and then entering the pipeline you constructed above, the images captured from the camera will continue to be displayed until you press `Ctrl-C`.

e.g.
```
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink
gst-launch-1.0 camera-name="<camera-name>" ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! autovideosink
```

3. Grayscale (16-bit):
#### Option 2. Output to OpenCV:

```
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-raw,format=GRAY16_LE,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink
By using `appsink` instead of `autovideosink`, OpenCV API can access the processed video frames.

You will need to import opencv-python with the GStreamer backend. The setup instructions can be found [here](../../external/OpenCV/how-to-build-opencv-with-gstreamer.md).

Additionally, if you are using Windows, you need to add the Sensing-Dev bin directory to the DLL directory so that opencv-python can find GStreamer, as follows:

```python
import os
if os.name == 'nt': # windows
os.add_dll_directory(os.path.join(os.environ["SENSING_DEV_ROOT"], "bin"))
import cv2
```

The line `cap = cv2.VideoCapture(pipeline, cv2.CAP_GSTREAMER)` connects OpenCV to the GStreamer Pipeline and tells OpenCV to use the pipeline to capture video frames.
Please construct the pipeline as a string as shown below. Also, make sure that the last element is `appsink`.

:::note
Currently this tutorial does not support BayerBG10 and BayerBG12, since for gstreamer 1.20.3, bayer2rgb only support 8 bits.
:::
```python
pipeline = 'aravissrc camera-name="<camera-name>" ! video/x-bayer,format=bggr,width=1920,height=1080,framerate=60/1 ! bayer2rgb ! videoconvert ! appsink'
```

### Display with OpenCV
In the source code, the line `cap = cv2.VideoCapture(pipeline, cv2.CAP_GSTREAMER)` connects OpenCV to the GStreamer pipeline, enabling OpenCV to capture video frames.

The output of `cap.read()` are `ret` and `frame` which are the result of reading the capture data and its data itself respectively.
The output of `cap.read()` consists of two parts: `ret`, which indicates whether the read operation was successful, and `frame`, which contains the actual captured data.

By displaying `frame` per pipeline execution with `for` loop, it looks like the sequential images.
By using a `for` loop to display the `frame` for each pipeline execution, you can continuously display the captured images.

```python
while (user_input == -1):
Expand Down
105 changes: 74 additions & 31 deletions ...ja/docusaurus-plugin-content-docs/current/tutorials/gstreamer/display-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,78 +4,121 @@ sidebar_position: 4

# 画像の表示

このチュートリアルでは、OpenCVと`appsink`エレメントを使ってGStreamerのパイプラインを構築・実行する方法を紹介します。
このチュートリアルでは、カメラから画像を取得して表示するためのシンプルなGStreamerのパイプラインを構築・実行する方法を紹介します。

GStreamer APIを使用すると、任意のアプリケーション内でビデオキャプチャおよび処理用のパイプラインを構築して実行できますが、今回はgst-launchというコンソールツール、またはOpenCVと組み合わせることで文字列として直感的にパイプラインの構築が可能になる例をご紹介します。

GStreamer APIを使用すると、ビデオキャプチャおよび処理用のパイプラインを構築して実行できますが、`appsink`エレメントをOpenCVと組み合わせることで、GStreamerパイプラインの出力を直接OpenCVに取り込むことが可能になります。
この方法は、さまざまなカメラ構成、ピクセルフォーマット、フレームサイズにも対応しています。

## チュートリアル

### 前提条件
1. GStreamerバックエンドを使用したopencv-python ([セットアップ方法](../../external/OpenCV/how-to-build-opencv-with-gstreamer.md))
2. **windows**:
sensing-devのC++版を`-InstallGstPlugins`オプション付きでインストールしてください。`GST_PLUGIN_PATH`環境変数が設定されていることを確認してください。
3. **linux**:
sensing-devのC++版を`--install-gst-tools`オプション付きでインストールしてください。`GST_PLUGIN_PATH`環境変数とsensing-devのライブラリパスを設定してください。
* Sensing-Dev SDK with gst-plugins and tools
* Windows: Sensing-DevのC++版を`-InstallGstTools -InstallGstPlugins`オプション付きでインストールしてください。`GST_PLUGIN_PATH`環境変数が設定されていることを確認してください。
* Linux: Sensing-DevのC++版を`--install-gst-tools --install-gst-plugin`オプション付きでインストールしてください。`GST_PLUGIN_PATH`環境変数とsensing-devのライブラリパスを設定してください。
* （OpenCVを使う場合）GStreamerバックエンドを使用したopencv-python。セットアップ方法は[こちら](../../external/OpenCV/how-to-build-opencv-with-gstreamer.md)。

:::note
Windowsのインストーラスクリプトでは環境変数が自動で設定されますが、Linuxでは以下の環境変数を別途設定する必要があります。
```bash
export GST_PLUGIN_PATH=/opt/sensing-dev/lib/x86_64-linux-gnu/gstreamer-1.0
export LD_LIBRARY_PATH=/opt/sensing-dev/lib:/opt/sensing-dev/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
```
:::

### 設定
カメラ名（camera_name）、ピクセル形式（pixelformat）、幅（width）、高さ（height）、フレームレート（framerate）を、必要に応じて調整してください。これらの値は、Sensing-Devソフトウェアパッケージ内の[arv-tool-0.8](../../external/aravis/arv-tools.md)を使用して取得できます。
カメラ名（camera_name）、ピクセル形式（pixelformat）、幅（width）、高さ（height）、フレームレート（framerate）を、必要に応じて調整してください。
これらの値は、Sensing-Devソフトウェアパッケージ内の[arv-tool-0.8](../../external/aravis/arv-tools.md)を使用して取得できます。

```python
camera_name = 'replace-by-your-camera-name'
pixelformat = 'Mono8'
# pixelformat = 'BayerBG8'
width = 1920
height = 1080
framerate = 60
```

### パイプラインの構築
パイプラインは`aravissrc`エレメントを最初に組み込むことでカメラに接続可能になります。camera-nameパラメータで使用するカメラを指定します。そこから`!`で後続のエレメントを繋ぎ、処理を進めていきます。

#### フレーム処理:
Gstreamerのパイプラインは`!`でエレメント同士を繋ぎ、処理を進めていきます。

##### Bayerフォーマットのカラー画像:
1. Bayerフォーマットを`bayer2rgb`でRGBに変換します。
2. 互換性を確保するために`videoconvert`で画像フォーマットを調整します。
| Element | description | parameters |
|---------------|---------------------------|-------------|
| aravissrc | camera data acquisition | camera-name |
| videoconvert | convert from raw to image | |
| autovideosink | display | |

##### グレースケール画像:
1. `GRAY8`（8ビット）や`GRAY16_LE`（16ビット）などの生フォーマットをサポートします。
2. 画像フォーマットを`videoconvert`で調整します。
パイプラインは`aravissrc`エレメントを最初に組み込むことでカメラに接続可能になります。

#### OpenCVへの出力:
また、`video/x-raw`や`video/x-bayer`によってフォーマットの指定が可能になります。

最後に、`appsink`を使用してOpenCVが処理済みのビデオフレームにアクセスできるようにします。
以下はいくつかの例です。

##### パイプライン例:
1. カラー（Bayer）(8ビット):
##### Bayerフォーマットのカラー画像の例:
1. Bayer指定をするために`video/x-bayer`でカメラの画像のフォーマットを指定します。
2. Bayerフォーマットを`bayer2rgb`でRGBに変換します。
3. 互換性を確保するために`videoconvert`で画像フォーマットを調整します。

カラー（Bayer）(8ビット):
```
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-bayer,format=bggr,width=1920,height=1080,framerate=60/1 ! bayer2rgb ! videoconvert ! appsink
aravissrc camera-name="<camera-name>" ! video/x-bayer,format=bggr,width=1920,height=1080,framerate=60/1 ! bayer2rgb ! videoconvert ! autovideosink
```

2. グレースケール(8ビット):
##### グレースケール画像の例:
1. `GRAY8`（8ビット）や`GRAY16_LE`（16ビット）などの生フォーマットを`video/x-raw`でサポートします。
2. 画像フォーマットを`videoconvert`で調整します。

グレースケール(8ビット):
```
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink
aravissrc camera-name="<camera-name>" ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! autovideosink
```

3. グレースケール(16ビット):

グレースケール(16ビット):
```
aravissrc camera-name="<camera-name>" ! gendcseparator ! queue ! video/x-raw,format=GRAY16_LE,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink
aravissrc camera-name="<camera-name>" ! video/x-raw,format=GRAY16_LE,width=1920,height=1080,framerate=60/1 ! videoconvert ! autovideosink
```

ソースコードの`cap = cv2.VideoCapture(pipeline, cv2.CAP_GSTREAMER)`という部分で、OpenCVをGStreamerパイプラインに接続し、OpenCVがビデオフレームをキャプチャ可能になりました。

:::note
現在、このチュートリアル（GStreamer 1.20.3）はBayerBG10およびBayerBG12をサポートしていません。bayer2rgbは8ビットのみに対応しています。
:::

### OpenCVでの画像表示
### パイプラインの実行

上記で構築したパイプラインはgst-launchというコンソールツールを使うことでコンソール上で実行可能です。また、`autovideosink`の代わりに`appsink`というエレメントに置き換えることで、PythonのOpenCV APIが使用可能になり、キャプチャした画像をOpenCVで表示することが可能になります。

#### Option 1. gst-launchの使用

Sensing-Devをgst-pluginsとtoolsオプションを有効にしたうえでインストールを行うと、`gst-launch-1.0`というコンソールツールが使用可能になります。

コマンドライン上で`gst-launch-1.0`と入力し、上記で構築したパイプラインを続けて入力すると、ctrl-Cを押すまでの間、カメラから取得した画像が表示され続けます。

例：
```
gst-launch-1.0 camera-name="<camera-name>" ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! autovideosink
```

#### Option 2. OpenCVへの出力:

`autovideosink`の代わりに`appsink`を使用してOpenCVのAPIが処理済みのビデオフレームにアクセスできるようにします。

GStreamerバックエンドを使用したopencv-python をimportする必要があります。セットアップ方法は[こちら](../../external/OpenCV/how-to-build-opencv-with-gstreamer.md)。

また、Windowsをお使いの場合はopencv-pythonがgstreamerを見つけるために、以下のようにSensing-Devのbinをdllディレクトリに追加してください。_

```python
import os
if os.name == 'nt': # windows
os.add_dll_directory(os.path.join(os.environ["SENSING_DEV_ROOT"], "bin"))
import cv2
```

下記のように文字列としてパイプラインを構築してください。また、一番最後が`appsink`になっていることを確かめてください。

```python
pipeline = 'aravissrc camera-name="<camera-name>" ! video/x-bayer,format=bggr,width=1920,height=1080,framerate=60/1 ! bayer2rgb ! videoconvert ! appsink'
```

ソースコードの`cap = cv2.VideoCapture(pipeline, cv2.CAP_GSTREAMER)`という部分で、OpenCVをGStreamerパイプラインに接続し、OpenCVがビデオフレームをキャプチャ可能になりました。


`cap.read()`の出力は読み込みの結果を示す`ret`と実際のキャプチャデータを含む`frame`です。

Expand Down