ASSOCIATION D UN PROJET UNITY VUFORIA ET D UNE APPLICATION ANDROID

Procédure ASSOCIATION D UN PROJET UNITY VUFORIA ET D UNE APPLICATION ANDROID IBISC Université d Evry Loïc Saillant 24 mars 2015

Table des matières Introduction 1 1 Importer le projet Unity dans Eclipse 2 1.1 Avant de commencer................................... 2 1.2 La procédure....................................... 2 2 Suite de l application 4 2.1 Création de la nouvelle activité............................. 4 2.2 Ajout de l interaction................................... 5 3 Cible 3D 6 4 Complément : modifier le projet Unity 6 Conclusion 7 ANNEXES 8 A Fichier layout activitywelcome.xml 8 B Fichier styles.xml 9 C Fichier strings.xml 9 D Fichier WelcomeActivity.java 9 E Fichier QCARJavaActivity.java 10

Introduction L idée de ce document est d expliquer au lecteur comment intégrer un projet Unity Vuforia dans une application Android. Dans le but de rendre les choses plus faciles, notamment à cause de l ensemble des liens qu il peut exister entre les différentes activités, je pars du principe que le projet Unity est déjà existant et que l application Android est, quant à elle, inexistante. Ce document a été très largement inspiré du tutoriel présent sur le site de Vuforia. Prérequis logiciel Pour la réalisation de ce document, j ai utilisé : Unity 4.3.4 pour Windows, Vuforia 3.0.9, Eclipse Luna 4.4.1 avec le dernier SDK Android. Prérequis matériel Pour la réalisation de ce document, j ai utilisé : Un ordinateur fixe sous Windows 7, Un Nexus 5 LGE sous Android Lollipop 5.0.1. De telles manipulations ont leurs équivalents sous ios avec un Mac et xcode, mais ces éléments ne seront pas étudiés ici. Idée générale L idée est de créer une application toute simple, composée de plusieurs boutons, permettant d accéder aux différents projets Vuforia. Voici à quoi pourrait ressembler notre application : Figure 1 Notre objectif final Pour ce faire, nous allons procéder en deux étapes : Importation de notre projet Unity dans Eclipse, Création de l activité d accueil de notre application et lien avec le projet Unity. Remarque Cette application est disponible sur mon site, sur cette page. 1

1. Importer le projet Unity dans Eclipse 1.1 Avant de commencer Comme je le disais dans l introduction, je vais partir du postulat que vous avez déjà créé un projet sur Unity à l aide de Vuforia et que vous voulez maintenant agrémenter votre application, pour une meilleure expérience utilisateur. Vous pouvez d ailleurs retrouver un document intitulé "Mise en place d un environnement 3D", dans lequel j explique la création d un univers 3D au travers de Unity et Vuforia. Avant de commencer la méthode qui va suivre, assurez-vous déjà que votre application fonctionne correctement en la compilant et en l exécutant directement sur votre smartphone, à partir de Unity. Logiquement, vu que nous travaillons sur des applications Vuforia, vous devriez simplement avoir une application plein écran sur laquelle défile l image de votre appareil photo. De plus, ajoutez à votre ARCamera un script 1 que vous applez BackButton. Dans ce script, dans la méthode "Update()" ajoutez les lignes suivantes : void Update ( ) { i f ( Input. GetKeyUp( Keycode. Escape ) ) { System. D i a g n o s t i c s. Process. GetCurrentProcess ( ). K i l l ( ) ; Ce petit bout de code va permettre, une fois l application Android créée, de stopper l activité Unity et de revenir au menu principal. 1.2 La procédure Suivez bien l ensemble de ces étapes, car la méthode est particulièrement fastidieuse, et on peut vite faire une erreur. Bon courage! 1. Rendez-vous dans le menu File/Build Settings de Unity. Allez sur Android, puis cliquez sur Player Settings. Tout en haut de la fenêtre de l inspecteur, saisissez : Company Name = MyCompany Product Name = QCARJava Ensuite, un peu plus bas, déployez le menu Other Settings et dans le Bundle Identifier, reportez com.mycompany.qcarjava. Enfin, sélectionnez l API 11 (Honeycomb) comme Minimum API Level 2. Remarque Le choix de MyCompany et de QCARJava est arbitraire. Vous pouvez mettre quasiment tout ce que vous voulez. Néanmoins, ces réglages sont des éléments sensibles, qui peuvent causer des bugs une fois l application mise en place. Je ne saurai que trop vous conseiller de faire exactement ce que je fais, de manière à avoir une application fonctionnelle. 2. Maintenant que tous ces réglages sont faits, faites Build et sauvegardez votre fichier.apk dans votre répertoire de travail 3. S il est déjà présent, vous pouvez le supprimer. 3. Une fois le Build fait, rendez-vous dans le dossier où se trouve le projet Unity. Vous devez trouver un dossier Temp et dans ce dossier, un dossier StagingArea. Copiez alors ce dossier StagingArea autre part qu ici, sur le bureau par exemple 4. 1. Dans l inspecteur, faites Add Component/New Script 2. Le choix de Honeycomb ne change pas grand chose, si ce n est l apparition de l ActionBar pour Android. 3. Le nom du fichier importe très peu. 4. L intérêt de cette manipulation est tout simplement que, si nous touchons au projet Unity, il se pourrait que le dossier StagingArea soit modifié, ce qui poserait de gros soucis à Eclispe. On crée donc une copie sur laquelle nous allons travailler avec Eclipse. 2

4. Maintenant, ouvrez Eclipse. Je suppose ici que le SDK Android est bien installé. Faites alors File/New/Project/. Dans la fenêtre qui s ouvre, déployez l onglet Android et cliquez sur Android Project From Existing Code. À ce moment, parcourez votre disque, jusqu à pointer sur le fameux StagingArea présent sur le Bureau. On vous propose alors d importer un projet dont le nom est QCARPlayerNativeActivity. Le nom est un peu long donc on va le renommer QCARUnity. 5. Maintenant que notre projet est importé, on va en faire une librairie, pour pouvoir l utiliser dans notre application. Faites alors clic droit sur votre projet QCARUnity, puis Properties. Allez dans l onglet Android et cochez la case IsLibrary. 6. Il faut dorénavant créer notre fameuse application Android. Soit encore une fois File/New/- Project. Puis Android Application Project. Remplissez alors les champs comme suit : Application Name = QCARJava Project Name = QCARJava Package Name = com.mycompany.qcarjava 5 On vous propose alors une multitude de choses pour commencer votre application, contentezvous de faire une Blank Activity et de l appeler QCARJavaActivity. 7. Il faut alors lui associer la librairie que nous avons créée avec le projet Unity. Pour ce faire, clic droit sur le projet Java, puis Properties et Android. Ici, faites Add et vous devriez avoir le projet QCARUnity. 8. Enfin, allez dans votre explorateur de fichiers et plus précisément là où est installé Unity. Naviguez selon ce chemin emplacement_unity/editor/data/playbackengines/androidplayer/bin. Ici vous devez trouver un fichier classes.jar. Copiez ce fichier dans le dossier libs du projet QCARUnity, dans Eclipse. Nous reviendrons sur son utilisation après. Maintenant que toutes ces étapes sont faites, il va falloir faire des transferts de fichiers entre le projet Unity et le projet Java. En effet, certains fichiers sont nécessaires à l application Android pour faire fonctionner le moteur Unity. Toutes les étapes suivantes se font directement dans Eclipse. 1. Bougez les dossiers "/assets" et "/libs" de QCARUnity à QCARJava. Il va vous demandez si vous souhaitez supprimer les autres, faites "Yes To All". À ce moment vous devez avoir trois fichiers dans le dossier "/libs" de QCARJava : armeabi, android-support et classes.jar. 2. Revenons au dernier fichier, classes.jar. Faites clic droit sur QCARJava, puis Properties et allez dans Java Build Path. Allez sur l onglet Libraries puis Add JARs. Naviguez alors dans votre projet jusqu au dossier "/libs" et sélectionnez classes.jar. Cliquez sur OK. 3. Maintenant, rendez-vous dans le dossier "/plugins" du projet QCARUnity. Copiez les fichiers QCARUnityPlayer.jar et Vuforia.jar dans le dossier "/libs" de QCARJava. 4. Puis, rendez-vous dans le dossier "/raw" de QCARUnity où vous trouverez le dossier "/Q- CAR". Copiez ce dossier dans le dossier "/assets" de QCARJava. 5. Enfin, copiez le fichier AndroidManifest.xml, présent à la racine de QCARUnity, au même endroit, mais dans le projet QCARJava. Un fichier est déjà existant, écrasez-le. Ouf, ça y est notre projet est bientôt prêt. Il faut maintenant faire quelques changements dans le code de l application. 1. Dans l activité principale de notre application, qui correspond au fichier QCARJavaActivity.java (présent dans src/com/mycompany/qcarjava), modifiez : public class QCARJavaActivity extends ActionBarActivity Par : public c l a s s QCARJavaActivity extends QCARPlayerNativeActivity Si vous utilisez la version 3.x de Vuforia, ou par : public class QCARJavaActivity extends UnityPlayerNativeActivity 5. Faites bien attention à mettre le même Bundle Identifier que celui stipulé au sein de Unity. 3

Si vous utilisez la version 4.x de Vuforia. 2. Faites la combinaison Ctrl+Shift+o, afin qu Eclipse importe les bons packages. 3. Supprimez la ligne setcontentview (R. layout. q c a r j a v a _ a c t i v i t y ) ; Cette ligne permet en fait de charger le fichier contenant la forme de notre page ainsi que tous les objets (Titres, Textes, Boutons, Images...). Or ici nous n en avons pas besoin, car notre but et de récupérer la même chose que sur Unity. Dans la même veine, vous pouvez uniquement laisser la surcharge de la méthode oncreate(), vu que le reste ne nous sert à rien. 4. Dans le fichier "AndroidManifest.xml" de QCARJava, allez au niveau de la ligne où on trouve la première balise <activity>. Dans le champ Name, remplacez quelque chose qui doit ressembler à com.qualcomm.qcarunityplayer.qcarlayernativeactivity par ".QCAR- JavaActivity". Ici on fait en fait directement référence à l activité de notre application. Remarque À ce moment si vous sauvegardez votre fichier Manifest, il y a une ligne qui pose souci : celle où on trouve la balise <application>. Pour régler ce problème, il faut supprimer le champ android :debuggable et ajouter : android : allowbackup=" t r u e " Au sein de la balise <application>. Sauvegardez alors, il ne devrait plus y avoir de souci. À ce stade, si vous exécutez votre application sur votre Smartphone, vous devriez avoir exactement la même chose que ce que vous aviez en sortie d Unity. Si c est le cas, bravo vous avez importé votre premier projet Unity dans Eclipse. On va maintenant pouvoir bosser dessus et notamment ajouter un menu. 2. Suite de l application Ici vous pouvez totalement laisser libre cours à votre imagination pour ce qui est du choix des couleurs, des boutons,... Néanmoins, comme tout à l heure, si vous voulez être certain que cela marche, je vous engage à suivre ma mise en forme et ma méthode. 2.1 Création de la nouvelle activité Faites clic droit sur QCARJava, puis New/Other. Allez alors dans Android puis Android Activity. Dans les fenêtres qui suivent, choisissez BlankActivity puis appelez-la WelcomeActivity et désignez-la comme la LauncherActivity. Remarque Pour une raison obscure, il considère toujours la QCARJavaActivity comme la Launcher Activity dans le Manifest. Rendez-vous donc dans le fichier "AndroidManifest.xml" et au sein de l activité "QCARJavaActivity", supprimez les lignes suivantes : <i n t e n t f i l t e r > <a c t i o n android : name=" android. i n t e n t. a c t i o n.main" /> <c a t e g o r y android : name=" android. i n t e n t. c a t e g o r y.launcher" /> </ i n t e n t f i l t e r > Dorénavant, l activité WelcomeActivity est bien celle qui apparaîtra au démarrage. Pour voir si tout fonctionne parfaitement, je vous engage à re-compiler le projet et à l envoyer sur votre téléphone. Vous devriez alors voir uniquement un "Hello World". Remarque Il y a une erreur assez fréquente qui apparaît et c est la suivante : 4

You need t o use a Theme. AppCompat theme ( or descendant ) w i t h t h i s a c t i v i t y. En fait, ceci est lié au fait que par défaut dans Unity, ils ont mis une application de type FullScreen, NoActionBar et on parle bien ici de l application. Il faut tout simplement aller dans le manifest et dans la balise <application>, remplacez : android : theme=" @android : s t y l e /Theme. NoTitleBar. F u l l s c r e e n " Par : android : theme=" @ s t y l e /Theme. AppCompat" Lancez votre appli, le Hello World s affiche bien ;) Tout fonctionne certes, mais on n a maintenant plus du tout accès à l activité Unity et il n existe aucune interaction. Faisons donc quelques modifications esthétiques et techniques. 2.2 Ajout de l interaction Afin que vous ayez la même chose que sur la figure (1), je vous ai mis mon fichier XML de layout, en annexe. Juste quelques précisions : Il va vous manquer les valeurs de la couleur que j ai appelé Green et des Strings que j utilise. Pas grave, je vous les mets aussi en annexe. Mais globalement là, vous pouvez vraiment écrire ce que vous voulez. Dans mon dossier Styles.xml, nous avons tous une valeur qui s appelle "AppBaseTheme". Mettez le parent de cette valeur à "Theme.AppCompat.NoActionBar". En effet, si vous regardez mon fichier XML de layout, j ai ajouté une Toolbar, qui prend la place de l ActionBar. Il faut déclarer la Toolbar dans le fichier WelcomeActivity.java. Je vous ai aussi mis mon activité WelcomeActivity en annexe. Maintenant que tout fonctionne, il manque encore l action des boutons. Nous allons juste nous intéresser au premier bouton à savoir "Partie I : CIBLE 2D". Il faut dans un premier temps le déclarer, puis ensuite ajouter l action suite au clic. La déclaration correspond aux lignes : public Button button1 ;... button1 = ( Button ) findviewbyid (R. id. button1 ) ; Et l ajout de l interaction par ces lignes-là : button1. s e t O n C l i c k L i s t e n e r (new View. OnClickListener ( ) { @Override public void onclick ( View v ) { //on cree notre i n t e n t I n t e n t i n t e n t = new I n t e n t ( WelcomeActivity. this, QCARJavaActivity2D. class ) ; //on demarre l a c t i v i t e s t a r t A c t i v i t y ( i n t e n t ) ; Remarque sans le 2D. J ai appelé mon activité QCARJavaActivity2D, vous devriez avoir la même chose Lancez alors votre application et vous devriez pouvoir cliquer sur le bouton et accéder à votre scène de réalité augmentée Unity. 5

3. Cible 3D Pour la cible 3D, la donne est différente. En effet, l exécution de la scène Unity et son bon fonctionnement demande d avoir des points communs essentiels, comme par exemple l arrière plan de nos cibles. C est avez ces considérations que je vous engage donc à créer vous-même vos cibles et à faire vous-même vos prises de vue. L application en saura d autant plus formatrice et surtout fonctionnelle. Vous pouvez retrouver toutes mes explications sur la création de cible 3D et de Multitarget Vuforia sur mon document "Mise en place d un univers 3D". 4. Complément : modifier le projet Unity Dans tout ce qui a été dit précédemment, j ai oublié de vous parler d un élément important. En effet, si toutefois après avoir fait cette multitude d étapes vous souhaitez modifier votre projet Unity sans pour autant supprimer tout ce que vous avez fait auparavant, c est possible. Pour ce faire, il suffit de suivre les étapes suivantes 6 : 1. Dans Eclipse, faites clic droit sur "QCARUnity, puis Delete. Dans la fenêtre surgissante, cochez "Delete project contents on disk" et faites OK. À ce moment, le dossier "StagingArea" précédent a été supprimé de l emplacement où vous l aviez mis et le projet "QCARUnity" a été supprimé d Eclipse. 2. Une fois votre projet Unity modifié et buildé, retournez dans le dossier Temp du projet, et copiez-collez le dossier "StagingArea" à l emplacement de votre choix. 3. Retournez dans Ecplise puis "File/New/Project" et choisissez "Android Project from Existing Code". Pointez sur le dossier "StagingArea" que vous venez de copier, puis modifiez le nom du projet en "QCARUnity". Faites Finish. Pour les étapes qui vont suivre, je ne suis pas certain qu elles soient toutes nécessaires. Néanmoins comme on dit "vaut mieux trop que pas assez" donc je préfère être prudent sur les fichiers à copier et à supprimer. Souvent il vous sera demandé si vous souhaitez écraser les fichiers déjà existants, faites toujours "Yes To All". 4. Dans le dossier "assets" de QCARUnity, copiez le dossier "bin" et collez-le dans le dossier "assets" de QCARJava. Supprimez le dossier "assets" de QCARUnity. 5. Dans le dossier "libs" de QCARUnity, copiez le dossier "armeabi-v7a" dans le dossier "libs" de QCARJava. Supprimez le dossier "libs" de QCARUnity. 6. Dans le dossier "plugins" de QCARUnity, copiez les fichiers "QCARUnityPlayer.jar" et "Vuforia.jar" dans le dossier "libs" de QCARJava. 7. Dans le dossier "raw" de QCARUnity, copiez le dossier "QCAR" dans le dossier "assets" de QCARJava. 8. Faites maintenant clic droit sur QCARUnity et aller dans "Properties". Dans Android, cochez "IsLibrary". Puis "Apply" et "OK". 9. Faites de même clic droit sur QCARJava puis "Properties/Android". À ce moment, dans la liste des librairies, vous devriez voir une croix rouge. C est normal puisqu il cherche la librairie de tout à l heure que nous avons supprimée. Positionnez-vous dessus, puis "Remove". 6. Les étapes sont fortement semblables à celles que nous avons employées plus tôt, mais pour plus de compréhension, je préfère les répéter. 6

10. Faites alors "Add", séléctionnez "QCARUnity" puis "Apply/OK". 11. Sauvegardez et fermez Eclipse. 12. Ré-ouvrez Eclipse et faites "Project/Clean". Ça y est, vous devriez maintenant pouvoir relancer sans souci votre application, avec votre nouvelle scène Unity. Remarque Il est possible que vous obteniez les erreurs suivantes : 1. Le clean vous dit que le fichier "qcarunity.jar" n existe pas. Cela signifie qu il n a pas correctement compilé la librairie "QCARUnity". Il faut donc faire "Project/Build automatically". Le problème devrait être résolu dès lors. 2. Il est probable que si vous compilez une fois, et que vous faites des changements sur l application, qu à la deuxième compilation il vous mette une erreur. Faites simplement un autre clean du projet. Conclusion Au cours de ce document, nous avons pu voir comment importe un projet Unity dans Eclipse et l utiliser dans le cadre d un écosystème Android. Si toutefois des questions persistent relativement à ce document, n hésitez pas à vous rendre sur mon site www.loicsaillant.fr. Vous trouverez de quoi me contacter, mais également des tutoriels recoupant avec cette série de documents. 7

ANNEXES A. Fichier layout activitywelcome.xml <RelativeLayout xmlns : android=" http : / / schemas. android. com/apk/ r e s / android " xmlns : t o o l s=" http : / / schemas. android. com/ t o o l s " android : layout_width="match_parent" android : layout_height="match_parent" t o o l s : context="com. l o i c s a i l l a n t. qcarjava. WelcomeActivity " > <android. support. v7. widget. Toolbar android : id="@+id /mtoolbar" android : layout_height="? a t t r / a c t i o n B a r S i z e " android : layout_width="match_parent" android : background=" @color / green " /> <TextView android : id="@+id /mtext" android : layout_below="@id/mtoolbar" android : t e x t=" @string / intro_text " android : layout_width=" wrap_content " android : layout_height="wrap_content" android : padding="5 dip "/> <Button android : id="@+id / button1 " android : layout_below="@id/mtext" android : layout_width="match_parent" android : layout_height="80 dip " android : t e x t=" @string / cible_2d " android : t e x t S i z e="20 sp " /> <Button android : id="@+id / button2 " android : layout_below="@id/ button1 " android : layout_width="match_parent" android : layout_height="80 dip " android : t e x t=" @string / cible_3d " android : t e x t S i z e="20 sp " /> <Button android : id="@+id / button3 " android : layout_below="@id/ button2 " android : layout_width="match_parent" android : layout_height="80 dip " android : t e x t=" @string / a s s e t s " android : t e x t S i z e="20 sp " /> </RelativeLayout> 8

B. Fichier styles.xml <r e s o u r c e s > <s t y l e name="appbasetheme" parent="theme. AppCompat. NoActionBar"> </s t y l e > <! A p p l i c a t i o n theme. > <s t y l e name="apptheme" parent="appbasetheme"> </s t y l e > <c o l o r name=" green ">#f f 2 6 c 4 1 e </c o l o r > </r e s o u r c e s > C. Fichier strings.xml <?xml v e r s i o n=" 1. 0 " encoding=" utf 8"?> <r e s o u r c e s > <s t r i n g name="app_name">qcartuto</s t r i n g > <s t r i n g name=" hello_world ">Hello world!</ s t r i n g > <s t r i n g name=" a c t i o n _ s e t t i n g s ">S e t t i n g s </s t r i n g > <s t r i n g name=" title_activity_welcome ">QCARTuto</s t r i n g > <s t r i n g name=" cible_2d ">P a r t i e I : Cible 2D</s t r i n g > <s t r i n g name=" cible_3d ">P a r t i e I I : Cible 3D</s t r i n g > <s t r i n g name=" intro_text ">Mettez ce que vous voulez ; ) </s t r i n g > <s t r i n g name=" a s s e t s ">Assets </s t r i n g > <s t r i n g name=" title_activity_target_2_d ">Target_2D</s t r i n g > <s t r i n g name=" t i t l e _ a c t i v i ty_scene2_d ">Scene2D</s t r i n g > <s t r i n g name=" t i t l e _ a c t i v i t y _ q c a r j a v a _ a c t i v i t y 3 _ d "> QCARJavaActivity3D</s t r i n g > </r e s o u r c e s > D. Fichier WelcomeActivity.java package com. l o i c s a i l l a n t. qcarjava ; import android. content. I n t e n t ; import android. os. Bundle ; import android. support. v7. app. ActionBarActivity ; import android. support. v7. widget. Toolbar ; import android. view. Menu ; import android. view. MenuItem ; import android. view. View ; import android. widget. Button ; import android. widget. Toast ; public class WelcomeActivity extends ActionBarActivity { public Toolbar mtoolbar ; public Button button1 ; @Override 9

protected void oncreate ( Bundle s a v e d I n s t a n c e S t a t e ) { super. oncreate ( s a v e d I n s t a n c e S t a t e ) ; setcontentview (R. layout. activity_welcome ) ; // d e c l a r a t i o n de notre t o o l b a r mtoolbar = ( Toolbar ) findviewbyid (R. i d. mtoolbar ) ; setsupportactionbar ( mtoolbar ) ; // d e c l a r a t i o n de notre premier bouton button1 = ( Button ) findviewbyid (R. id. button1 ) ; button1. s e t O n C l i c k L i s t e n e r (new View. OnClickListener ( ) { @Override public void onclick ( View v ) { Toast. maketext ( WelcomeActivity. this, " Ouverture d Unity... ", Toast.LENGTH_SHORT). show ( ) ; I n t e n t i n t e n t = new I n t e n t ( WelcomeActivity. this, QCARJavaActivity2D. class ) ; s t a r t A c t i v i t y ( i n t e n t ) ; ) ; E. Fichier QCARJavaActivity.java package com. l o i c s a i l l a n t. qcarjava ; import android. os. Bundle ; import android. widget. Toast ; import com. qualcomm. QCARUnityPlayer. QCARPlayerNativeActivity ; import com. unity3d. p l a y e r. UnityPlayerNativeActivity ; public c l a s s QCARJavaActivity2D extends QCARPlayerNativeActivity { @Override protected void oncreate ( Bundle s a v e d I n s t a n c e S t a t e ) { super. oncreate ( s a v e d I n s t a n c e S t a t e ) ; 10