Emgu TF Download And Installation

From Emgu CV: OpenCV in .NET (C#, VB, C++ and more)
Revision as of 19:23, 15 October 2021 by Canming (talk | contribs)
Jump to navigation Jump to search

Windows

Nuget

Using nuget package manager is probably the easiest way to include Emgu TF library in your project.

Open Source Release

  • From your project, right click on "References" and select "Manager Nuget Packages..." option. It will open up nuget package manager. In package source, make sure that "nuget.org" is selected. (If you are using the commercial release, please check the instruction in the commercial download area for instructions to setup the commercial release nuget repository.)
Emgu TF
  • Under "Browse", enter the search text "emgu.tf.runtime" and you should be able to find the Emgu.TF.runtime.windows nuget package.

Please make sure the package is created by "Emgu Corporation" for the official release.

  • Click the "Install" button. Nuget will download Emgu.TF.runtime.windows and configure the project for you.
Emgu TF Lite
  • Under "Browse", enter the search text "emgu.tf.lite.runtime" and you should be able to find the Emgu.TF.Lite.runtime.windows nuget package.

Please make sure the package is created by "Emgu Corporation" for the official release.

  • Click the "Install" button. Nuget will download Emgu.TF.Lite.runtime.windows and configure the project for you.

Commercial Release

  • If you are using the commercial release, please check the instruction in the commercial download area for instructions to setup the commercial release nuget repository. Commercial release download link can be found in the "Download Instructions" at the bottom of your purchase complete page. It is also available on the product delivery email, under the "CUSTOMER SERVICE" session. Please click on the link below "Your Order Data" to access the Commercial release download area.

Order data.png

  • If you have the Professional / Ultimate license. The instruction can be found in "windows" folder.
  • If you have the Windows only license. The instructions can be found at the bottom of the page as soon as you logged in.
  • Once the commercial nuget repository is setup, you should be able to find the following three packages, please choose one depends on your requirement:
    • Emgu.TF.runtime.windows.cuda is the commercial release runtime of TF with CUDA support.
    • Emgu.TF.Lite.runtime.windows.xnn is the commercial release runtime of TF Lite with XNN support.
  • Click the "Install" button. Nuget will download Emgu commercial release and configure the project for you.

The type initializer for 'Emgu.TF.TfInvoke' threw an exception.

If you see this exception, please check the following

Are you missing any dependency?

Download Dependency Walker and use it to open the "tfextern.dll" or "tfliteextern.dll" file. Check if any dependency is missing.

Linux

Getting ready

Ubuntu 20.04

  • dotnet SDK
    • For 4.5.1 release, you will need dotnet SDK 5.0. Please follow this instruction to install asp .net core on Ubuntu. Once that is done, run the following command to verify dotnet is installed:
      ubuntu:~$ dotnet --list-runtimes
      It should show a message similar to the following
      Microsoft.AspNetCore.App 5.0.0 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App] Microsoft.NETCore.App 5.0.0 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
  • CMake
    • Emgu TF & Emgu TF Lite has adapted to use cmake to compile its source code.
  • Installing GIT so you can check out the project folder, you can install GIT by running
    sudo apt-get install git

Raspberry Pi OS

  • dotnet SDK
    • For 4.5.1 release, you will need dotnet SDK 5.0
  • CMake
    • Emgu TF & Emgu TF Lite has adapted to use cmake to compile its source code.
  • Installing GIT so you can check out the project folder, you can install GIT by running
    sudo apt-get install git

Getting the source code

  • To build from source, you will need a Git client to check out the source code from SourceForge. For more information, see GIT. The following command can be used to check out the source:
git clone https://github.com/emgucv/emgutf emgutf 
  • Go to emgutf directory
cd emgutf
  • Initialize tensorflow and submodules
git submodule update --init --recursive

Configuring & Building the project

Ubuntu 20.04

  • Got to the configuration folder.
    cd platforms/ubuntu/20.04
  • Installing the prerequisites. This only needs to be run once. You can install them by running
    ./apt_install_dependency
Tensorflow
  • If you are build Emgu TF, use the following command to build the tensorflow:
    bazel_build_tf
  • Skip the build steps for Tensorflow Lite below
Tensorflow Lite
  • If you are build Emgu TF Lite, use the following command to build the tensorflow:
    bazel_build_tflite
  • Skip the build steps for Tensorflow above
Emgu TF / Emgu TF Lite
  • Build the managed Emgu TF or Emgu TF Lite code using the following command:
    build_emgutf

Raspberry Pi OS

  • Got to the configuration folder
cd platforms/raspbian
  • Installing the perquisites

This only needs to be run once. You can install the prerequisites by running

./apt_install_dependency
Tensorflow
  • If you are build Emgu TF, use the following command to build the tensorflow:
    bazel_build_tf
  • Skip the build steps for Tensorflow Lite below
Tensorflow Lite
  • If you are build Emgu TF Lite, use the following command to build the tensorflow:
    bazel_build_tflite
  • Skip the build steps for Tensorflow above
Emgu TF / Emgu TF Lite
  • Build the managed Emgu TF or Emgu TF Lite code using the following command:
    build_emgutf


Running the Examples

Emgu TF

  • We have the native binary compiled. Now let's compile and run our first dot net core program.
cd Emgu.TF.Example\Inception.Console.NetCore
  • make sure dotnet can load the dynamic library from the current location by typing
export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
  • Try to compile and run the program on ubuntu:
dotnet run
  • Or, if you are on Raspbian OS,
 LD_PRELOAD=/usr/lib/arm-linux-gnueabihf/libatomic.so.1 dotnet run

Emgu TF Lite

  • We have the native binary compiled. Now let's compile and run our first dot net core program.
cd Emgu.TF.Example\Inception.Console.Lite.NetCore
  • make sure dotnet can load the dynamic library from the current location by typing
export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
  • Try to compile and run the program on ubuntu:
dotnet run
  • Or, if you are on Raspbian OS,
 LD_PRELOAD=/usr/lib/arm-linux-gnueabihf/libatomic.so.1 dotnet run

System.DllNotFoundException

If you encounter this exception, there might be missing dependencies. In this case, go to libs\x64 folder (or libs\arm folder, or libs\x86 folder, depends on your system architecture).

Run this command for Emgu TF: ldd libtfextern.so

Run this command for Emgu TF Lite: ldd libtfliteextern.so

and check if there is any dependency missing.

If not, go back to project folder and run this command

gdb dotnet

then, on the (gdb) commandline, type

run run

to debug with GDB.

You can also try

LD_DEBUG=libs dotnet run

to find missing dependencies.

Mac OS

Emgu TF for Mac OS is available under our commercial license. The instructions below applies to the Emgu TF for Mac OS, Professional or Ultimate commercial release.

Adding Emgu TF to your Xamarin Mac App

You can either add Emgu TF to your project by directly adding the binary files, or by adding two projects.

Using binary files

The "lib" folder of the Mac OS (or Pro) release package should contains the files

Emgu.TF.NetStandard.dll
macos/libtfextern.dylib
macos/libtensorflow_framework.dylib

Please add Emgu.TF.NetStandard.dll as a reference to your Xamarin Mac App. Deploy "libtfextern.dylib" & "libtensorflow_framework.dylib" file to the folder of executable. Afterwards you should be ready to use Emgu TF in your Mac OS App.

If the files "Emgu.TF.NetStandard.dll" does not exist, you can compile the visual studio solution under "Solution\macos\Emgu.TF.Mac.sln" to build the dlls.

Using project files

Instead of using the binary files as mention above. You can also add this two projects as references into your existing project:

For v2.5.0

  • Emgu.TF\Emgu.TF.Netstandard\Emgu.TF.Netstandard.csproj
  • Emgu.TF.Runtime\Mac\Emgu.TF.Runtime.Mac.shproj

Demos

If you use the zip file, the demo solution can be found under the "Solution\Mac" folder. To avoid getting security error from Mac OS such as

"{App ID}" is blocked from use because it is not from an identified developer

please change the demo project output folder to somewhere outside the unzipped folder.

iOS

Emgu TF Lite for iOS is only available under our commercial license. The instructions below applies to the Emgu TF Lite for iOS, Professional or Ultimate commercial release.

Adding Emgu TF Lite to your Xamarin IOS App using dlls from the zip package

The iOS (or Pro) Emgu TF Lite release package should contains the following two files:

lib\ios\Emgu.TF.Lite.NetStandard.dll
lib\Emgu.TF.Lite.Runtime.iOS.dll

Adding this two dll files as a reference to your Xamarin iOS App should allow you to use Emgu TF Lite in your App.

For 2.5.0 and later release, after adding the references. You should call

TfLiteInvokeIOS.Init()

in the main ios app, to make sure the native binary is included in the compilation. Otherwise you may see a long list of missing native reference errors during compilation. You can add the function call in the AppDelegate.cs file, under the FinishedLaunching function:

        public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
        {
            // Override point for customization after application launch.
            // If not required for your application you can safely delete this method

            global::Xamarin.Forms.Forms.Init();

            TfLiteInvokeIOS.Init();

            LoadApplication(new YourApp());

            return base.FinishedLaunching(application, launchOptions);
        }

Adding Emgu TF Lite to your Xamarin iOS App using nuget package

The commercial download page also provide access to the "Emgu.TF.Lite.runtime.ios" nuget pacakge. Similar to the "Emgu.TF.Lite.runtime.windows" nuget package that provide runtime dependencies for Windows, it provides the runtime dependencies for Emgu TF Lite targeting iOS application. Once you download the nuget package, you can either put it in your own nuget server, or you can put it in a local folder and configure Visual Studio to use the folder as a local repository.

For 2.5.0 and later release, after adding the nuget package. You should call

TfLiteInvokeIOS.Init()

in the main iOS app, to make sure the native binary is included in the compilation. Otherwise you may see a long list of missing native reference errors during compilation.

Please make sure you don't include more than one "Emgu.TF.Lite.runtime" packages for a single project. If you are developing multiplatform applications, you can create a library project that reference "Emgu.TF.Lite" without any "Emgu.TF.Lite.runtime" pacakge. After that, you can create seperate projects targeting different platforms referencing your common library. Each individual platform targeted project will reference the specific "Emgu.TF.Lite.runtime" package. e.g.

MyLibrary -> Add Reference to "Emgu.TF.Lite" nuget pacakge
MyWindowsApp -> Add Reference to "MyLibrary" and "Emgu.TF.Lite.runtime.windows" nuget pacakge
MyMacApp -> Add Reference to "MyLibrary" and "Emgu.TF.Lite.runtime.mac" nuget pacakge
MyAndroidApp -> Add Reference to "MyLibrary" and "Emgu.TF.Lite.runtime.android" nuget package
MyIOSApp -> Add Reference to "MyLibrary" and "Emgu.TF.Lite.runtime.ios" nuget package

Size of the binary

The "Emgu.TF.Lite.Runtime.iOS.dll" file size is large. For example, in the 2.6.0 iOS release, this file is 167MB. It contains the native binary for all supported CPU architectures, including those for simulators.

However, if you are building an IPA for app store submission, and is only targeting ARM64 devices, you can select just ARM64 architecture. When the IPA is build, the compiler will strip out all the binary that are not used. It will significantly reduce the final size of the IPA. Depends on the number of functions you used, if you are only targeting a single ARM64 architecture, the final IPA size should be much smaller.

Demos

The demo solution is available under the "Solution\iOS" folder.

Android

Emgu TF / Emgu TF Lite for Android is only available under our commercial license. The instructions below applies to the Emgu TF / Emgu TF Lite for Android, Professional or Ultimate commercial release.

Adding Emgu TF to your Xamarin Android App using dlls from the zip package

The "lib" folder of the Emgu TF Android (or Pro) release package should contains these two files

Emgu.TF.NetStandard.dll
Emgu.TF.Runtime.Android.dll

Adding the above files as references to your Xamarin Android App should allow you to use Emgu TF in your App.

If the files does not exist, you can compile the visual studio solution under "Solution\Android\Emgu.TF.Android.sln" to build the dlls.

For 2.5.0 and later release, after adding the references. You should call

Emgu.TF.TfInvokeAndroid.Init();

in the main android app, to make sure the native binary is included in the compilation. Otherwise you may see PInvoke exception when you call an Emgu CV function on Android.

Adding Emgu TF to your Xamarin Android App using nuget package

The commercial download page also provide access to the "Emgu.TF.runtime.android" nuget pacakge. Similar to the "Emgu.TF.runtime.windows" nuget package that provide runtime dependencies for Windows, it provides the runtime dependencies for Emgu TF targeting Andorid application. Once you download the nuget package, you can either put it in your own nuget server, or you can put it in a local folder and configure Visual Studio to use the folder as a local repository.

For 2.5.0 and later release, after adding the nuget package. You should call

Emgu.TF.TfInvokeAndroid.Init();

in the main android app, to make sure the native binary is included in the compilation. Otherwise you may see PInvoke exception when you call an Emgu TF function on Android.

Please make sure you don't include more than one "Emgu.TF.runtime" packages for a single project. If you are developing multiplatform applications, you can create a library project that reference "Emgu.TF" without any "Emgu.TF.runtime" pacakge. After that, you can create seperate projects targeting different platforms referencing your common library. Each individual platform targeted project will reference the specific "Emgu.TF.runtime" package. e.g.

MyLibrary -> Add Reference to "Emgu.TF" nuget pacakge
MyWindowsApp -> Add Reference to "MyLibrary" and "Emgu.TF.runtime.windows" nuget pacakge
MyMacApp -> Add Reference to "MyLibrary" and "Emgu.TF.runtime.mac" nuget pacakge
MyAndroidApp -> Add Reference to "MyLibrary" and "Emgu.TF.runtime.android" nuget package
MyIOSApp -> Add Reference to "MyLibrary" and "Emgu.TF.runtime.ios" nuget package

Size of the binary

The "Emgu.TF.Platform.Android.dll" file size is large. For example, in the 2.6.0 Android release, this file is 133MB. It contains the native binary for all supported CPU architectures, including "arm64-v8a", "armeabi-v7a", "x86" and "x64".

If you are building an app for Google Play Store submission, we recommend using the AAB (Android App Bundle) format. When end-user download the APK package generated from the AAB file, only one out of 4 CPU architectures matching the user device will be included, resulting in a much smaller size occupied by Emgu TF for Android runtime. FYI, the download size limit of the compressed APK generated from the AAB is 150MB as of Apr 2021. That should give you lots of rooms to include other libraries on top of Emgu TF.

Another option is to build one APK per CPU architecture. The process of submmiting multi-architecture APK is much more compilcated than using AAB. Google recommend using AAB instead.

At last, if you are only targeting arm64-v8a devices, you can select just arm64-v8a architecture. When the final APK is build, the compiler will strip out all the binary for the architectures that are not used. It will significantly reduce the final size of the APK. Depends on the number of functions you used, if you are only targeting a single arm64-v8a architecture, the final APK size should be much smaller.

Demos

The demo solution is available under the "Solution\Android" folder.