expo-opencv

Expo OpenCV

An Expo Module exposes the native Android and iOS OpenCV SDK's to the React Native & Expo platforms.

The OpenCV SDK's used are:

Android Maven: https://central.sonatype.com/artifact/org.opencv/opencv/overview

Generated XCFramework from Github: https://github.com/opencv/opencv

Getting Started

Clone the repo, pull large files from LFS, and then install dependencies from the root directory:

// Clone the repo
git clone https://github.com/Glennis-Mobile/expo-opencv.git
// Open the project direcory
cd expo-opencv
// Some Large files are managed by LFS,
// so you need to pull these
git lfs pull
// Install the dependencies
npm install

Next, you need to install dependencies into the example project:

cd example
npm install

Building and Running the Example project

Each time the codebase in the /src, /ios, or /android folders are modified, the example project code needs to be rebuilt.

cd example
npx expo prebuild --clean
// This clears the existing ios and andriod folders and reinstalls the dependencies

Now that the projects have been configured, you can build iOS or Android project using the command:

// Change to the example directory if not already there
cd example
npx expo run:ios
// or
npx expo run:android

If you wish to see the project in either Xcode or Android Studio, you can run the following command after running the previous prebuild command:

// Change directory to the root directory if not already there
cd ..
npm run open:ios
// or
npm run open:android

Adding as a Dependency to Another Project

This project is pubically available on npm as expo-opencv.

To add it as a depedency:

npx expo install expo-opencv

You will then need to add this config to your package.json file:

{
   ...,
   "expo": {
    "autolinking": {
      "nativeModulesDir": ".."
    }
  }
}

You have to run the project as a Expo Development Build. So if you havent already, install the dev-client:

npx expo install expo-dev-client

Then prebuild the project:

npx expo prebuild --clean

To run locally:

npm run open:ios
// or
npm run open:android

Or create a development build for a device, follow these instructions.

Directory Structure

The directory is structure into four main folders

• /android: Contains the native kotlin code that will be imported into an expo project
• /example: An example app that models the expo-module being added as a dependency to an expo project
• /ios: Contains the native swift code that will be imported into an expo project. This essentially acts as files in a development pod.
• /source: The javascript/typescript layer that exposes the native ios/android code to the expo project

iOS Folder

If you are wrapping an native third party dependency as described in the Expo Documentation, then the main file you will use is the /ios directory is ExpoOpencv.podspec. This folder contains the ruby code used to configure and download a cocoapod as a depenendency.

Creating XCFramework

Check out this guide and this official doc on creating an OpenCV XCFramework.

Once you download the opencv repo, python and cmake, then you can run this command in terminal:

python3 platforms/apple/build_xcframework.py --out build_all \
--iphoneos_deployment_target 14.0 \
--iphoneos_archs arm64 \
--iphonesimulator_archs arm64,x86_64 \
--build_only_specified_archs True \
--without=video \

Integrating XCFramework

Create a Frameworks folder inside you /ios directory and copy the opencv2.xcframework folder into it.

Now update the ExpoOpencv.podspec file to include the framework:

require 'json'

package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))

Pod::Spec.new do |s|
  s.name           = 'ExpoOpencv'
  s.version        = package['version']
  s.summary        = package['description']
  s.description    = package['description']
  s.license        = package['license']
  s.author         = package['author']
  s.homepage       = package['homepage']
  s.platforms      = { :ios => '13.4', :tvos => '13.4' }
  s.swift_version  = '5.4'
  s.source         = { git: 'https://github.com/Glennis-Mobile/expo-opencv' }
  s.static_framework = true

  s.dependency 'ExpoModulesCore'

  # Add OpenCV Framework and preserve file paths for all the headers
  s.vendored_frameworks = 'Frameworks/opencv2.xcframework'
  s.exclude_files = ["Frameworks/*.xcframework/**/*.{h,hpp}"]
  s.preserve_paths = [
    "Frameworks/*.xcframework",
    "**/*.{h,hpp}",
    "Frameworks/*.xcframework/**/*.{h,hpp}"
  ]

  # Swift/Objective-C/C++ compatibility
  s.pod_target_xcconfig = {
    'DEFINES_MODULE' => 'YES',
    'SWIFT_COMPILATION_MODE' => 'wholemodule',
  }

  # Added mm, h, and hpp for the bridging files for OpenCV Framework
  s.source_files = '**/*.{h,hpp,m,mm,swift}'
end

When you generate the .xcframework file, it will structure the framework using symlinks. However, if you publish the project to npm, these links will not be preserved and the module will fail to run as a dependency in another project. To fix this issue, we haved added a handy script. Once the .xcframework is in the /Frameworks directory, you can run this command:

npm run fix-links

This will run the node function contained in the replace_symlinks.js file. It recursively goes through a directory to replace all the symlinks with the correct targets. You will only need to do this once per a new .xcframework if you commit the file changes after the script is ran.

You can now publish the expo-module to npm by incrementing the version number in the package.json and then run:

npm publish