远程模块¶

什么是远程模块¶

远程模块允许任何人 extend the functionalities of OTB 而不是核心项目库的一部分。它们可以拥有与主OTB存储库不同的许可证。这些模块就像普通模块一样，只是它们不是分布在OTB源代码中。在某些情况下(依赖关系、官方接受流程等)，我们还可以在官方独立二进制文件中分发您的远程模块。

可用模块列表¶

Official OTB modules

“官方”远程模块只是我们认为对用户特别有用的常规模块。其中一些是以二进制包的形式提供的，因此您不需要自己构建它们。

DiapOTB ：通过突出SAR图像之间的差异来分析潜在事件

存储库：https://gitlab.orfeo-toolbox.org/remote_modules/diapotb

许可证：阿帕奇许可证2.0

描述：差分合成孔径雷达干涉测量(DInSAR)技术依赖于对在不同时间拍摄的地球表面同一部分的两幅合成孔径雷达图像进行处理。目的是分析潜在事件(地震、破坏、…)通过突出不同的合成孔径雷达图像。DInSAR涉及一套工具，如创建变形网格、联合配准或建立干涉图。Orfeo工具箱远程模块DiapOTB包含所有必要的步骤，并允许启动完整的DInSAR链。该模块已用于Sentinel-1数据，结果令人满意。此模块是Diapason Tool中的一个端口，集成在 ESA GeoHazards TEP 。

otb-mosaic ：图像拼接

存储库：https://github.com/remicres/otb-mosaic

作者：雷米·克雷森

许可证：CeCILL-B

描述：这个模块提供了一个专门用于图像马赛克的应用程序，提供了几种可用的合成方法。自7.0.0版起，此模块现已成为OTB的一部分

otb-bv ：生物物理变量的估计

存储库：https://gitlab.orfeo-toolbox.org/jinglada/otb-bv

作者：乔迪·英格拉达

许可证：GNU Affero通用公共许可证3.0版

描述：OTB-BV项目允许使用机器学习非线性回归从遥感图像中估计生物物理变量(LAI、fAPAR、fCover)，以反演PROSPECT+SAIL模型。

Phenotb ：从时间配置文件中提取物候信息

存储库：https://gitlab.orfeo-toolbox.org/jinglada/phenotb/

作者：乔迪·英格拉达

许可证：GNU Affero通用公共许可证3.0版

描述：这个模块实现了几种算法，允许从时间配置文件中提取物候信息。这些时间剖面应代表植被状况，例如NDVI、LAI等。

otbFFSforGMM ：基于混合高斯模型的大规模特征选择

存储库：https://github.com/Laadr/otbFFSforGMM

作者：阿德里安·拉格朗日

许可证：阿帕奇

描述：此模块实现了一种使用高斯混合模型执行快进特征选择的方法，用于高维遥感图像的分类。该算法在以下文件https://hal.archives-ouvertes.fr/hal-01382500.中进行了描述

GRM ：通用区域合并分割

存储库：http://tully.ups-tlse.fr/lassallep/grm/tree/master

作者：皮埃尔·拉萨勒

许可证：GPL v3

描述：该模块提供了GRM OTB应用程序，用于对卫星图像进行多尺度区域合并分割。有三个局部齐性判据可用：Baatz&Schäpe判据、完全Lambda调度判据和简单欧氏距离判据。这个模块是由Pierre Lassalle贡献的，他还提供了学习如何使用库的教程。

SertitObject ：面向对象的图像分析

存储库：https://github.com/sertit/SertitObject

作者：SERTIT-斯特拉斯堡大学

许可证：CeCILL-B

描述：此模块提供两个OTB应用程序，专门用于面向对象的图像分析。

Temporal gap-filling ：在图像时间序列中进行时间填补

存储库：http://tully.ups-tlse.fr/jordi/temporalgapfilling.git

作者：乔迪·英格拉达

许可证：GNU Affero通用公共许可证3.0版

描述：该模块提供了用于图像时间序列中的时间间隔填充的类和一个应用程序(提供了线性和样条内插器)。

Community modules

Feature selection ：

存储库：https://github.com/boussaffawalid/FeatureSelection

作者：瓦利德·布萨法和内斯林·切哈塔

许可：保留所有权利(未许可授予更多权利，版权完全适用，未经著作权人明确和事先授权，不得使用此组件)。

描述：此模块包含一个基于 FST3Lib 。

OTBTensorflow (otbtf) ：通用、多用途深度学习框架，针对遥感图像处理

存储库：https://gitlab.irstea.fr/remi.cresson/otbtf

作者：雷米·克雷森

许可证：阿帕奇许可证2.0

描述：Orfeo工具箱的这个远程模块提供了一个通用的、多用途的深度学习框架，目标是遥感图像处理。它包含一组在内部调用TensorFlow的新流程对象，以及一组面向用户的应用程序，用于对真实世界的遥感图像执行深度学习。应用程序可用于从Python或C++API构建OTB管道。

安装和使用¶

Build possibilities

您的远程模块可以构建在OTB源代码树内部，也可以作为外部CMake项目与现有的OTB安装一起构建。

Building against a build tree

在这种情况下，您有 compiled OTB from source ，cmake配置将在OTB构建目录中完成。

请注意，有两种编译方法：
- Build as a module inside OTB 在这种情况下，构建文件将作为其他模块写入OTB构建树。主要好处是，这将使用您的新模块丰富当前的OTB构建，但您需要对构建目录具有写入权限。对于这种类型的构建，cmake配置很简单，请参见下面的 compilation 各章
- Build as a standalone CMake project 在这种情况下，构建文件将保留在模块构建文件夹中。这个构建完全独立于构建(或安装)目录，但该模块不会被识别为OTB模块(仍然可以使用它的二进制文件和库)。
此行为由cmake选项控制 OTB_BUILD_MODULE_AS_STANDALONE ，这在默认情况下是关闭的(因此是第一行为)。为了将其构建为独立的，还需要设置其他cmake选项，如下所述。
Building against an installed OTB
在这种情况下，只有第二种行为(作为独立构建)可用。这需要为构建指定cmake选项：
- 使用将模块设置为独立构建 OTB_BUILD_MODULE_AS_STANDALONE=ON
- 设置以下选项 -DCMAKE_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=0 (见下文)
- 使用变量设置OTB安装目录 OTB_DIR
- 为您的库设置安装文件夹 CMAKE_INSTALL_PREFIX=/theModulePath/install
- 设置运行时路径 RPATH 库的文件放到安装/lib文件夹中 DCMAKE_INSTALL_RPATH=/theModulePath/install/lib
- 告诉cmake使用链接路径设置运行时路径： CMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE (允许避免修改LD_LIBRARY_PATH)

OTB二进制文件是使用选项编译的 GLIBCXX_USE_CXX11_ABI 设置为 0 。这就是为什么您必须使用相同的选项构建远程模块。如果不这样做，您将在运行应用程序时遇到“Symbol Not Found”错误消息。

Compilation and Installation

如果您选择 inside OTB build ，您的模块将与OTB项目的其余部分一起构建。要将模块添加到编译过程中，您有两种选择：
- 使用OTB自动检索您要构建的官方远程模块(不适用于社区/自我远程模块)。您所要做的就是调用OTB构建目录中的cmake配置来激活 Module_TheModuleName
- 自己克隆模块(如果您使用社区模块或您自己的模块，则需要)，并将文件夹复制到 OTBSource/Modules/Remote ，这将在CMake配置中触发一个名为 Module_TheModuleName 这就是 OFF 默认情况下。
打开终端并运行：

cd /PathToOTB/build
cmake -DModule_TheModuleName=ON
make install

模块的应用程序将安装在与OTB应用程序相同的文件夹中

如果您选择 OTB install build ：

mkdir /Path/to/Module/build && cd /Path/to/Module/build
cmake -DOTB_DIR=/PathTo/OTB/install -DOTB_BUILD_MODULE_AS_STANDALONE=ON
-DCMAKE_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=0
-DCMAKE_INSTALL_PREFIX=/theModulePath/install -DCMAKE_INSTALL_RPATH=/theModulePath/install/lib
-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE ../
make install

这些应用程序将安装在 /theModuleInstallFolder/lib 二进制文件将在 /theModuleInstallFolder/bin

Usage

为. inside OTB build ，验证是否设置了OTB环境变量，并调用您的应用程序：

otbcli_MyModuleApp arg1 ... argX

为. OTB install build ，您必须添加您的 /theModuleInstallFolder/lib 设置为变量OTB_APPLICATION_PATH，并且 theModuleInstallFolder/bin 到路径：

export OTB_APPLICATION_PATH=/theModuleInstallFolder/lib:$OTB_APPLICATION_PATH
export PATH=/theModuleInstallFolder/bin:$PATH

我们强烈建议 adding these exports in your .bashrc 为了使您的应用程序在系统中可用

编写您自己的远程模块¶

本节将逐步指导您创建自己的远程模块。首先，您可以派生我们的远程模块模板项目： Remote Module Template 。每个模块由不同的组件组成，如以下各节所述。

The otb-module.cmake file

此文件为必填项。它遵循CMake语法，有两个用途：

声明对其他模块的依赖关系，
提供模块用途的简短说明。

这些目的可通过单个CMake宏调用来实现：

otb_module(TheModuleName DEPENDS OTBModule1 OTBModule2 ... OTBModuleN DESCRIPTION "A description string")

Note ：您可以使用关键字 TESTDEPENDS 声明仅适用于测试的模块依赖项。

The CMakeLists.txt file

这个 CMakeLists.txt 文件是必填项。它只包含几样东西。首先，它使用模块的名称声明一个新的CMake项目：

project(OTBTheModuleName)

其次，如果模块包含库(参见下面的src文件夹部分)，它将初始化TheModuleNameLIBRARIES CMake变量(如果您的模块只包含头文件或模板代码，请跳过此行)：

set(OTBTheModuleName_LIBRARIES OTBTheModuleName)

通过将源代码复制到目录中，可以在OTB源代码树中构建远程模块 Module/Remote 或针对现有的OTB构建树(请注意，它不适用于OTB的安装版本)。

下面的配置将处理这两种情况，并负责模块的所有CMake管道：

if(NOT OTB_SOURCE_DIR)
  find_package(Boost REQUIRED COMPONENTS filesystem serialization)
  find_package(OTB REQUIRED)
  list(APPEND CMAKE_MODULE_PATH ${OTB_CMAKE_DIR})
  # The Python interpreter is needed for Python tests
  set(Python_ADDITIONAL_VERSIONS "3")
  find_package( PythonInterp REQUIRED)
  include(UseOTB)
  include(OTBModuleExternal)
else()
  otb_module_impl()
endif()

整个文件应如下所示：

cmake_minimum_required(VERSION 3.10.0)
project(OTBTheModuleName)
set(OTBTheModuleName_LIBRARIES OTBTheModuleName)

if(NOT OTB_SOURCE_DIR)
  find_package(Boost REQUIRED COMPONENTS filesystem serialization)
  find_package(OTB REQUIRED)
  list(APPEND CMAKE_MODULE_PATH ${OTB_CMAKE_DIR})
  # The Python interpreter is needed for Python tests
  set(Python_ADDITIONAL_VERSIONS "3")
  find_package( PythonInterp REQUIRED)
  include(UseOTB)
  include(OTBModuleExternal)
else()
  otb_module_impl()
endif()

Remarque: the command find_package(Boost) is called before
find_package(OTB). This is due to the fact that FindBoost.cmake is
integrated to cmake, so it is better to use the official command
rather than the one integrated to the OTB.

The include folder

Include文件夹将包含您的所有标题 (*.h 文件)和模板方法文件 (*.hxx 或 *.hxx )。它不需要任何额外的文件(特别是不需要CMakeLists.txt文件)。

The src folder

Src文件夹包含模块的内部实现：

它通常包含将编译到库中的CXX源文件。
它可以包含仅在模块的实现文件中使用的类的头文件。Src文件夹中的任何头文件都不会安装，并且不能用于其他模块，具体取决于您的模块。

如果您的模块由纯模板代码组成，则根本不需要src文件夹。

如果存在，src文件夹需要CMakeLists.txt文件。

CMakeLists.txt文件的第一部分是经典的，因为它构建并链接了库：

set(OTBTheModuleName_SRC
    sourceFile1.cxx
    sourceFile2.cxx
    sourceFile3.cxx
    ...
    sourceFileN.cxx)

add_library(OTBTheModuleName ${OTBTheModuleName_SRC})

target_link_libraries(OTBTheModuleName ${OTBModule1_LIBRARIES} ${OTBModule2_LIBRARIES} ... ${OTBModuleN_LIBRARIES})

Notes ：

库名称应与设置CMake变量TheModuleName_LIBRARIES时根CMakeLists.txt中声明的名称匹配。
链接库应该与根otb-mode.cmake文件中声明的模块依赖项相匹配。

CMake代码的最后一行负责安装说明：

otb_module_target(OTBTheModuleName)

整个CMakeLists.txt文件应该如下所示：

set(OTBTheModuleName_SRC
    sourceFile1.cxx
    sourceFile2.cxx
    sourceFile3.cxx
    ...
    sourceFileN.cxx)

add_library(OTBTheModuleName ${OTBTheModuleName_SRC})

target_link_libraries(OTBTheModuleName ${OTBModule1_LIBRARIES} ${OTBModule2_LIBRARIES} ... ${OTBModuleN_LIBRARIES})

otb_module_target(OTBTheModuleName)

The app folder

App文件夹包含模块附带的应用程序代码。如果您的模块没有应用程序，则不需要应用程序文件夹。

Notes ：如果您的模块包含应用程序(和应用程序文件夹)，请不要忘记将ApplicationEngine添加到otb-mode.cmake文件中列出的依赖项中。

除了应用程序源代码之外，app文件夹还应该包含一个CMakeLists.txt文件，如下所示。

对于每个应用程序，需要对bcreateapp进行一次调用：

otb_create_application(
  NAME           TheModuleApplication1
  SOURCES        TheModuleApplication1.cxx
  LINK_LIBRARIES ${OTBModule1_LIBRARIES} ${OTBModule2_LIBRARIES} ... ${OTBModuleN_LIBRARIES})

The test folder

此文件夹包含模块的测试。如果您的模块中没有测试(不推荐，您不需要它)。

测试文件夹应该包含测试的源文件，以及CMakeLists.txt文件。该文件将包含以下内容。

首先，指出此文件夹包含测试。

otb_module_test()

然后，构建测试驱动程序：

set(OTBTheModuleNameTests
    testFile1.cxx
    testFile2.cxx
    ...
    testFileN.cxx)

add_executable(otbTheModuleNameTestDriver ${OTBTheModuleNameTests})

target_link_libraries(otbTheModuleNameTestDriver ${OTBTheModuleName-Test_LIBRARIES})

otb_module_target_label(otbTheModuleNameTestDriver)

最后，您可以添加您的测试：

otb_add_test(NAME nameOfTheTest COMMAND otbTheModuleNameTestDriver
             --compare-image ${EPSILON_8} ... # baseline comparison if needed
             nameOfTheTestFunction
             testParameters)

如果您的模块在app文件夹中包含一个或多个应用程序，则还应该在test文件夹中为它们编写测试。运行应用程序测试很容易使用帮助器宏otbtest应用程序完成：

otb_test_application(NAME   nameofApplication1Test1
                      APP  TheModuleApplication1
                      OPTIONS -in1 ${INPUTDATA}/input1.tif
                              -in2 ${INPUTDATA}/input2.tif
                              -out ${TEMP}/nameofApplication1Test1_result.tif
                      VALID   --compare-image ${EPSILON_8}
                              ${BASELINE}/nameofApplication1Test1_result.tif
                              ${TEMP}/nameofApplication1Test1_result.tif)

要添加一个 test executed by a Python script 使用OTB应用程序绑定：

set(TEST_DRIVER otbTestDriver
    --add-before-env OTB_APPLICATION_PATH $<TARGET_FILE_DIR:otbapp_EmptyApp> )

otb_add_test(NAME otbEmptyScriptTest
  COMMAND ${TEST_DRIVER} Execute ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/EmptyScript.py)

总体CMakeLists.txt应该如下所示：

otb_module_test()

set(OTBTheModuleNameTests
    testFile1.cxx
    testFile2.cxx
    ...
    testFileN.cxx)

add_executable(otbTheModuleNameTestDriver ${OTBTheModuleNameTests})

target_link_libraries(otbTheModuleNameTestDriver ${OTBTheModuleName-Test_LIBRARIES})

otb_module_target_label(otbTheModuleNameTestDriver)

otb_add_test(NAME nameOfTheTest COMMAND otbTheModuleNameTestDriver
             --compare-image ${EPSILON_8} ... # baseline comparison if needed
             nameOfTheTestFunction
             testParameters)

otb_test_application(NAME otbEmptyAppTest
                 APP  EmptyApp
                 )

在模块中使用Python OTB和GDAL依赖项¶

如果您的模块有一个使用OTB Python绑定的Python部分，您应该会在二进制版本中遇到一些问题，下面是如何修复它：

首先在您的平台上安装OTB。请参阅 related documentation 要在系统上安装OTB，请执行以下操作。

然后，您需要一个与您的OTB版本兼容的GDAL版本。

如果您使用的是OTB二进制分发版，则需要 patch 提供的文件。
- 为此，您可以在OTB源码树中找到这个简化的通用版本的gdal-config : Documentation/CookBook/Scripts/gdal-config. Just drop it into the bin/ directory where you've extracted OTB. This will permit pip install gdal==vernum 才能正常工作。
- 你还必须 patch otbenv.profile 至 insert OTB lib/ 目录的开头 $LD_LIBRARY_PATH 。这将允许 python3 -c 'from osgeo import gdal' 才能正常工作。
  # For instance, type this, once! echo 'LD_LIBRARY_PATH="${CMAKE_PREFIX_PATH}${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"' >> otbenv.profile

如果你已经从源码中编译了OTB，你应该不会有这种麻烦。

共享您的模块¶

要使您的远程模块可供其他人使用，您应该首先将模块代码托管在公开可用的Git存储库中。如果您无法访问Git服务器，BitBucket或GitHub可以为您提供这项服务。然后，您应该提供一个名为 TheModuleName.remote.cmake 包含在OTB源代码树的模块/Remote文件夹中。

该文件应包含以下内容：

# Contact: Author name <author email address>

otb_fetch_module(TheModuleName
  "A description of the module, to appear during CMake configuration step"

  GIT_REPOSITORY http_link_to_a_git_repository_hosting_the_module
  GIT TAG the git revision_to_checkout
)

此文件应与您的远程模块纳入建议电子邮件一起提供给OTB社区列表：远程模块的接受将提交给OTB-Developers投票。如果接受，您的CMake文件将被放入OTB源代码树中的模块/Remote文件夹。

Important Note ：引入新的第三方依赖关系的远程模块不会包含在二进制程序包中。

在OTB发布过程中，所有符合远程模块发布策略的模块都将与标准模块一起打包。

在以下情况下，可以从模块/远程删除远程模块(这只需要删除描述它的CMake文件)：

它不再符合远程模块接受政策(在这种情况下，决定提交表决 OTB's forum ),

远程模块的作者要求删除它。

Remote module acceptance policy

为了让您的模块被接受为官方远程模块，您应该遵守以下规定：

远程模块源代码应托管在公开可用的Git存储库中

应识别远程模块的作者并将其注册到 OTB's forum

远程模块的作者接受开发者或用户就其模块的问题联系(尽最大努力)，

远程模块源代码应尽可能符合OTB风格，

远程模块源代码应该使用doxygen标签进行记录，

远程模块应提供最少的测试集以确保构建模板代码和基本的非回归测试，

远程模块应附带某种形式的文档(网站、出版物、自述文件...)

远程模块不应嵌入任何第三方软件的代码(除非作者给出了强有力的论据，在这种情况下可以例外)，

远程模块应尽可能避免依赖新的第三方，

远程模块作者应是版权所有者，并遵守任何第三方的许可，而第三方应遵守OTB许可的条款(将由PSC审查)

远程模块的作者应提供要添加到OTB网站上的远程模块的小说明。

无论如何，内部模块都不应该依赖远程模块。

Remote module release policy

在OTB发布过程中，如果存在仪表板提交并显示远程模块，则远程模块将包含在源代码和二进制程序包中：

在所有平台上构建

通过参考平台上的所有测试

在其余平台上没有任何测试崩溃(即核心转储失败或内存问题)

远程模块在发布候选版本时遵守远程模块验收策略

开发人员将在发布候选版本时通知远程模块作者现有问题。如果到最终发布日期的3天前，上面列出的一些问题仍然存在，远程模块将从发布源代码和二进制包中删除。

使用持续集成¶

我们鼓励您在模块开发过程中使用CI平台。

在远程模块模板中，我们提供了两个文件，允许将您的模块放在配置项上

Ci.cmake=>用于构建模块
Travis.yml=>由Travis-CI使用ci.cmake脚本调用cmake并启动测试

这些文件使您的模块能够使用Travis-CI，这是GitHub持续集成平台。如果您的存储库位于GitLab上，则可以创建 mirror of your repo to github

要修改travis.yml：使用 manual

您有两个选项可以在您的配置项中使用OTB：

从网站获取安装程序并将其安装在 install: Travis.yml的一部分。您必须将您的模块构建为独立模块

env:
  global:
    - OTB_URL=https://www.orfeo-toolbox.org/packages/archives/OTB
    - OTB_VER=7.2.0
    - OTB_OS=Linux64
    - OTB_PKG_EXT=run

install:
  - export OTB_PKG="OTB-${OTB_VER}-${OTB_OS}.${OTB_PKG_EXT}"
  - wget ${OTB_URL}/${OTB_PKG}
  - chmod +x ${OTB_PKG}
  - ./${OTB_PKG} --target xdk

script:
  - command to build and test your module here

构建包含OTB构建树的停靠器映像。在Travis中运行此停靠器映像，并根据此构建树构建模块

before_script:
  - docker pull YourOTBImage

script:
  - docker run -it YourOTBImage /bin/bash -c "ctest -VV -S ci.cmake"

在BEFORE SCRIPT部分，必须设置环境变量。为此，您可以在主模块文件夹中创建一个名为Activate_env.sh的脚本，其中包含：

export OTB_RESULT_DIR=/home/travis/build/yourName/yourModule/data/OutputTest
export OTB_DATA_DIR=/home/travis/build/yourName/yourModule/data
export PYTHONPATH=/OTB_InstallDir/lib/otb/python
export OTB_APPLICATION_PATH=/home/travis/build/yourName/yourModule/install/lib:/OTB_InstallDir/lib/otb/applications

在travis.yml中将其命名为：

before-script:
   - source activate_env.sh

您可以使用travis.yml中的一行测试您的模块：

script:
   - ctest -VV -S ci.cmake

该命令构建您的项目并启动测试。