labstreaminglayer初探

最新推荐文章于 2024-10-10 07:11:50 发布

seuzwb

最新推荐文章于 2024-10-10 07:11:50 发布

阅读量2.8k

点赞数 2

分类专栏：学习笔记

学习笔记专栏收录该内容

1 篇文章

订阅专栏

labstreaminglayer初探

Building LSL

简介

github地址：https://github.com/sccn/labstreaminglayer

LSL是一个系统，用于在研究实验中统一收集测量时间序列，处理网络，时间同步，（近）实时访问以及可选的集中收集，查看和磁盘记录数据。
LSL包括：
核心传输库（liblsl）及其语言接口（C，C ++，Python，Java，C＃，MATLAB）。该库是通用的和跨平台的（Win / Linux / MacOS / Android / iOS，x86 / amd64 / arm），是项目的核心。
基于库构建的一套工具，包括录制程序，文件导入程序和应用程序，这些应用程序可以从实验室网络上的一系列采集硬件（例如音频，EEG或动作捕捉）中获取数据。
这里有关于LSL的介绍讲座/演示： http://www.youtube.com/watch?v=Y1at7yrcFW0 （基于脑电图的脑机接口在线课程的一部分）。
这只是一个包含所有项目的子模块的存储库。根据您的需要，您应该下载可立即使用的二进制包或仅克隆您需要的存储库。、
您可以在我们的FTP站点上找到旧版本：ftp://sccn.ucsd.edu/pub/software/LSL/
这些版本已过期。我们正在努力实现自动构建和部署系统，但尚未准备好。

API介绍

liblsl库提供以下抽象供客户端程序使用：

Stream Outlets：用于在实验室网络上提供时间序列数据流。数据被逐个样本或逐块地推送到插座中，并且可以包括单通道或多通道数据，规则或不规则采样率，具有统一的值类型（整数，浮点数，双精度数，字符串）。流可以具有任意XML元数据（类似于文件头）。通过创建出口，流对一组计算机（由网络设置/布局定义）可见，其中人们可以通过创建入口来订阅它。

Resolve functions：这些功能允许根据基于内容的查询（例如，按名称，内容类型或元数据查询）解析实验室网络中存在的流。服务发现功能不依赖于zeroconf等外部服务，而是旨在大幅简化数据收集网络设置。

Stream Inlets：用于从连接的插座接收时间序列数据。允许从提供程序检索样本（按顺序，具有可靠的传输，可选的类型转换和可选的故障恢复）。除了样本之外，还可以获取元数据（作为XML blob或通过小型内置DOM接口）。

Built-in clock内置时钟：允许对传输的样本加盖时间戳，以便它们可以相互同步。请参阅Time Synchronization。

可靠性

库实现了以下可靠性功能（透明地）：

传输继承了TCP的可靠性，是面向消息的（分区为样本）和类型安全的。

该库提供从应用程序或计算机崩溃中自动故障恢复，以最大限度地减少数据丢失（可选）; 这样就可以在录制过程中更换计算机，而无需重新启动数据收集。

数据在发送方和接收方都缓冲（具有可配置和任意大的缓冲区），以容忍间歇性网络故障。

传输类型安全，并根据需要支持类型转换。

Time Synchronization

实验室流层具有内置的同步时间功能，可用于所有记录的数据，旨在在本地计算机网络上实现亚毫秒精度。该工具用于为同步数据收集提供开箱即用的支持，但不排除使用用户提供的替代时间戳，例如商业定时中间件或高质量时钟。
内置时间同步是在广泛部署的网络时间协议（NTP）之后设计的，并在LSL库中实现。

文件格式

传输API本身不支持或提供特定的文件格式，但提供的记录程序（LabRecorder）记录为XDF文件格式（可扩展数据格式）。 XDF与实验室流层同时设计，支持LSL的完整功能集（包括多流容器文件，每个流任意大的XML头，所有样本格式以及时间同步信息）。

开发信息

更多开发信息见开发手册：https://github.com/sccn/labstreaminglayer/blob/master/doc/BUILD.md （本手册描述了为Windows、Mac OS X和Linux从源代码构建liblsl和应用程序的过程。因为liblsl是跨平台的(它是用标准c++编写的，并使用一些boost库)，所以这个过程应该非常简单。以下各段将逐步说明在所有三个平台上的构建过程。）
该发行版包括C，C ++，Python，MATLAB，Java和C＃中的一系列代码示例，包括一些非常简单的发送器和接收器程序，以及一些相当广泛的演示应用程序。

有关示例程序，API文档链接以及常规编程技巧，技巧和常见问题的更广泛概述，请参阅ExampleCode。：https://github.com/labstreaminglayer/App-Examples/

如何获得支持

如果您在使用LSL时遇到问题，您可以采取一些措施来获得帮助。首先，查看Wiki，尤其是常见问题。其次，在此存储库和存档的存储库中搜索问题列表，包括已关闭的问题。如果找不到所需内容，则可以创建新问题。尝试尽可能多地包含有关您的设备（如果适用），计算环境（操作系统，处理器架构），到目前为止测试的内容的信息，并提供日志或其他错误消息（如果有）。如果您创建了新问题，请回复后续问题，并确保在问题解决后关闭它。
您也可以尝试加入Slack上的LabStreamingLayer #users频道。有人可能会通过对话找到问题的根源。

Building LSL

此存储库仅包含一般项目结构和对liblsl C / C ++库的引用各种语言绑定应用程序以从多种类型的设备（包括模板示例）和[LabRecorder]流式传输数据(https://github.com/labstreaminglayer/App-LabRecorder)

  labstreaminglayer
  ├── Apps
  │   ├── AMTI ForcePlate
  │   ├── Examples
  │   ├── LabRecorder
  │   ├── [several other apps]
  │   └── Wiimote
  └── LSL
    ├── liblsl
    │   ├── external
    │   ├── include
    │   ├── lslboost
    │   ├── project
    │   ├── src
    │   └── testing
    ├── liblsl-Matlab
    ├── liblsl-Python
    └── liblsl-Java

更新、添加所有子模块。
windows上主要需要（非必须）
CMake(https://cmake.org/download/)（至少3.5以上）
Qt5(https://www.qt.io/download-open-source/)
Boost(https://sourceforge.net/projects/boost/files/boost-binaries/)

Build instructions构建指令

首先建立环境，见 build-environment.md。

构建环境

安装vs2017，cmake，liblsl包含了boost所以不用另外安装。
Boost库有两种风格:只支持头文件的库和编译的库。
header-only libraries你可以下载源文件并用cmake指向他(-DBOOST_ROOT=path/to/boost)
compiled libraries你要么自己编译它(不推荐)或下载预编译的二进制文件（这必须匹配您的编译器版本和处理器架构）
每个应用程序构建说明都应该准确地告诉您需要哪些boost库
Windows: 安装precompiled binaries
选择版本匹配您的编译器版本和处理器架构(probably 64-bit).
您可以找到vs编号和编译器版本之间的映射 here.
如果你的boost版本过新那cmake有可能找不到。
CMake内置了如何在boost库中查找模块及其依赖项的说明。
这些说明与特定版本的boost相关联。如果发布了新版本的boost，那么旧的cmake将没有关于如何加载其模块的说明。解决此问题的最简单方法是使用与最兼容的最新版本的boost和cmake的最新版本。
在撰写本文时，CMake 3.10支持Boost 1.65.1

构建指令有三种构建类型:

in tree builds build the LSL library and all apps you explicitly enable.构建LSL库和显式启用的所有应用程序。
This is probably what you want.
out of tree builds build only a single app and require you to have a prebuilt LSL library and the exported build configuration (LSLConfig.cmake).只构建一个应用程序，并要求您有一个预构建的LSL库和导出的构建配置
semi out of tree builds build only a single app and liblsl alongside it.只构建一个应用程序和liblsl

In tree builds (recommended)

1.克隆库(git clone --recurse-submodules https://github.com/labstreaminglayer/labstreaminglayer.git)
1.创建构建目录
您可以使用GUI文件管理器来完成这一部分，也可以通过下面的命令行来完成。打开终端/shell/命令提示符并切换到labstreaminglayer目录
如果构建目录已经存在就删除它。
Windows: rmdir /S build;Others: rm -Rf build
Create the ‘build’ dir: mkdir build
1.使用cmake配置项目
-选择1：用GUI
-打开终端/shell/命令提示符并切换到labstreaminglayer目录。
-如果您之前删除了“build”目录：mkdir build
- cd build
- cmake-gui .. (GUI) or ccmake .. (terminal) on other platforms.
做一个初始Configure，如果被提问，同意创建目录。
选择你的编译器并点击finish
使用该界面可以构建您想要使用的apps。
如有必要，更改选项或添加选项/路径(Add Entry)
- Qt if the guessed path is not right
- Boost 如果默认值不正确
- 复制可重新分发二进制文件的路径(CMAKE_INSTALL_PREFIX)
- Build type (CMAKE_BUILD_TYPE, either Release or Debug).
You can change this in Visual Studio later.
- 再次点击 Configure 确认修改.
单击Generate创建build files/ Visual Studio Solution file

选择 2 - 使用命令行.
- 打开终端窗口，或者在Windows上显示’Developer Command Prompt for VS2015’(or 2017, as needed)
- 使用适当的commandline options运行cmake
选择3 -vs2017或更高版本
- 在vs中打开CMakeLists.txt(File->Open->CMake)
- 更改cmake设置通过CMake->Change CMake Settings
  - 详见Common Cmake Settings
- 从下拉菜单(x64-Debug, x64-Release)更改所选项目。这将触发CMake使用新变量重新配置。

1.创建项目

如果在MSVC（微软（MS）的VC运行库）中使用cmake生成项目文件
- 仍然在cmake-gui，点击Open Project，或者如果没有留在cmake-gui，请双击创建的build / LabStreamingLayer.sln
- 将目标更改为Release
- 在解决方案资源管理器中，右键单击INSTALL并单击build。
如果使用命令行
- 开始构建进程(cmake --build . --config Release --target install*)
如果使用vs2017 内置的CMake实用工具
- Use the CMake menu > Install > LabStreamingLayer

这将在CMAKE_INSTALL_PREFIX指定的文件夹中创建一个分布树*类似于：

‘installed’ directory tree

  ├── AppX
  │   ├── AppX.exe
  │   ├── liblsl64.dll
  │   ├── Qt5Xml.dll
  │   ├── Qt5Gui.dll
  │   └── AppX_configuration.ini
  ├── AppY
  │   ├── AppY.exe
  │   ├── AppY_conf.exe
  │   ├── liblsl64.dll
  │   └── example.png
  ├── examples
  │   ├── CppReceive.exe
  │   ├── CppSendRand.exe
  │   ├── SendDataC.exe
  │   ├── liblsl64.dll
  └── LSL
    ├── cmake
    │   ├── LSLCMake.cmake
    │   ├── LSLConfig.cmake
    │   └── [snip]
    ├── include
    │   ├── lsl_c.h
    │   └── lsl_cpp.h
    └── lib
      ├── liblsl64.dll
      ├── liblsl64.lib
      └── lslboost.lib

在Windows上，库被复制到（并搜索）可执行文件夹中。
生成的文件夹LSL包含三个子文件夹：

cmake包含导出的构建配置（LSLConfig.cmake）可用于 out of tree builds中导入库。
include包含C(lsl_c.h)和C ++(lsl_cpp.h)程序的include头。
lib包含库文件。要运行程序，您需要liblslXY.dll（Windows）或.so（Linux）或.dylib（MacOS）。

Regarding the `install` target关于安装目标

CMake在构建树中放置构建的二进制文件以及构建副产品，该构建树应该与源目录分开。
要将只需要的文件（以及它们所依赖的其他库文件）复制到您可以与同事或另一台PC共享的文件夹，您需要“安装”它们。
这并不意味着在传统意义上“安装”它们（即，在Linux / OS X上使用程序包管理器或Windows安装程序），而只是将它们复制到单独的文件夹并修复二进制文件中的一些硬编码路径。

Out of tree builds

不包含整个labstreaminglayer目录，只有一个应用程序。一个最小化例程OutOfTreeTest
构建LSL库只要一两分钟，所以推荐还是用in tree builds。

Common CMake Options

cmake构建系统有很多选择。
如果您使用的是CMake GUI，那么在生成项目/ makefile之前，将向您显示这些选项。
如果您使用的是命令行，则默认选项将仅为liblsl生成makefile。
如果要使用命令行为IDE生成项目，或者要生成构建LSL应用程序的项目，则必须为cmake命令提供一些可选参数。

Generator: -G <generator name>.
Apps: -DLSLAPPS_<AppName>=ON.
- -DLSLAPPS_LabRecorder=ON
- -DLSLAPPS_XDFBrowser=ON
- -DLSLAPPS_OpenVR=ON
- TODO: 每个应用程序都应该在其自述文件中轻松访问其cmake选项。
- TODO: 每个应用程序都应在其自述文件中指定其自己的附加选项。
App dependencies应用程序依赖关系 (required by some apps). See build environment docs for more info.
- -DQt5_DIR=<path/to/qt/binaries>/lib/cmake/Qt5
- -DBOOST_ROOT=<path/to/boost>
  - liblsl comes with its own boost used by itself, 但是一些APP要求 ‘normal’ boost也很常见.
Install root (see below)
- Not necessary for in-tree builds.

一些cmake命令的例子：

Chad’s Windows build: cmake .. -G "Visual Studio 14 2015 Win64" -DLSL_LSLBOOST_PATH="lslboost" -DQt5_DIR=C:\Qt\5.11.1\msvc2015_64\lib\cmake\Qt5 -DBOOST_ROOT=C:\local\boost_1_67_0 -DLSLAPPS_LabRecorder=ON -DLSLAPPS_XDFBrowser=ON -DLSLAPPS_OpenVR=ON

在VS 2017中配置CMake选项

如果您使用的是Visual Studio 2017的内置CMake工具，则默认选项将用于配置项目。
要设置任何变量，您必须编辑文件。使用CMake菜单>更改CMake设置> LabStreamingLayer。
这将打开一个json文件。对于每个感兴趣的配置，添加一个带有键/值对列表的’variables’条目。
For example, under "name": "x64-Release", and immediately after "ctestCommandArgs": "" add the following:

,
      "variables": [
        {
          "name": "Qt5_DIR",
          "value": "C:\\Qt\\5.11.1\\msvc2015_64\\lib\\cmake\\Qt5 "
        },
        {
          "name": "BOOST_ROOT",
          "value": "C:\\local\\boost_1_67_0"
        },
        {
          "name": "LSLAPPS_Examples",
          "value": "ON"
        },
        {
          "name": "LSLAPPS_LabRecorder",
          "value": "ON"
        },
        {
          "name": "LSLAPPS_Benchmarks",
          "value": "ON"
        },
        {
          "name": "LSLAPPS_XDFBrowser",
          "value": "ON"
        }
      ]

`LSL_INSTALL_ROOT`

要在单独的CMake构建中导入LSL库，您需要将绝对路径设置为'LSL_INSTALL_ROOT变量中的’installed’ LSL directory(e.g. -DLSL_INSTALL_ROOT=C:/LSL/build/install/)或将绝对路径添加到’installed’ LSL directory的子文件夹LSL/cmake中CMAKE_PREFIX_PATH
(list(APPEND CMAKE_MODULE_PATH "C:/path/to/LSL/build/install/cmake/")
CMake查找文件${LSL_INSTALL_ROOT}/LSL/share/LSL/LSLConfig.cmake，所以确保你的LSL_INSTALL_ROOT中包含了文件the previous section
默认情况下，应该查看../../LSL/liblsl/build/install，如果你在每个子模块中有一个build文件夹(LSL/liblsl/build,
Apps/Examples/build etc.)并首先安装liblsl，CMake自动找到liblsl。

多平台构建

如果您没有多台具有不同构建环境的PC和Mac来测试您的更改，您可以使用CI在多个平台上编译代码，并为愿意的测试人员提供二进制文件。

Note about architectures / binaries架构/二进制文件

也称为"Which liblsl.so / liblsl.dll do I need?
Liblsl被编译为二进制文件，用于组合操作系统/ libc（几乎相同）和处理器体系结构。
ost二进制文件包括名称中的本地字大小（以位为单位），以及提示文件扩展名中二进制文件所用的平台，
例如 liblsl * 32 * .dll用于32位Windows dll，liblsl * 64 * .so用于64位
Linux / Android库或liblsl64.dylib用于64位OS X dylib。

CI系统自动构建以下组合：

x86 Windows DLL (liblsl32.dll)
x64 Windows DLL (liblsl64.dll)
x64 Linux shared object (liblsl64.so)
x64 OS X shared object (liblsl64.dylib)
Android也有.so共享对象，但使用不同的工具链构建，因此它们不能与常规Linux的.so文件互换。
计划在CI系统上为以下架构构建Android二进制文件：arm64-v8a，armeabi，mips64，x86_64。