Introduction
In order for an Intel® RealSense™ application to be deployed correctly, the application’s installer will have to bundle the necessary application runtime components. To do this, the Intel® RealSense™ SDK provides a command-line mechanism built into the runtime redistributable packages to pre-bundle the specific SDK components that the application will need. The runtime redistributable serves as a master installer script that will then generate new runtime installer scripts to install the specified components. Those specific runtimes (that is, hand, blob, and so on) must be included with the main application installer. In addition, developers should know about the three distinct installation processes for their Intel RealSense applications:
Offline installation. The application and all its dependencies exist within a super-installer that is pre-installed by the original equipment manufacturer (OEM) or downloaded as a single package by the user.
Online installation. This is the model expected for Web-based applications and consists of a sequence of installation packages. A first package tests for compatibility, and if the application passes, a subsequent download occurs of an additional package containing the remaining dependencies.
SDK installation. This is what developers get from the Intel® Developer Zone for creating their Intel RealSense application. This is single super-installer that contains all the dependencies, many of which are not applicable to a specific product. The installation also contains the SDK documentation and code samples.
It is important that the shipping product not be redistributed with the SDK installation package. Doing so will create future incompatibilities with newer components distributed by other applications. In addition, the software license does not allow for redistribution of the Intel RealSense SDK. While the official SDK documentation describes the application deployment process in detail, this white paper is intended to summarize some of the key items that have previously been confusing for application engineers and ISVs.
Description of Runtime Installers
As of the R5 SDK release, there are four different runtime installers available to use depending on your application’s needs and developer preference. There are master installers available both for offline and online downloads, a core installer for applications requiring just the raw streams, and a web application runtime for JavaScript applications. Figure 1 below taken from the Intel RealSense SDK website summarizes the list of runtimes.
Figure 1.List of Intel® RealSense™ SDK runtime installers.
When using the master installer script, there are two versions that can be used to create the smaller installer scripts with the selective Intel RealSense SDK components: offline or online. The online method has the advantage of ease of setup and smaller installer file size, since the SDK components are downloaded directly from the Intel RealSense SDK website. The downside, of course, is that an Internet connection is required. Both versions of the installer script can be found on the Intel RealSense SDK website toward the bottom of the page under the optional runtime redistributable table, as shown in Figure 2. For the master offline installer, use the Full Download button. For the websetup installer, use the Online Download button.
Figure 2.Screenshot of Intel® RealSense™ SDK runtime distributable downloads from the SDK website.
Please refer to the SDK documentation for the full command-line parameters needed to specify the desired SDK components for any of the runtime installers. For example, the following command used with the offline master installer will just install the hand module libraries along with the core components:
setup.exe --silent --no-progress --acceptlicense=yes --fnone=all --finstall=core,hand
Offline Method
Use the - -pre-bundle=<dir> command on the intel_rs_sdk_runtime_YYYY.exe (YYYY is the SDK version). This runtime used to be found in the $(RSSDK_DIR)/runtime folder on the local system in previous SDK releases, but due to its large size, it has been removed and must be downloaded from the SDK website.
Online Method
Follow the SDK documentation under the “runtime installers” article to use the intel_rs_sdk_runtime_websetup_YYYY.exe to install the subset of SDK modules needed directly from the website. Note that the websetup does not use the - -pre-bundle=<dir> command to export the subset of modules. You can find the websetup runtime in the $(RSSDK_DIR)/runtime folder on your local system if you have already installed the full SDK package.
Avoiding Common Install Errors
The supporting SDK documentation on how to deploy an application fails to mention one key point that has caused installation issues for a number of ISVs. While I’ve already referenced the SDK documentation detailing the command-line interface for setting up the runtime redistributables, it doesn’t mention that the same command-line interface is built into the main SDK package installer file (for example, intel_rs_sdk_offline_package_r_5.0.3.187777.exe). It is also missing details on the differences that exist from the setup.exe installer file generated from one of the runtime installers mentioned above versus the offline package installer. Unfortunately, the result is that many apps have been deployed using the full SDK package as the master installer script, which installs components of the SDK package along with the application, resulting in several errors when updating the runtime versions for subsequent releases.
To understand why errors occur with the full SDK package installer, we first must note a key difference between the SDK package (for example, intel_rs_sdk_offline_package_r_5.0.3.187777.exe) and the runtime redistributable installers (for example, intel_rs_sdk_runtime_5.0.3.187777.exe). In short, the SDK package is intended for application developers to be used on development systems. In contrast, the runtime redistributables are intended for end users to enable Intel® RealSense™ software on their consumer platforms. Furthermore, a key distinction in their behaviors is that the SDK package installer is designed to have only a single version exist on a given system at a time, while multiple versions of the runtime redistributables can coexist on the same system. This means that if you had the full R4 package installed on a system, trying to install any components of the R5 SDK package will fail, and the error message shown in Figure 3 will display.
Figure 3.Intel® RealSense™ SDK installation error when previous SDK installation exists.
This issue would not exist if the runtime installer command line did not exist with the package installer. In fact, its existence with the package installer is unintentional, and it is scheduled to be deprecated from future SDK releases. However, if your app has been deployed on R5 or older, you must be aware of the different behavior with the installation of your app depending on which installer file was used as the master script. The following summarize the behavior differences:
- On a clean system with no previously installed versions of the runtimes packaged with the app and no SDK package installed, using either the runtime or package installer will work fine. This is why this issue took so long to manifest as many of the initial apps were tested on systems “clean” of previous SDK installations.
- If the app uses the offline package installer: If you try to install on a system with newer versions of the runtimes already installed, the Intel RealSense SDK runtime installer will fail. If you run the installer in silent mode, you won’t receive a notification that the runtime installation failed. You’ll simply notice that the runtimes are missing in the control panel or you will find that the Intel RealSense SDK components of your app are not functional. If you run in non-silent mode, you’ll see an error that looks like the one shown in Figure 3.
A Real World Example
Let’s say that an application called RealSensePrime was developed and shipped on R1 or R2 Gold SDK runtimes back in February using the hand and blob modules. Let’s also say that RealSenseNext, deployed in May, is a recent app compiled on R4 SDK runtimes using the hand and face modules. A consumer just purchased a new Intel® RealSense™ hardware device and goes on the app showcase to find some apps. He discovers RealSenseNext from May and installs that one first. The RealSenseNext installer installs the R4 runtimes for the hand and face modules as part of its installation. He then finds RealSensePrime on the showcase and decides to download that. The RealSensePrime installer uses a setup.exe (used for Intel RealSense SDK runtime installation) that was generated from the intel_rs_sdk_offline_package_r_YYYY.exe installer instead of the intel_rs_sdk_runtime_YYYY.exe installer. As a result, when he installs RealSensePrime he received no error, but upon playing the game a message in the app displays saying that there was no Intel® RealSense™ camera found on the system (or just finds the camera unresponsive to his actions). This is because (silently) the runtime installation for RealSensePrime failed since the hand module was already installed with a newer version from RealSenseNext.
Conclusion
Application deployment is one of the most vital steps in enabling Intel RealSense applications successfully. Unfortunately, it also happens to be one of the most confusing aspects given the large variety of target platforms, OEMs, CPUs, SDK versions, and other variables that must be accounted for. The paper is intended to clarify some of the more obscure points in successful deployment and adopt lessons learned from the prior mistakes. Here are key takeaways that will facilitate successful deployment:
- An app should never use the
intel_rs_sdk_offline_package_r_YYYY.exeinstaller to generate the module runtimes (that is, hand, face, and so on). This was never intended to be the case since by design only a single version of the SDK can exist on a system. The correct method is to only use the provided runtime redistributables obtained from the SDK website or included with the SDK package. - Installing SDK runtimes on top of older or newer runtimes will work fine as long as it is generated from any of the three runtime installer binaries (see Figure 1). In fact, they are actually installed in different directories and registries to avoid conflicts.
- There are still apps out in the wild that use older runtimes with the offline package installer that may still run into this issue. If the ISV or OEM reports issues with games not working on newer machines with other Intel® RealSense™ applications installed, a new installer script from the ISV using the proper runtime installer will be required to fix it.
- While the application is responsible for bundling the SDK runtimes within its installer, it should never remove the SDK runtimes when the app is uninstalled.
About the Author
Tion Thomas is a software engineer on the media enabling team within the Developer Relations Division at Intel. He helps deliver leading-edge user experiences with optimal performance and power for all types of consumer applications with a focus on perceptual computing. Tion has a passion for delivering positive user experiences with technology. He also enjoys studying graphics, gaming, and immersive technologies.