diff --git a/docs/tutorials/gstreamer/display-image.mdx b/docs/tutorials/gstreamer/display-image.mdx index 9150d89..ade8946 100644 --- a/docs/tutorials/gstreamer/display-image.mdx +++ b/docs/tutorials/gstreamer/display-image.mdx @@ -4,22 +4,26 @@ 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 @@ -27,7 +31,6 @@ Please adjust the camera_name, pixelformat, width, height, framerate based on yo ```python camera_name = 'replace-by-your-camera-name' pixelformat = 'Mono8' - # pixelformat = 'BayerBG8' width = 1920 height = 1080 framerate = 60 @@ -35,54 +38,91 @@ Please adjust the camera_name, pixelformat, width, height, framerate based on yo ### 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="" ! 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="" ! gendcseparator ! queue ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink ``` -aravissrc 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="" ! 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="" ! gendcseparator ! queue ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink +gst-launch-1.0 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="" ! 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="" ! 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): diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/gstreamer/display-image.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/gstreamer/display-image.mdx index 59e757c..89dd432 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/gstreamer/display-image.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/gstreamer/display-image.mdx @@ -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="" ! gendcseparator ! queue ! video/x-bayer,format=bggr,width=1920,height=1080,framerate=60/1 ! bayer2rgb ! videoconvert ! appsink +aravissrc 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="" ! gendcseparator ! queue ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink +aravissrc camera-name="" ! video/x-raw,format=GRAY8,width=1920,height=1080,framerate=60/1 ! videoconvert ! autovideosink ``` -3. グレースケール(16ビット): - +グレースケール(16ビット): ``` -aravissrc camera-name="" ! gendcseparator ! queue ! video/x-raw,format=GRAY16_LE,width=1920,height=1080,framerate=60/1 ! videoconvert ! appsink +aravissrc 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="" ! 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="" ! 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`です。