RaspberryPI（ラズパイ）×産業用UVCカメラ（USBカメラ）ダウンロードサイト＜Linux版＞ TheImagingSource | ソフトウェア

ダウンロード
The Imaging Source　ダウンロードサイト（Linux版）
ユーザーガイド：ラズパイ × 産業用UVCカメラ（USBカメラ）

ラズパイ × 産業用UVCカメラ（USBカメラ）

初めに：
Raspberry Pi（ラズパイ）は、小型でUSBやLAN、GPIOインターフェースを持っており、Wi-Fi、Bluetoothも搭載されています。最大の特徴である小型、ローコストであるという2点により、ラズベリーパイを使えば産業用カメラの用途を大幅に広げることが期待できます。

カメラ	TheImagingSource社製産業用UVCカメラ DFK(DMK)22/42/72　USB2.0カメラシリーズ DFK(DMK)23/33/37/38　USB3.0カメラシリーズ DFK(DMK)-Fシリーズ　USB2.0/3.0オートフォーカスカメラシリーズ
PC	Raspbery Pi 4 Model B（memory 4GB）・SoC：Broadcom BCM2711 ・CPU：1.5GHz クアッドコア Cortex-A72（ARMv8、64bit L1=32KB、L2=1M）・メモリ：4GB（DDR4-2400低電圧）・ストレージ：microSDカード・ビデオ出力：Micro HDMI×2（4Kデュアル）・USB：USB2.0×2、USB3.0×2 ・Ethernet（有線LAN）：10/100/1000 Base-T ・Wi-Fi（無線LAN）／Bluetooth：IEEE 802.11 b/g/n/ac 2.4/5GHz デュアルバンド／Bluetooth 5.0 ・電源：5V3A（USB Type-Cメス）、またはピンヘッダまたはPoE HAT ・寸法：85mm×56mm×18mm ・工事設計認証（技適・電波法）／設計認証（電気通信事業法）番号：[007-AF0184]／[D190067007] https://www.raspberrypi.org/products/raspberry-pi-4-model-b/
OS環境	Raspbian Buster with desktop and recommended software Version:September 2019 Release date:2019-09-26 Kernel version:4.19 Size:2541 MB https://www.raspberrypi.org/software/

1. ラズパイ側のアップデート

sudo date --set="2019/12/11 11:46"
sudo apt update
sudo apt upgrade

解説.１OSをインストールしたら最初に時刻の設定をしてください。Linuxのリポジトリから様々なモジュールをダウンロードする必要がありますが、時刻の設定をしていないとLinuxサーバからのダウンロードに失敗します。時刻設定をしたら環境のアップデートをします。

2. TISの環境のインストール編

v4l2の場合

sudo apt-get install git
sudo apt-get install v4l-utils
git clone https://github.com/TheImagingSource/tiscamera.git
cd tiscamera 
sudo ./scripts/dependency-manager install
mkdir build
cd build
cmake -DBUILD_ARAVIS=ON -DBUILD_LIBUSB=ON -DBUILD_V4L2=ON -DBUILD_GST_1_0=ON -DBUILD_TOOLS=ON -DBUILD_DOCUMENTATION=ON ..
sudo make
sudo make install

解説.２公式リポジトリからgitをインストールし、TheImagingSource社の公式リポジトリからgitのコピーをダウンロードします（OSによっては既にgitがインストールされているものもあります）。tiscameraのディレクトリに移動し、そこでTISカメラを動作させるのに必要な依存パッケージをインストールします。dependencies.shは、tiscameraがDebianベースのシステムで動作するのに必要な依存関係パッケージを自動でインストールする為のシェルスクリプトです。 --compilationでコンパイル、--runtimeでランタイム依存関係のインストールをします。buildフォルダーを作成しそこに移動し、cmakeします。cmakeしたらmakeしてインストールします。

補　足ラズパイやJetsonでsudo makeで処理が毎回同じ箇所で詰まる場合はメモリ不足やCPU処理速度が不足している場合があります。その場合は「スワップの拡張」と「Makeの並列化」を行ってください。拡張方法については、CONF_SWAPFILEで検索してご確認ください。Makeの並列化については、sudo makeコマンドではCPUを1コアしか使いませんが、sudo make -j2とすると2コア使ってmake処理を行います。このように開発時におけるメモリ不足とCPU処理速度不足によるパフォーマンス低下を回避してください。

USB3 Visionの場合（33、37、38シリーズのみ対応）

git clone https://github.com/TheImagingSource/tiscamera.git
cd tiscamera
sudo ./scripts/dependency-manager install
mkdir build
cd build
cmake -DBUILD_ARAVIS=ON -DBUILD_LIBUSB=ON -DBUILD_V4L2=ON -DBUILD_GST_1_0=ON -DBUILD_TOOLS=ON -DBUILD_DOCUMENTATION=ON -DTCAM_ARAVIS_USB_VISION=ON ..
sudo make
sudo make install

解説.３V4l2のドライバを使用している場合、選択できる解像度が限られております。V4l2にはないより多くのフレームレートと解像度を選択したい場合、Aravisを使用することでUSB3Visionデバイスとして制御することが可能です。
なお、USB3 Vision カメラは33、37、38シリーズのみ対応しており、USB2.0カメラと一部のUSB3.0カメラ（22、23、27シリーズ）は非対応です。プログラム上でUSB3Visionにて動作させるときには「12345678-aravis」のようにシリアル番号の後に「-aravis」を後付けする必要があります。

ワンポイントアドバイス

上記の【２. TISの環境のインストール編】で以下のようなエラーがでる場合があります。

[ERROR] [TcamView.py:509] - ERROR: displaysink : Could not initialise Xv output

このエラーが出る場合、gstreamerやGObject Introspectionなどの一部のパッケージのインストールに失敗している可能性があります。
これらのパッケージはtiscameraのモジュールの一部として利用されており、使用しているPCの環境によってはインストールに失敗する事があります。パッケージの一部のインストールに失敗してそうな場合は、別のバージョンのtiscameraをインストールしてみてください。

別のバージョンのtiscameraにアクセスするには、【tiscamera】＞ master(画面左上コンボボックス) ＞ Tagsからアクセスができます。

別のバージョンのtiscameraをインストールする為に、既にインストールしてしまったtiscameraを以下の通りいったんアンインストールしてください。

cd tiscamera/build
sudo make uninstall

git cloneの部分に別バージョンのtiscameraを指定し下記の例のように再度インストールします。

sudo apt-get install git
sudo apt-get install v4l-utils
git clone https://github.com/TheImagingSource/tiscamera.git -b v-tiscamera-0.12.0
cd tiscamera  
sudo ./scripts/install-dependencies.sh --compilation --runtime
mkdir build
cd build
cmake -DBUILD_ARAVIS=ON -DBUILD_LIBUSB=ON -DBUILD_V4L2=ON -DBUILD_GST_1_0=ON -DBUILD_TOOLS=ON -DBUILD_DOCUMENTATION=ON ..
sudo make
sudo make install

ここでは、例としてtiscameraのバージョン0.12.0のバージョンでインストールを行っていますが、tiscameraのバージョンによってインストール手順が若干異なる場合があります(sudo ./script…の部分など)。インストール手順は上記リンク内にある各バージョンのREADMEファイルをご確認ください。

動作確認

解説.４上記のモジュールが正しくbuild、cmake、make、make installができていれば、接続したUSBカメラを「tcam-ctrl」にて下記のように確認できます。デバイスが表示されていない場合は、上記の手順でエラーが出ている可能性がありますので解説２、解説３の必要な依存関係パッケージをインストール（sudo ./scripts/install-dependencies.sh --compilation –runtimeを実行）したうえで再度build、cmake、make、make instalを行ってください。

V4l2あるいはUSB3Visionでライブ表示を表示するには、下記のようにコマンドラインを実行することで映像を確認できます。

V4l2の場合（シリアル番号：16710581）

gst-launch-1.0 tcamsrc serial=16710581 ! video/x-raw,width=640,height=480 ! videoconvert ! ximagesink

USB3Visionの場合（シリアル番号：16710581）

gst-launch-1.0 tcamsrc serial=16710581-aravis ! video/x-raw,width=640,height=480 ! videoconvert ! ximagesink

３.UVC Extensionsをインストール

cd
cd tiscamera/data/uvc-extensions
sudo apt-get install uvcdynctrl
USB2.0カメラの場合　sudo uvcdynctrl -i tisEUVC.xml -d /dev/video0
USB3.0カメラの場合　sudo uvcdynctrl -i usb3.xml -d /dev/video0

解説.５sudo ./scripts/install-dependencies.sh –compilation --runtimeでインストールすると以下の環境がインストールされてしまいます。
https://github.com/TheImagingSource/tiscamera/blob/master/dependencies/dependencies-debian-compilation.txt
https://github.com/TheImagingSource/tiscamera/blob/master/dependencies/dependencies-debian-runtime.txt
既存の開発環境で既に他のUVCカメラを既に制御していて、TISの環境を新たに追加したくない場合や、既存のLinuxのビューワソフトウェアでUVCデバイスとしてハードウェア機能にアクセスしすぐに動作させたい場合は、.sh⇒cmake⇒make⇒make installをせずにこちらのプロセスを行ってください。まずUVCカメラが持つ機能にアクセスする為のツールであるuvcdynctrlをインストールします。uvcdynctrlにxmlファイルを認識させ、vl42ドライバがxml経由でカメラにアクセスできるようにします。２の手順通りにそのままcmakeすると、/etc/udev/rules.dにxml ファイルとほぼ同じ機能を果たすtiscamera-cameras.rulesがインストールされますが、これがあるとv4l2はxmlファイルを読み込まずにtiscamera-cameras.rulesに従ってデバイスにアクセスします。

４. 動作確認編

tcam-capture

解説.６GUIでTISの産業用UVCカメラを操作できるビューワツールtcam-captureとtiscameraを動作する環境が整ったので、実際にtiscameraが動作するかtcam-captureで確認します。tcam-captureの立ち上げ時は特にパスを指定する必要はありません。2. TISの環境のインストール編に進み、.sh⇒cmake⇒make⇒make installをしていない場合はtcam-captureはインストールされていません。
（※古いTcam-Captureでは動作が不安定でアプリが落ちることがあります。Tcam-Captureが不安定な場合は、動作確認番外編へお進みください。）

ワンポイントアドバイス

Tcam-captureはPythonのプログラムでコーディングされています。PyenvなどのPython環境のバージョンツールを利用していた場合、Tcam-captureの参照先が変更されてしまっている場合があります。その場合、tcam-captureとターミナルで実行しても、Tcam-captureの参照先が違っているので(ModuleNotFoundError: No module named 'tcam_capture')といったエラーが出る事があります。

$ tcam-capture
Traceback (most recent call last):
  File "/usr/bin/tcam-capture", line 28, in <module>
    from tcam_capture.TcamDevice import TcamDevice, TcamDeviceIndex
ModuleNotFoundError: No module named 'tcam_capture'

このようなエラーが出る場合は、tcam-captureのパス（/usr/lib/python3/dist-packages/tcam_capture）をPYTHONPATHに追加してください。
コマンドラインで下記のコマンドを入力することで参照先が追加されます。

export PYTHONPATH="/usr/lib/python3/dist-packages/tcam_capture:$PYTHONPATH"

４－１．動作確認編（USB2.0カメラDFK22/42/72シリーズの場合）

git clone https://github.com/TheImagingSource/tcam-firmware-update
mkdir tcam-firmware-update/build
cd tcam-firmware-update/build
cmake ..
make
cd bin
sudo ./tcam-firmware-update -l
sudo ./tcam-firmware-update -id <serial>
sudo ./tcam-firmware-update -ud <serial number> -f ../../firmware/usb2/dfk72uc02_3012.euvc
sudo ./tcam-firmware-update -d <serial number> -m uvc

解説.７22/42/72シリーズはデフォルトでUVCモードがONになっていない場合があります。そこでUVCモードをONにしますが、モードを切り合えるにはファームウェアの更新を伴います。新たにTheImagingSource社の公式リポジトリからファームウェアアップデートのプログラムのあるgitのコピーを、任意の場所にダウンロードし、コンパイル(make)まで行います。コンパイルが成功したらtcam-firmware-updateが使用できる状態になるので、-lでOSが認識しているUSBカメラでupdateできるリストを表示します。そこで型番とシリアルNOを確認したら、-idでUVC mode is: ON/OFFを確認できます。OFFの場合は -udでファームウェアを書き換えます。必要なファームウェアはモデルによって異なるので以下をご確認ください。間違ったファームウェアを書き込むと故障する可能性がありますのでモデル名は十分ご確認ください。UVCモードをON（＝ファームウェアをアップデート）したら、USBケーブルを抜き差ししカメラを再起動する必要があります。カメラを再起動したら、再度 -idでUVC mode is: ONになったか確認してください。
https://github.com/TheImagingSource/tcam-firmware-update/tree/master/firmware/usb2
ファームウェアアップデート後UVC mode is: OFFの場合でも、”v4l2-ctl --list-devices”のコマンドで出力結果のカメラ一覧の中に該当する表示されていれば、UVCカメラとして動作しています。

※注意事項
https://github.com/TheImagingSource/tcam-firmware-update
ファームウェアアップデート（firmware-update -ud）する前に下記のコマンドを実行しないでください。
「firmware-update -d -m uvc firmware-update -d -m proprietary」
ファームウェアアップデートをする前に上記コマンドを実行するとカメラが故障します。
必ず解説手順に沿ってファームウェアのアップデートを実行してください。

動作確認番外編（tcam-captureを使わずターミナルでカメラを制御する）

tcam-ctrl -l

tcam-ctrl -c <serial>

gst-launch-1.0 tcamsrc serial=<serial> ! video/x-bayer,width=2592,height=1944,framerate=15/2 ! tcamwhitebalance auto=false red="75" green="65" blue="115" ! bayer2rgb ! videoconvert ! xvimagesink

解説.８tcam-captureを使わずにターミナルコマンドのみで動作確認をする方法です。２でTISの環境をインストールすると、tcam-ctrlツールが使えます。-lでtcam-ctrlで制御できるデバイスを列挙してシリアルNOを把握し、-cでgstreamer-1.0で設定できるカラーフォーマット/解像度 /フレームレートを把握します。把握できたら、gst-launch-1.0で画像を出力します。

例：DFK37BUX178でaravisの場合

例：DFK37BUX178でv4l2の場合

tcam-ctrl -p  <serial>
tcam-ctrl --load  <serial> '{"Gain Auto":"false","Gain":20,"Exposure Auto":"false","Exposure Time (us)":3000}'
tcam-ctrl --load  <serial> '{"Trigger Mode":"true"}'
tcam-ctrl --save  <serial>

解説.９gstreamer-1.0で画像を出力しながら、別のターミナルを立ち上げて-pで現在の設定値や設定可能な値を確認できます。上記の --loadでゲインや露光時間、トリガーモードを設定すれば、リアルタイム画像を確認しながらデバイス制御できます。Trigger Modeをtrueにするとカメラからの画像出力が停止します。また、--saveでカメラに保存されているプロパティ値一覧を確認することができます。

tcam-ctrl -p <serial>で設定項目にGain Auto、Exposure Time、Exposure Autoがない場合には上記の設定はできません。
その場合、露光時間の自動をオフにするには下記のようにGstreamerのtcamautoexposureプラグインを使用して制御する必要があります。

gst-launch-1.0 tcamsrc ! video/x-raw,width=640,height=480 ! tcamautoexposure auto-exposure=false auto-gain=false ! videoconvert ! ximagesink

Tcamautoexposureの他にもTIS社が提供しているGstreamerプラグインを用意しています（下記詳細）。
https://www.theimagingsource.com/documentation/tiscamera/tcam-gstreamer.html

これらのプラグインを利用してプロパティ値を制御することができますが、tcam-captureで表示されているすべてのプロパティ値にはアクセスすることができません。
Pythonのコーディングで使用するカメラプロパティの設定名称を取得するには下記のサンプルコードを実行してプロパティをご確認ください。
https://www.argocorp.com/UVC_camera/Linux_TIScam_Python.html

tcam-ctrl --save <serial> 
tcam-ctrl --load <serial> '{"Trigger Mode": "On","Offset Auto Center": "","Offset X": "624", "Offset Y": "50"}'
tcam-ctrl --save <serial> > properties.json
tcam-ctrl --load <serial> < properties.json

解説.10tcam-ctrl --saveでは接続したカメラの使用可能なプロパティの情報のリストを表示し、tcam-ctrl --loadではカメラにプロパティ値を反映させることができます。また、上記のように末尾にjsonファイルを指定することでプロパティ値を保存、ロードすることができます。

gst-launch-1.0 tcammainsrc tcam-properties=tcam,BalanceWhiteAuto=Off,BalanceWhiteRed=1.0,BalanceWhiteGreen=1.0,BalanceWhiteBlue=1.0 ! video/x-bayer,width=640,height=480,framerate=30/1 ! bayer2rgb ! jpegenc ! multifilesink location=/home/argo/output%d.jpeg

解説.11ソフトウェアトリガーで撮影した画像を、指定のフォルダーにjpg保存します。userはログインしているユーザ名のフォルダーです。

gst-launch-1.0 tcammainsrc tcam-properties=tcam,BalanceWhiteAuto=Off,BalanceWhiteRed=1.0,BalanceWhiteGreen=1.0,BalanceWhiteBlue=1.0 ! video/x-bayer,width=640,height=480,framerate=30/1 ! bayer2rgb ! tee name=t  ! queue ! jpegenc ! multifilesink location=/home/argo/output%d.jpeg  t. ! queue ! videoconvert ! xvimagesink

解説.12tcam-ctrl --saveでは接続したカメラの使用可能なプロパティの情報のリストを表示し、tcam-ctrl --loadではカメラにプロパティ値を反映させることができます。また、上記のように末尾にjsonファイルを指定することでプロパティ値を保存、ロードすることができます。

gst-launch-1.0 tcammainsrc tcam-properties=tcam,BalanceWhiteAuto=Off,BalanceWhiteRed=1.0,BalanceWhiteGreen=1.0,BalanceWhiteBlue=1.0 ! video/x-bayer,width=640,height=480,framerate=30/1 ! bayer2rgb ! tee name=t  ! queue ! jpegenc ! multifilesink location=/home/argo/output%d.jpeg  t. ! queue ! videoconvert ! videoscale ! video/x-raw,width=1024,height=768 ! xvimagesink

解説.13ソフトウェアトリガーで撮影し保存した画像を表示し、表示する画面のサイズを調整しています。
videoconvert ! xvimagesinkの間に、videoscale ! video/x-raw,width=1024,height=768 !を入れて表示画面のサイズを調整します。

動作確認番外編その２（モノクロ12bitとカラー12bitの取得方法）

gst-launch-1.0 tcamsrc serial=<serial> ! video/x-raw,format=GRAY16_LE,width=1920,height=1080,framerate=30/1 ! videoconvert ! ximagesink

解説.14モノクロカメラでGRAY16_LEのカラーフォーマットの画像を表示する方法です。
「tcam-ctrl -c <serial>」でカラーフォーマットGRAY16_LEが表示されるのであれば、直接GRAY16_LEを指定することができます。

gst-launch-1.0 tcamsrc serial=<serial> ! video/x-bayer,format=rggb16,width=1920,height=1080,framerate=30/1 ! capssetter join=false replace=true caps="video/x-raw,format=GRAY16_LE,width=1920,height=1080,framerate=30/1" ! videoconvert ! ximagesink

解説.15カラーカメラでGRAY16_LEのカラーフォーマットの画像を表示する方法です。
カラーカメラでは「tcam-ctrl -c <serial>」でGRAY16_LEが表示されず、直接GRAY16_LEを指定できないため、capssetterのモジュールで「video/x-bayer,format=rggb16」から「video/x-raw,format=GRAY16_LE」に置き換えることでカラーカメラでもモノクロ画像を表示することができます。

gst-launch-1.0 tcamsrc serial=<serial> ! video/x-bayer, format=rggb16,width=640,height=480,framerate=30/1 ! tcamdutils ! video/x-raw, format=RGBx64,width=640,height=480,framerate=30/1 ! tee name=t t. ! queue ! appsink t. ! queue ! tcambiteater ! videoconvert ! ximagesink

解説.16カラーカメラでRGBx64のカラーフォーマットの画像を表示する方法です。
RGBx64のカラーフォーマットを使用するにはメーカーが提供しているモジュールtcamdutilsでRGBx64に変換する必要があります。tee nameで12bitカラーデータをappsinkに入力し、並行して Videoconvertに引き渡しています。ただし、videoconvertではRGBx64をサポートしていないためtcambiteater でRGBx64をRGBx32に変換してから表示しています。
なお、tcamdutilsを使用するにはtiscamera-dutilsが必要となりますので事前にインストール（ダウンロードサイト4）、5) ）してください。

ダウンロード
The Imaging Source　ダウンロードサイト（Linux版）
ユーザーガイド：ラズパイ × 産業用UVCカメラ（USBカメラ）