WebCFace

Web-based RPC & UI Library

WebSocketとMessagePackを使った、ROSのような分散型の通信ライブラリです。 クロスプラットフォームかつ異なる言語間で数値、文字列、画像などのデータを送受信したり、関数(手続き)を呼び出したりすることができます。

WebCFaceはプログラム間の通信のライブラリとして使うことができるだけでなく、 WebブラウザーでアクセスできるUI(WebUI)を使うことでWebCFaceで通信されているデータを可視化したり関数を呼び出したりできます。 WebUIでは簡易なUIを作成したり2D、3Dの図形の描画をさせることもできます。

• plotjuggler-webcface-plugin を使うと、WebCFaceで通信されているデータを PlotJuggler を使って見ることもできます。

Benchmark

ver1.11時点のReleaseビルドの src/example/benchmark.cc で通信速度をチェックしてみました。 以下の表は クライアント→サーバー→クライアント でさまざまなサイズの文字列データの送受信にかかった時間です。 なおこれはサーバーとクライアントが同一マシン上の場合の結果なので、Wi-FiやEthernetを経由する場合はその環境次第ですがこれより遅くなると思います。

使用したPCのCPUは、MacOSは Apple M1 、それ以外は Intel Core i5-13500 です。

表

OS	10Byte	100Byte	1kByte	10kByte	100kByte	1MByte
Windows (MSVC build)	244 μs	301 μs	381 μs	428 μs	2.82 ms	22.5 ms
Windows (MinGW build)	219 μs	218 μs	262 μs	411 μs	1.93 ms	17.0 ms
Linux (on WSL1)	177 μs	213 μs	195 μs	272 μs	1.26 ms	12.3 ms
Server=MSVC + Client=WSL1	323 μs	258 μs	401 μs	420 μs	2.34 ms	18.2 ms
Server=MSVC + Client=WSL2	379 μs	369 μs	488 μs	656 μs	2.47 ms	17.6 ms
Server=WSL1 + Client=MSVC	335 μs	287 μs	252 μs	504 μs	2.02 ms	16.3 ms
Server=WSL2 + Client=MSVC	553 μs	637 μs	622 μs	810 μs	2.28 ms	29.5 ms
Linux (Native)	491 μs	439 μs	519 μs	1.01 ms	4.78 ms	27.8 ms
MacOS	130 μs	136 μs	165 μs	439 μs	2.98 ms	28.3 ms

Links

• webcface: サーバー & C/C++クライアントライブラリ (このリポジトリ)
• webcface-webui: webブラウザ用UIアプリ
• webcface-tools: コマンドラインツール群
• webcface-js: JavaScriptクライアントライブラリ
• webcface-python: Pythonクライアントライブラリ
• homebrew-webcface: HomebrewのTapを管理しています
• webcface-windows-package: Windows用ビルドをリリースする場所
• plogjuggler-webcface-plugin: PlotJuggler プラグイン

Installation

以下の手順で webcface, webcface-webui, webcface-tools をインストールできます。 (webcface-toolsの内容と使い方についてはwebcface-toolsのReadmeを参照してください)

Ubuntu (x86_64, arm64, armhf)

WebCFaceのReleases と webuiのReleases 、toolsのReleases からそれぞれ最新のdebパッケージをダウンロードしてインストールできます。

debパッケージはubuntu20.04,22.04,24.04でビルドしています。 それぞれ依存するパッケージのバージョンが違います。 Debianなど他のディストリビューションで動作するかはわかりません。

コマンドからダウンロードするなら以下のようにします。

Ubuntu 24.04 Noble

x86_64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu24.04_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu24.04_amd64.deb

arm64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu24.04_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu24.04_arm64.deb

armhf

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu24.04_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu24.04_armhf.deb

Ubuntu 22.04 Jammy

x86_64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu22.04_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu22.04_amd64.deb

arm64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu22.04_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu22.04_arm64.deb

armhf

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu22.04_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu22.04_armhf.deb

Ubuntu 20.04 Focal

x86_64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu20.04_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu20.04_amd64.deb

arm64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu20.04_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu20.04_arm64.deb

armhf

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v1.11.3/webcface_1.11.3-ubuntu20.04_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.6.0/webcface-webui_1.6.0-s_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v1.4.4/webcface-tools_1.4.4-ubuntu20.04_armhf.deb

ダウンロードできたら

sudo apt install ./webcface*.deb
rm ./webcface*.deb

でインストールできます

Homebrew (MacOS, Linux)

brew tap na-trium-144/webcface
brew install webcface webcface-webui webcface-tools

App Bundle for MacOS

homebrew-webcfaceのRelease から .app.zip ファイルをダウンロードするか、

brew tap na-trium-144/webcface
brew install --cask webcface-webui-server

でインストールできます。

インストールしたappを起動するとWebUIのウィンドウとwebcface-serverが起動します。(詳細はドキュメントの Overview を参照)

Windows (MSVC)

webcface-windows-packageのReleaseからインストーラーをダウンロードしてください。

MinGW用バイナリは今のところ配布していません(ソースからビルドしてください)

Build from source

以下はwebcfaceをソースからビルドする場合の説明です。(webcfaceをインストールした場合は不要です。)

Requirements

• c++20に対応したコンパイラが必要です
• テスト済みの環境
  • (gcc-10以上)
  • (clang-13以上)
  • 
  • 
  • 
• webcfaceは外部ライブラリとして crow, asio, libcurl, eventpp, msgpack-cxx, spdlog, cli11, UTF8-CPP, opencv を使用します。
  • cmake時に自動的にFetchContentでソースコード取得しビルドしますが、eventpp, msgpack, spdlog に関してはシステムにインストールされていてfind_packageで見つけることができればそれを使用します
  • opencvはソースからビルドしません。別途インストールする必要があります。
    • またはcmake時のオプションでopencvを使わないようにすることもできます (画像の変換機能が無効になります)
  • libcurlはwebsocket機能を有効にする必要があるためインストールされている場合でもソースからビルドします

Ubuntu 20.04, 22.04

sudo apt install build-essential git cmake
sudo apt install libopencv-dev libspdlog-dev  # optional

ubuntu20.04の場合デフォルトのコンパイラ(gcc-9)ではビルドできないのでgcc-10にする必要があります

sudo apt install gcc-10 g++-10
export CC=gcc-10
export CXX=g++-10

Homebrew (MacOS, Linux)

brew install cmake
brew install opencv spdlog msgpack-cxx  # optional

Visual Studio

• Visual Studio 2019, 2022 でcloneしたwebcfaceのフォルダーを開くとビルドできます
• Developer Command Promptからcmakeコマンドを使ってもビルドできます
• OpenCVを使う場合は公式サイトからダウンロードしてください
  • またはchocolateyでchoco install opencvなど

MSYS2

pacman -S git mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja
pacman -S mingw-w64-x86_64-opencv mingw-w64-x86_64-spdlog  # optional

Build (with Pure CMake)

cmake -Bbuild
cmake --build build
sudo cmake --build build -t install

• CMakeのオプション
  • -DWEBCFACE_USE_OPENCV=offにするとOpenCVを使用しないようになります
  • -DWEBCFACE_FIND_LIBS=offにするとmsgpack, eventpp, spdlogをfind_packageせずソースからビルドします
  • -DWEBCFACE_SHARED=offにすると共有ライブラリではなくすべて静的ライブラリになります
  • -DWEBCFACE_EXAMPLE=onでtestをビルドします(submoduleの場合デフォルトでoff)
  • -DWEBCFACE_INSTALL=onでtargetをinstallします(submoduleの場合デフォルトでoff)
    • さらに-DWEBCFACE_INSTALL_SERVICE=onで webcface-server.service を lib/systemd/system にインストールします (デフォルトでoff)
  • -DWEBCFACE_TEST=onでtestをビルドします(デフォルトでoff)
    • テストが通らない場合テスト中の通信の待機時間を-DWEBCFACE_TEST_TIMEOUT=100などと伸ばすとうまく行く場合があります(デフォルト=10(ms))
  • -DWEBCFACE_VERSION_SUFFIXでバージョン表記を変更できます
    • 例えばバージョン(common/def.hに定義されている)が1.2.0のとき
    • -DWEBCFACE_VERSION_SUFFIX=git なら git describe --tags コマンドを使用して取得した文字列 (1.2.0-x-gxxxxxxx) になります(未指定の場合のデフォルト)
    • git以外の任意の文字列の場合 -DWEBCFACE_VERSION_SUFFIX=hoge で 1.2.0-hoge になります
    • -DWEBCFACE_VERSION_SUFFIX= で 1.2.0 だけになります

Build (with colcon, ROS2)

• このリポジトリをワークスペースのsrcに追加して、colconでビルドすることができます

WebUI

• デフォルトではビルド済みのものがcmake時にダウンロードされます。
• -DWEBCFACE_DOWNLOAD_WEBUI=offを指定するとダウンロードしません。
  • その場合は webuiのReleases からビルド済みのtar.gzのアーカイブをダウンロードして /usr/local/share/webcface/dist として展開するのが簡単です。
    • install先が/usr/localでない場合はprefixを読み替えてください
    • installせずに実行する場合は webcface-server のバイナリと同じディレクトリか、その1, 2, 3階層上のどこかにdistディレクトリを配置してください
  • または自分でビルドすることも可能です(node.jsが必要)
• このリポジトリのReleasesにあるdebパッケージとhomebrewではwebcfaceのパッケージとは別で配布しています

tools

• toolsは別途 https://github.com/na-trium-144/webcface-tools.git をcloneしてビルド、インストールしてください

Documentation

• まずはここから→ Overview
• APIリファレンス
• webcface-python APIリファレンス
• webcface-js APIリファレンス

License

WebCFaceと関連するプログラムはすべてMITライセンスで公開しています。詳細は LICENSE を参照してください。

WebCFace本体とtoolsが使用しているサードパーティーのライブラリのライセンスはそれぞれ以下を参照してください。

• Crow (BSD 3-Clause) : https://github.com/CrowCpp/Crow
• Asio (Boost Software License) : http://think-async.com/Asio/
• curl : https://curl.se/docs/copyright.html
• eventpp (Apache 2.0) : https://github.com/wqking/eventpp
• msgpack-c (Boost Software License) : https://github.com/msgpack/msgpack-c
• spdlog (MIT) : https://github.com/gabime/spdlog
• CLI11 (BSD 3-Clause) : https://github.com/CLIUtils/CLI11
• UTF8-CPP (BSD 1.0) : https://github.com/nemtrif/utfcpp
• OpenCV (Apache 2.0) : https://opencv.org/license/
• tiny-process-library (MIT) : https://gitlab.com/eidheim/tiny-process-library (toolsで使用)
• toml++ (MIT) : https://github.com/marzer/tomlplusplus (toolsで使用)