Skip to content

Build instructions

Jump to bottom
Étienne Léger edited this page Jun 11, 2024 · 7 revisions

Dependencies

It is up to the user to build these libraries and place them in the lib directories, where MARIN can find them. The expected structure is:
./lib/common/libcommon.a
./lib/openIGTLink/libOpenIGTLink.a
./lib/processing/libprocessing.a
./lib/welsdec/libwelsdec.a
./lib/welsenc/libwelsenc.a

Configuration

Configuration files are placed in the configs folder. It is up to the user to set the desired parameters in those files to fit their specific network and mobile device.

iOS-specific build instructions:

Below is a step-by-step guide for compiling MARIN on an iPad. Is currently tested on the iPad Pro (12.9-inch) (5th generation) running iPadOS 17.1, using Xcode 15 (see notes below about qmake issue).

OpenIGTLink + OpenH264

On a Mac with Xcode installed, clone the OpenIGTLink project by executing the following commands within a base directory:

git clone https://github.com/openigtlink/OpenIGTLink.git
mkdir OpenIGTLink-build

Next, using CMake (3.23.1), configure the OpenIGTLink project with Xcode as the generator and with video streaming and H264 enabled: **

fig1

Be sure that the OpenH264_INCLUDE_DIR is pointing to the wels folder rather than the outdated svc folder. Then, within the ./OpenIGTLink-build directory, clone the openh264 repository and build it by executing the following commands:

cd OpenIGTLink-build/Deps
git clone https://github.com/cisco/openh264.git

Then, build the openh264 project for the OS and architecture of your target device (which in this case is an iPad Pro (12.9-inch) (5th generation)) as follows:

cd openh264
make OS=ios ARCH=arm64

At this points, the following libraries should have been created:

  • ./OpenIGTLink-build/Deps/openh264/libcommon.a
  • ./OpenIGTLink-build/Deps/openh264/libdecoder.a
  • ./OpenIGTLink-build/Deps/openh264/libencoder.a
  • ./OpenIGTLink-build/Deps/openh264/libopenh264.a
  • ./OpenIGTLink-build/Deps/openh264/libprocessing.a

Now, back in CMake, configure once again and generate the OpenIGTLink project. Verify that the Xcode project file ./OpenIGTLink-build/OpenIGTLink.xcodeproj was created and open it in Xcode. Select the OpenIGTLink project in the project navigator (left pane). From the drop down menu in the main pane, change the default ALL_BUILD target to the OpenIGTLink-lib project. Under Build Settings → Architectures, change the Base SDK to iOS and change Architectures to Standard Architectures (arm64, armv7). Plug your iPad to your Mac and ensure that the your are building the OpenIGTLink project on your iPad (c.f. top window of the main pane in the next figure which should read OpenIGTLink > Your iPad). Then, add the following Xcode projects:

  • ./OpenIGTLink-build/Deps/openh264/codec/build/iOS/common/common.xcodeproj
  • ./OpenIGTLink-build/Deps/openh264/codec/build/iOS/dec/welsdec/welsdec.xcodeproj
  • ./OpenIGTLink-build/Deps/openh264/codec/build/iOS/enc/welsenc/welsenc.xcodeproj
  • ./OpenIGTLink-build/Deps/openh264/codec/build/iOS/openh264/openh264.xcodeproj
  • ./OpenIGTLink-build/Deps/openh264/codec/build/iOS/processing/processing.xcodeproj

as subprojects by dragging the files in the left pane under the OpenIGTLink project. Your Xcode window should look like this:

fig2

Next, add the subprojects as target dependencies in the Build Phases of the OpenIGTLink target which you must select from the drop down menu in the main pane:

fig3

Then, for the OpenIGTLink, common, welsdec, welsenc, openh264, and processing projects and targets, change Targeted Device Families to iPad (with code number 2) and the iOS Deployment Target to the iOS version of your iPad (e.g. iOS 15.5) under Build Settings → Deployment:

fig4

Next,

  1. To the OpenIGTLink target, add the path ./OpenIGTLink-build/Deps/openh264/codec/api/wels to the Header Search Paths under Build Settings→Search Paths (if not already listed)
  2. To the common target, add the path ./OpenIGTLink-build/Deps/openh264/codec/common/inc to the Header Search Paths under Build Settings→Search Paths
  3. To the welsdec target, add the path ./OpenIGTLink-build/Deps/openh264/codec/decoder/core/inc to the Header Search Paths under Build Settings→Search Paths

Finally, validate all project settings in the Issues Navigator (default left pane) and select Product→Build from the Xcode interface. If all goes well (fingers crossed), the following libraries will be created:

  • ./OpenIGTLink-build/lib/Debug/libOpenIGTLink.a
  • ./OpenIGTLink-build/Deps/openh264/codec/build/IOS/common/build/Debug-iphoneos/libcommon.a
  • ./OpenIGTLink-build/Deps/openh264/codec/build/IOS/dec/welsdec/build/Debug-iphoneos/libwelsdec.a
  • ./OpenIGTLink-build/Deps/openh264/codec/build/IOS/enc/welsenc/build/Debug-iphoneos/libwelsenc.a
  • ./OpenIGTLink-build/Deps/openh264/codec/build/IOS/processing/build/Debug-iphoneos/libprocessing.a

Libyuv

An arm64 build of libyuv is provided with MARIN in the lib folder. If a custom build is required, here is a typical build procedure:

# uncomment if depot tools is not installed on your system
#git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
##replace path below to the location where depot tools is installed on your system
#export PATH=<PATH_TO_DEPOT_TOOLS>:$PATH

gclient config --name src https://chromium.googlesource.com/libyuv/libyuv
gclient sync
vim .gclient # or text editor of choice

Add “; target_os=[’ios’];” to the end of .gclient as follows:

fig5

Then, install Python on your system, run ../Applications/Python X.X/Install Certificates.command and execute the following:

gclient sync
cd src
gn gen out/Debug "--args=is_debug=true target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"arm64\""
ninja -C out/Debug libyuv

This will create the following libraries:

  • <PATH_TO_LIBYUV_SRC>/out/Debug/obj/libyuv_internal.a
  • <PATH_TO_LIBYUV_SRC>/out/Debug/obj/libyuv_neon.a

Building MARIN

Within a base directory ., clone the MARIN repository by **executing the following commands:

git clone https://github.com/AppliedPerceptionLab/MARIN.git
cd MARIN
mkdir lib
cd ..

Then, copy the libraries created in previous sections to MARIN/lib folder using the following commands:

# provided that all libraries have been created
mkdir *MARIN/lib/openIGTLink* && cp *OpenIGTLink-build/lib/Debug/libOpenIGTLink.a ****MARIN/lib/openIGTLink*
mkdir *MARIN/lib/common* && cp *OpenIGTLink-build/Deps/openh264/codec/build/IOS/common/build/Debug-iphoneos/libcommon.a ****MARIN/lib/common*
#mkdir *MARIN/lib/welsdec* && cp *OpenIGTLink-build/Deps/openh264/codec/build/IOS/dec/welsdec/build/Debug-iphoneos/libwelsdec.a ****MARIN/lib/welsdec*
mkdir *MARIN/lib/welsdec* && cp *OpenIGTLink-build/Deps/openh264/libdecoder.a ****MARIN/lib/welsdec/libwelsdec.a*
mkdir *MARIN/lib/welsenc* && cp *OpenIGTLink-build/Deps/openh264/codec/build/IOS/enc/welsenc/build/Debug-iphoneos/libwelsenc.a ****MARIN/lib/welsenc*
mkdir *MARIN/lib/processing* && cp *OpenIGTLink-build/Deps/openh264/codec/build/IOS/processing/build/Debug-iphoneos/libprocessing.a ****MARIN/lib/processing*

Then, in .*/MARIN/**MARIN.pro*** (starting on line 42), specify the local paths to *OpenIGTLink* and *OpenIGTLink-build*:*

INCLUDEPATH +=
../OpenIGTLink/Source
../OpenIGTLink/Source/VideoStreaming
../OpenIGTLink/Source/igtlutil
../OpenIGTLink-build
../OpenIGTLink-build/lib/Debug
../OpenIGTLink-build/Deps/openh264
../OpenIGTLink-build/Deps/openh264/codec
../OpenIGTLink-build/Deps/openh264/codec/api/wels \


Next, convert the .*/MARIN/**MARIN.pro*** file to an Xcode project file using the following command:

```bash
cd MARIN

#replace path below to the location where Qt is installed on your system
#Note: the command below is specific to the iOS operating system
<PATH_TO_QT_INSTALL>/5.15.2/ios/bin/qmake -spec macx-ios-clang MARIN.pro
(patch qmake first, see [https://bugreports.qt.io/browse/QTBUG-117225](https://bugreports.qt.io/browse/QTBUG-117225))

Open the ./MARIN/MARIN.xcodeproj Xcode project file and select the MARIN project in the project navigator (left pane). To the MARIN project, under Build Settings → Architectures, change the Base SDK to iOS and change all Architectures to Standard Architectures. Make sure that the same parameters are set for the MARIN target. Plug your iPad to your Mac and ensure that the your are building the OpenIGTLink project on your iPad (c.f. top window of the main pane in the next figure which should read MARIN > Your iPad).

Next, open the ./MARIN/MARIN.xcodeproj Xcode project file and select the MARIN project in the project navigator (left pane). Under Build Settings → Architectures, change the Base SDK to iOS and change all architectures to to Standard Architectures. Apply these same settings to the MARIN target. Then, plug your iPad device and ensure that you are building the MARIN project on your iPad (c.f. top window of the main pane in the next figure which should read MARIN > Your iPad).

fig6

Then, to the MARIN project, change Targeted Device Families to iPad (with code number 2) and the iOS Deployment Target to the iOS version of your iPad (e.g. iOS 15.5) under Build Settings → Deployment.

fig7

Also to the MARIN project, change Build Settings → Build Options → Enable Bitcode to No. Make sure that these changes also take effect on the MARIN target.

Next, set the desired network and mobile device parameters in the configs folder of MARIN.

In the Xcode interface, click on the hammer icon in the center pane (c.f. figure below) and change Legacy Build System (Deprecated) to New Build System (Default).

fig8

fig9

Finally, validate the project settings of MARIN in the Issues Navigator (default left pane), wait for Xcode to process all files (c.f. message left of hammer on the figure above) and select Product→Build from the Xcode interface. If Xcode complains about not being able to find certain files in MARIN/ which exists in that directory, proceed by selecting Product→Clean Build Folder in the Xcode interface and re-run Product→Build.

Clone this wiki locally