Introduction

This tutorial is a step by step guide on how to create a simple augmented relaity (AR) web application.

First of all we need to setup the toolchain that enables the project as a web page. We'll use A-Frame , an open-source web framework to create VR/AR experience, and AR.js, a Javascript library used in order to integrate AR functionalities in web apps.

Notre objectif sera d'afficher le texte "Hello" sur un marqueur AR de type code-barres. Puis de customiser le contenu. Our Goal is to display the "Hello" text, on an AR marker of the barcode typen, then we'll see how to customize the content.

We'll use th efollowing free tools: -github: to version your code and host it for free -projectIDX, now known as Google Firebase: it is an IDE (integrated development environment) that allows to write code and connects to your github repo to sort out the changes made to your code.

Requirements

• having a Github account

• having a Gmail account

• a computer

• a code editor, our tools will be : Firebase Studio)

• a decent web browser(Chrome, Firefox ...)

• a smartphone running a web browser (Chrome, Firefox ...)

Here we go!

📽️Speedrun video (French, sorry!):

• this tutorial is waaay too long...
• in fact , it takes < 10 minutes !

speedrun_edit_4.mp4

Step 1 : Create a GitHub account and a repository

• If you don't already have one, point your browser to https://github.com/signup?source=login and create an account. ** ☢️ The username you pick we'll be used in the URL you'll have to type in to reach your project. Pick a short name, without any space, or any accented character (çêœöü etc.)** ☢️ Le nom d'utilisateur que vous choisissez sera utilisé pour l'adresse qu'il faudra tapper pour voir votre projet. Choisissez un nom court ! sans espaces, sans caractères spéciaux (accents, cédille, etc.)

- Create a new repository: once logged in, click on the "New repository" button. Give a name to your repo (for instance, "microprojectAr"), add a facultative description, and click on the "Create repoository".

Step 2 : activate GitHub Pages

Let's setup Github Pages, to allow our project to be hosted on github servers located under the follwoing pattern: :

https://[vyour-username].github.io/[your-repository]

• Look for the parameters : Dans votre dépôt, cliquez sur l'onglet "Settings", puis sur l'onglet "Pages"

• Sélectionner la branche : Dans la section "GitHub Pages", sélectionnez la branche "main" (ou la branche principale de votre dépôt).
• Enregistrer les modifications : Cliquez sur le bouton "Save". Votre site GitHub Pages sera maintenant accessible à l'adresse https://[votre-nom-utilisateur].github.io/[microprojetAr].

Si vous revenez sur la page d'accueil de votre projet, vous remarquerez au bout de quelques minutes, que certains éléments ont changés. Un déploiement est maintenant disponible !

Toute l'infrastructure nécessaire pour héberger votre projet est donc bien en place, il suffit maintenant d'ajouter du contenu.

Étape 3 : Utiliser Project IDX

Rendez-vous sur le site de projetIDX et connectez-vous.

Importer le dépôt : Utilisez l'option pour importer votre dépôt GitHub dans Project IDX.

Copiez l'adresse du dépot créé précédemment.

Configurer le projet pour un usage de développement web.

• Créer un dossier ".idx":

  

• Dans ce dossier, créer un fichier nommé "dev.nix"

  
  Pour arriver à ce résultat :
  

• Copier le code de configuration de l'environnement de développement dans le fichier "dev.nix" que vous venez de créer. (Ce fichier va nous permettre de tester notre code directement dans projetIDX et aussi de tester sur notre téléphone).

    # To learn more about how to use Nix to configure your environment
  # see: https://developers.google.com/idx/guides/customize-idx-env
  { pkgs, ... }: {
    # Which nixpkgs channel to use.
    channel = "stable-23.11"; # or "unstable"
    # Use https://search.nixos.org/packages to find packages
    packages = [
      pkgs.nodejs_20
      pkgs.python3
    ];
    # Sets environment variables in the workspace
    env = {};
    idx = {
      # Search for the extensions you want on https://open-vsx.org/ and use   "publisher.id"
      extensions = [
        # "vscodevim.vim"
      ];
      # Enable previews and customize configuration
      previews = {
        enable = true;
        previews = {
          web = {
            command = ["python3" "-m" "http.server" "$PORT" "--bind" "0.0.0.0"];
            manager = "web";
          };
        };
      };
      # Workspace lifecycle hooks
      workspace = {
        # Runs when a workspace is first created
        onCreate = {
          # Example: install JS dependencies from NPM
          # npm-install = "npm install";
          # Open editors for the following files by default, if they exist:
          default.openFiles = [ "style.css" "main.js" "index.html" ];
        };
        # Runs when the workspace is (re)started
        onStart = {
          # Example: start a background task to watch and re-build backend code
          # watch-backend = "npm run watch-backend";
        };
      };
    };
  }
  

Votre environnement de travail devrait ressembler à ceci :

Il ne vous reste plus qu'à cliquer sur le bouton "Rebuild Environment" et c'est bon !

Étape 4 : Créer la page HTML

Créer un fichier index.html : Dans votre projet IDX, créez un fichier nommé "index.html".

Ajouter le code HTML : Copiez et collez le code HTML suivant dans votre fichier index.html :

<!DOCTYPE html>
<html>

<head>
  <title>Ma première app AR</title>
  <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
  <script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js"></script> 
</head>

<body>
    <a-scene embedded
    arjs="sourceType: webcam; detectionMode: mono_and_matrix; matrixCodeType: 3x3; trackingMethod: best ; changeMatrixMode: modelViewMatrix;"
    renderer="sortObjects: true; antialias: true; colorManagement: true; logarithmicDepthBuffer: true;"

    vr-mode-ui="enabled: false"

    smooth=" true" smoothCount="5" smoothTolerance=".05" smoothThreshold="5"
    
    sourceWidth="800" sourceHeight="600" displayWidth="1280" displayHeight="720">

      
        <a-marker type='barcode' value='2'>
   
            <a-text value="Hello !" 
            side="double" position = "0 0 -1" rotation="270 0 0" 
            width="8"
            color="red" align="center" >
            </a-text>

        </a-marker>

        <a-entity camera></a-entity>
  </a-scene>
</body>
</html>

Étape 5 : Comprendre le code

Ce code créer une expérience simple de réalité augmentée (RA) en utilisant A-Frame et AR.js. Décomposons ce que fait chaque partie :

Si vous n'êtes pas à l'aise et ne connaissez pas du tout la manière dont du code html fonctionne cliquez sur le petit triangle pour déplier une explication des bases de la syntaxe html

💡 les bases html

Une page HTML est comme un sandwich. Elle a besoin d'un pain du haut et d'un pain du bas pour contenir la garniture !

Le pain du haut et du bas, ce sont les balises <html> et </html>. Elles indiquent au navigateur que le contenu entre ces balises est du code HTML.

Deux parties principales : À l'intérieur du "sandwich HTML", on trouve deux parties :

La tête (<head> et </head>) : C'est comme les informations sur l'emballage du sandwich. On y met des informations importantes pour le navigateur, mais qui ne sont pas affichées directement à l'utilisateur.

Par exemple :

• Le titre de la page <title> qui décrit au navigateur quoi afficher dans la barre d'onglets.

• Des liens vers des fichiers CSS pour charger la mise en page

• Des liens vers des fichiers JavaScript pour les fonctionnalités interactives

Le corps (<body> et </body>) : C'est la garniture du sandwich ! C'est le contenu visible de la page web : texte, images, vidéos, etc.

La syntaxe et donc l'interprétation par le navigateur du code html repose sur des balises ouvrantes et fermantes :

• La balise ouvrante (par exemple <p>) dit au navigateur : "Attention, on commence un paragraphe !"
• La balise fermante (par exemple </p>) dit : "Voilà, le paragraphe est terminé."

Tout le contenu entre la balise ouvrante et la balise fermante est considéré comme faisant partie de cet élément.

Exemple :

<html>
<head>
  <title>Ma page web</title>
</head>
<body>
  <h1>Bienvenue !</h1>
  <p>Ceci est un paragraphe de texte.</p>
</body>
</html>

Dans cet exemple :

• <html> ouvre la page HTML et </html> la ferme.
• <head> ouvre la section d'en-tête et </head> la ferme.
• <title> ouvre le titre de la page et </title> le ferme.
• <body> ouvre le corps de la page et </body> le ferme.
• <h1> ouvre un titre de niveau 1 et </h1> le ferme.
• <p> ouvre un paragraphe et </p> le ferme.

Ici nous avons une structure HTML classique : Le code met en place une page HTML basique avec les sections et .

Dans la partie <head>, nous ajoutons :

• le titre de l'expérience

  <title>Ma première app AR</title>

• la Bibliothèque A-Frame : Il inclut la bibliothèque A-Frame (aframe.min.js) qui est un framework JavaScript permettant de créer des expériences de réalité virtuelle (RV) et de RA en utilisant du HTML. Une bibliothèque est simplement du code que l'on ammène dans le projet pour ajouter des fonctionnalités supplémentaires. Un framework est une bibliothèque qui nécessite de respecter certaines regles pour bien marcher, mais en echange un framework est plus puissante qu'une bibliothèque normale.

  <script src="https://aframe.io/releases/1.3.0/aframe.min.js"></script>

• la Bibliothèque AR.js : Il inclut la bibliothèque AR.js (aframe-ar.js) qui ajoute des capacités de RA à A-Frame.

  <script src="https://raw.githubusercontent.com/jeromeetienne/AR.js/master/aframe/build/aframe-ar.js"></script>  

Dans la partie <body>, et c'est ici que tout ce joue pour le contenu visible par l'utilisateur. Nous ajoutons :

• la scène RA : L'élément <a-scene> crée la scène de RA.

  <a-scene embedded
    arjs="sourceType: webcam; detectionMode: mono_and_matrix; matrixCodeType: 3x3; trackingMethod: best ; changeMatrixMode: modelViewMatrix;"
    renderer="sortObjects: true; antialias: true; colorManagement: true; physicallyCorrectLights; logarithmicDepthBuffer: true;"
  
    vr-mode-ui="enabled: false"
  
    smooth=" true" smoothCount="5" smoothTolerance=".05" smoothThreshold="5"
    
    sourceWidth="800" sourceHeight="600" displayWidth="1280" displayHeight="720">
  
        <!-- contenu de l'expérience AR avec d'autres balises -->
  
  </a-scene>

  Remarquez que dans la balise ouvrante <a-scene> nous ajoutons beaucoup d'options (qui s'appellent attributs en html) pour configuer la manière dont la scène va s'afficher.

  💡 les détails des options de configuration de l'attribut arjs

  - *embedded* : Cet attribut indique à A-Frame d'intégrer la scène dans la page HTML.

  • arjs : Cet attribut configure AR.js
    • sourceType: webcam : Utilise la webcam de l'appareil comme source vidéo.
    • detectionMode: mono_and_matrix : Détecte à la fois les images cibles et les marqueurs de type code-barres.
    • matrixCodeType: 3x3 : Spécifie que le type de code-barres utilisé est un code-barres matriciel 3x3.
    • trackingMethod: best : Utilise la meilleure méthode de suivi disponible.
    • changeMatrixMode: modelViewMatrix : Mode de changement de matrice pour le suivi.
    • vr-mode-ui="enabled: false" : Désactive l'interface utilisateur du mode VR.
    • renderer. Configure le rendu de la scène avec des options pour le tri des objets, l'antialiasing, la gestion des couleurs, etc.
    • smooth : Active le lissage du mouvement de la caméra.
  
  

• Le marqueur : L'élément <a-marker> définit un marqueur de type code-barres avec la valeur '2'. Lorsque la caméra détecte ce marqueur, le contenu à l'intérieur de la balise sera affiché en RA.

  <a-marker type='barcode' value='2'>
    <!-- ajouter du contenu qui sera visible par l'utilisateur et donc ancré sur notre marqueur -->
  </a-marker>

  Ici la valeur 2 correspond à un motif précis qui a été prédécoupé pour vous à la découpeuse de stickers. Avec la technique que nous utilisons il existe 64 motifs différents qui peuvent être détectés en même temps par arjs.

• Un texte : L'élément crée un texte en 3D qui sera affiché au-dessus du marqueur. Le texte est "Hello !", de couleur rouge et centré.

  <a-text value="Hello !" 
            side="double" position = "0 0 -1" rotation="270 0 0" 
            width="8"
            color="red" align="center" >
  </a-text>

  💡 les détails des attributs de la balise a-text

  - *value* : Le texte à afficher. - *side=double* : permet d'afficher le texte quelque soit l'angle sous lequel on le regarde. - *position="0 0 -1" : la position xyz du centre du texte par rapport au centre du marqueur. - *rotation="270 0 0"* : - *width="8"* : la largeur du texte. - *color="red"* : la couleur du texte. - *align="center"* : l'alignement du texte.
  
  

• Caméra : L'élément <a-entity camera> définit la caméra de la scène, le fonctionnement par défaut nous convient parfaitement, mais il est possible d'ajouter des fonctionalités comme par exemple l'interaction via l'orientation du regard ('gaze' interaction).

En résumé, ce code crée une expérience de RA où un texte apparaît dans un esapce 3D lorsque le marqueur code-barres 2 est détecté par la caméra.

Étape 6 : Tester

• Enregistrer les modifications : Enregistrez votre fichier index.html.

• Tester votre projet : Affichez la webview de votre projet.

  

  ☣️ Il peut arriver que la webview disparaisse ... Dans ce cas là vous pouvez faire apparaitre la "palette de commande" en (Cmd+Maj+P sur Mac ou Ctrl+Maj+P pour les autres systèmes), puis sélectionnez ou tappez "Show Web Preview" (Afficher l'aperçu sur le Web).

  

  Vous pouvez alors visionner votre page en plein écran en cliquant sur le petit icône en haut à droite.

  

  Cela ouvrira votre expérience dans un nouvel onglet sur votre ordinateur. A ce stade vous devriez voir : une page web vous montrant vous !

  Si vous montrez le marqueur à la caméra vous devriez voir ceci :

  

  Votre projet fonctionne donc dans l'éditeur et avec la caméra de votre ordinateur.

  Vous pouvez maintenant le tester sur votre smartphone. Il vous suffit de vous rendre sur la page que vous venez d'ouvrir.

  Pour cela vous pouvez cliquer sur l'icône "lien" en haut à droite à côté de l'icône pour ouvrir dans une nouvelle fenêtre. Scannez le qr code et vous voilà avec la page chargée sur votre téléphone.

  

Vous pouvez ensuite répéter ces opérations en changeant le code, sauvegardant et en actualisant la page.

Essayer par exemple de changer le texte, sa couleur, sa taille, sa position etc.

Étape 7 : Publier l'application

Commiter les modifications : Utilisez les outils de versioning de Project IDX pour commiter vos changements et les pousser sur votre dépôt GitHub.

• Cliquer sur le bouton source control de projetIDX

  

• 'Stager' les changements en cliquant sur le "+"

  

• 'Commiter' les changements en cliquant sur le bouton 'commit'

  

• Synchroniser les changements en cliquant sur le bouton 'commit'

  

Cette dernière opération va envoyer vos changements à votre dépot github et du coup mettre à jour la page mise en ligne.

Votre expérience est maintenant déployée à l'adresse : https://[votre-nom-utilisateur].github.io/[votre-depot]

✨ Félicitations ! ✨ Vous avez créé votre première application AR. Vous pouvez maintenant personnaliser votre application en modifiant le texte, en ajoutant des modèles 3D, et en expérimentant avec différentes fonctionnalités d'A-Frame et AR.js.

Note : Ce tutoriel est une introduction de base. Pour approfondir vos connaissances, consultez la documentation officielle d'A-Frame et AR.js.

Étape 8 : Encoder le sticker RFID

Notre but est de programmer notre sticker RFID pour que lorsque nous approchons notre téléphone, celui-ci va nous proposer d'ouvrir la page web hébergeant notre projet.

Pour cela nous allons utiliser NFCTools qui est gratuit et qui est disponible pour Android ou iOS?.

• Choisir l'onglet "Ecrire" et sélectionner "ajouter un enregistrement"
  
• Choisir "URL/URI"
  
• Entrer l'adresse de votre page puis valider
  
• Vous pouvez maintenant cliquer sur le bouton "Ecrire" sous le champ "Plus d'options"
  
• Vous devrier voir cet écran vous demandant d'approcher votre smartphone du sticker.
  
• Une fois que vous avez réussi à détecter votre sticker, l'écriture devrait s'effectuer
  

Normalement c'est bon ! Vous pouvez fermer NFCTools et tester !

Pour aller plus loin ...

Un cours entier en anglais est disponible sur le site de l'ateliernum à cette adresse : https://github.com/b2renger/Introduction_A-frame#introduction_a-frame

Personnaliser l'apparence : Ajouter d'autres éléments, modifier les couleurs, les tailles et les positions des éléments.

Ajouter des modèles 3D : Importer des modèles 3D dans votre scène.

Utiliser d'autres types de marqueurs : Explorer les différents types de marqueurs AR.

Créer des interactions : Ajouter des événements et des interactions à votre application.