Getting Started with Roux, Part 1: How to Set Up the Example iOS App
This is part one of a two part series. Part two will go more in-depth on building your own project from scratch.
Before building your first Roux project from scratch, we recommend building one of our example apps. These pre-configured projects demonstrate how to access the Roux library and how to include your license key. You will also see the basic functionality of setting up scan configurations, starting & stopping scanning, and generating & saving meshes.
Before we get started, ensure you have the following:
- Xcode
- A TrueDepth-enabled iPhone or iPad
Step 1: Clone the example project
For your convenience, we’ve built two example apps, one in Objective-C and one in Swift. The apps are identical in functionality, so choosing which to build is simply a matter of which language you prefer.
Simply clone the repo down to your local environment using:
Objective-C
git clone git@github.com:Scandy-co/RouxObjCHelloWorld.git
cd RouxObjCHelloWorld/
Swift
git clone git@github.com:Scandy-co/RouxSwiftHelloWorld.git
cd RouxSwiftHelloWorld/
As you can see, the repository names above are virtually identical except for the indication of `ObjC` or `Swift`. This naming convention also exists in many of the files and directories within the projects. For simplicity’s sake, this tutorial will use the flag <language> in place of `ObjC` or `Swift`. Any time you see this flag, simply replace it with the language you are using.</language>
Step 2: Sign up to become a Roux developer
In order to use the Roux SDK, you will need to register as a Roux developer. We make this process simple and painless. Simply visit the Roux registration page, fill in your information and click “Sign Up”.
Once you click “Sign Up”, you will receive an email containing a link to confirm your email. Click the link, return to roux.scandy.co and sign in with your credentials.
The final step is to submit your business and billing information, and read and accept the license agreement. Once you click “Get Roux”, you will be registered and immediately given access to the Roux Portal.
Step 3: Create a new project
Every application you build using Roux will need to have an associated project in the Roux portal. Click “Start new project”.
On the next screen, fill out the required fields and click "Create Project". For this tutorial, you should set the project name to "Example Project", bundleid to "co.scandy.Roux<langauge>HelloWorld", and project type to "Direct-to-Consumer".</langauge>
- Project Name: the name you would like to use to refer to your project
- Bundle ID: the bundle id of the application which will be using Roux. This must be an exact match with that of the bundle ID in Xcode otherwise the Roux SDK will not work. For this tutorial, we are using co.scandy.Roux<langauge>HelloWorld because that is the bundle id of the example project.</langauge>
- Project Type: select ‘Direct-to-Consumer’ if your application will be deployed to the Apple App Store or select ‘Enterprise’ if your application will be deployed to the Apple Enterprise Store. For this tutorial, it does not matter which one you pick.
Step 4: Download your license key
When you create a project, a license key is generated specifically for that project. Upon creating your project, this license key will be emailed to you or you can download it directly from the project details page by clicking “Download license”.
This will download a simple .txt file called license.txt which looks something like this:
This is your proof of registration and what will allow the Roux SDK to run in your application. Keep this file secure and do not share outside of your company. This file is highly sensitive to changes - do not change anything within the file, otherwise it will be invalidated.
Step 5: Download the SDK
If you haven’t already, download the SDK by clicking “Download SDK” in the top navigation bar.
This will download a zipped file named Roux-[VERSION_NUMBER]-iOS.zip. Unzip the file.
Step 6: Add license to example project
If you list what's in that directory, you'll see a dir called `Roux<language>HelloWorld/`. Rename the license.txt you downloaded in Step 3 to </language>ScandyCoreLicense.txt and move it into Roux<language>HelloWorld/</language>.
🤔 Wondering what "ScandyCore" is ❓
ScandyCore is the old name for our SDK, which is now obviously called Roux . As you can see, there are remnants of the previous name in a few areas of our code still. We are phasing these references out over time, so in the meantime, when you see "ScandyCore", just think Roux!
Open Roux<language>HelloWorld.xcodeproj</language> by either double clicking the file in the finder or running
open Roux<language>HelloWorld.xcodeproj</language>
Now, let’s make sure the license is properly being linked. Select Roux<language>HelloWorld</language> in the left-hand project navigator, then select Roux<language>HelloWorld</language> from the TARGETS list and then click Build Phases from the top menu bar. Expand the section called Copy Bundle Resources. If you do not see ScandyCoreLicense.txt in the list of resources, click `+` and add it.
You can double check that license is linked by clicking ScandyCoreLicense.txt in the left-hand navigator. If you see the contents of your license, then you are good to go!
Step 7: Add ScandyCore Framework
In your unzipped SDK file, there should be an item called ScandyCore.framework.
Move this item into Frameworks/
Step 8: Build and Run!
Plug in your iOS device. In the top toolbar of Xcode, make sure your device is selected - not a simulator or “generic iOS device”.
Hit 'Run' and voila! Your example Roux application will be running on your device. In this basic example, you can preview meshes, start scanning, stop scanning and save meshes.
