Tutoriel : Connecter votre visualisation de simulation à Bonsai

Suivez ce tutoriel pour savoir comment :

  • Quels visualiseurs web sont.
  • Fonctionnement du plug-in Visualiseur.
  • Comment créer un visualiseur de base pour l’exemple de cerveau Cartpole.

Avant de commencer

  • Vous devez être familiarisé avec le développement web de base. Les instructions ci-dessous supposent que vous comprenez les principes de base du développement web et du codage Javascript spécifiquement. Si vous n’avez jamais codé dans Javascript avant, nous vous recommandons de suivre le cours MS Learn : Développement web pour les débutants avant de continuer.
  • Vous devez être familiarisé avec JSON. Les instructions ci-dessous partent du principe que vous comprenez la structure de base d’un objet JSON. Si vous n’avez jamais travaillé avec JSON auparavant, avant de continuer, nous vous recommandons de consulter la section À propos du format JSON de Utilisation de fichiers CSV et JSON.
  • Vous devez installer NPM.

Qu’est-ce qu’un visualiseur web ?

Il existe deux types de visualiseurs de simulation :

  • Visualiseurs incorporés
  • Visualiseurs web

Les visualiseurs incorporés sont générés dans le cadre du simulateur associé. Vous pouvez voir des exemples de visualiseurs incorporés lorsque vous entraînez les exemples de cerveaux Cartpole et Moab dans Bonsai.

Les visualiseurs web sont générés indépendamment du simulateur associé en tant qu’application web. L’application web accepte les messages POST avec des informations d’état et affiche une représentation appropriée de la simulation. Vous fournissez l’URL de votre visualiseur et Bonsai chargez l’application web dans un IFrame dans l’interface Bonsai utilisateur.

Qu’est-ce que le Bonsai plug-in du visualiseur ?

Le Bonsai plug-in de visualiseur connecte des visualisations web de votre état de simulation et de l’espace d’action à votre Bonsai espace de travail. Les visualisations connectées sont chargées dans l’interface Bonsai utilisateur, ainsi que les données d’épisode pour faciliter la compréhension des résultats des épisodes.

Le plug-in Visualiseur utilise l’API Window.postMessage() web pour communiquer avec votre application web via l’IFrame. Par conséquent, les visualiseurs peuvent être écrits dans n’importe quel langage ou infrastructure capable de traiter les messages POST. Par exemple, JavaScript, Node.js ou une infrastructure web comme React ou Angular.

Exemples d’éléments de visualiseur

Suivez les étapes ci-dessous pour créer un visualiseur web de base pour l’exemple de cerveau Cartpole dans Bonsai ce qui inclut :

  • Paramètre de requête (_theme) à modifier entre le mode clair et le mode sombre.
  • Variables personnalisables pour la position du chariot et l’angle du pôle.
  • Gestionnaire d’événements pour Window.postMessage recevoir des données d’état à partir de Bonsai.

Étape 1 : Créer une page HTML de base

Commencez par créer une page HTML qui inclut les éléments visuels du visualiseur. L’exemple de code ci-dessous définit deux éléments :

  • un bloc de code (jsonBox) pour afficher les informations d’état brut reçues.
  • image SVG composée de trois rectangles qui représentent le chariot, le pôle et la piste.
<html>

<head>
  <title>Cartpole Visualizer</title>

  <script language="JavaScript">
    // Javascript code for the visualizer goes here
  </script>
</head>

<body>
<table width="100%">
<tr>
<td width="30%">
  <svg preserveAspectRatio="xMidYMid meet" height="100%" width="100%" viewBox="-1 -1 2 2">
    <rect id="track" x="-0.5"   y="-0.025" width="1"    height="0.05" fill="#333" />
    <rect id="cart"  x="-0.15"  y="-0.05"  width="0.3"  height="0.1"  fill="#ccc" />
    <rect id="pole"  x="-0.025" y="-0.5"   width="0.05" height="0.5"  fill="#999" />
  </svg>
</td>
<td>
  <pre id="jsonBox" style="display: box;">Waiting...</pre>
</td></tr>
</table>
</body>

</html>

Étape 2 : Créer des constantes pour accéder aux paramètres de requête

Ajoutez du code à la <script> balise pour définir certaines constantes utiles pour accéder aux données de paramètre personnalisées et personnaliser les POST clés de données :

// Grab any URL parameters that were provided
const params = new URLSearchParams(window.location.search);
const darkMode = params.get('_theme') === 'dark';

// [OPTIONAL] Override the state parameter names if needed
const positionKey = params.has('pos') ? params.get('pos') : 'cart_position';
const angleKey    = params.has('angle') ? params.get('angle') : 'pole_angle';

Les noms des paramètres d’état doivent correspondre aux noms passés par le simulateur. L’ajout d’instructions de remplacement peut faciliter l’utilisation de votre visualiseur sur différentes simulations du même événement.

Étape 3 : Créer une fonction pour définir le thème d’affichage

Le plug-in du visualiseur prend en charge un paramètre de requête réservé, _theme pour basculer entre le mode clair et sombre. Pour personnaliser le comportement du thème, ajoutez du code à la <script> balise pour modifier les couleurs d’affichage en fonction de la valeur de _theme:

function setTheme() {

  // Define JS objects for the SVG elements and code box
  const pole = document.getElementById('pole');
  const cart = document.getElementById('cart');
  const track = document.getElementById('track');
  const jsonBox = document.getElementById('jsonBox');

  // Adjust the visualizer colors based upon the selected theme 
  if (darkMode) {
    document.body.style.backgroundColor = '#333';
    document.body.style.color = '#fff';

    track.style.fill = '#000';
    cart.style.fill = '#555';
    pole.style.fill = '#aaa';
  }
  else {
    document.body.style.backgroundColor = '#fff';
    document.body.style.color = '#000';

    track.style.fill = '#333';
    cart.style.fill = '#ccc';
    pole.style.fill = '#999';
  }  
}

Étape 4 : Ajouter la fonction de mise à jour du visualiseur

Ajoutez du code à la <script> balise pour mettre à jour le contenu de la page en fonction des nouvelles informations d’état transmises par Bonsai:

function updateVisualizer() {

  // Define JS objects for the SVG elements and code box
  const pole = document.getElementById('pole');
  const cart = document.getElementById('cart');
  const track = document.getElementById('track');
  const jsonBox = document.getElementById('jsonBox');

  // Grab the message data 
  var jsonData = JSON.parse(event.data);
          
  // Pull out the state info and convert units 
  var position = jsonData.state[positionKey];
  var angle = (jsonData.state[angleKey] * 180.0) / Math.PI;

  // Convert message to formatted JSON text for display 
  var jsonString = JSON.stringify(jsonData, null, 4);

  // Update the code block and positions of graphical elements 
  jsonBox.textContent = jsonString;
  cart.setAttribute('transform', `translate(${position} 0)`);
  pole.setAttribute('transform', `translate(${position} 0) rotate(${angle} 0 0)`);  
}

Étape 5 : Ajouter du code pour initialiser la page web correctement

Ajoutez du code à la balise pour initialiser la <script> page web lorsqu’elle se charge avec le thème d’affichage correct et définissez l’écouteur d’événement.

function init() {

  // Adjust the visualizer colors based upon the selected theme 
  setTheme();
        
  // Add an event listener to catch messages from Bonsai
  window.addEventListener('message', updateVisualizer, false);
}

// Run the init() function when the window loads
window.onload = init;

Étape 6 : Héberger l’application visualiseur localement

  1. Ouvrez une fenêtre de console et installez le local-web-server package NPM :
    npm install -g local-web-server
    
  2. Servez votre page HTML sur le port 8080 :
    ws -p 8080 --spa PATH_TO_YOUR_HTML_FILE
    
  3. Ouvrez http://localhost:8080 votre navigateur pour confirmer que le visualiseur est accessible et rendu correctement.

Étape 7 : Connecter votre visualiseur à un Bonsai cerveau

  1. Ouvrez l’interfaceBonsai utilisateur.
  2. Créez un cerveau en sélectionnant l’exemple Cartpole .
  3. En bas du fichier Inkling, commentez la référence du visualiseur par défaut et ajoutez un lien à votre application web :
    #const SimulatorVisualizer = "/cartpoleviz/"
    const SimulatorVisualizer="http://localhost:8080"
    

Commencez à entraîner le cerveau pour voir le visualiseur en action.

Sample web visualizer

Capture d’écran de l’exemple de visualiseur Cartpole s’exécutant dans l’interface Bonsai utilisateur avec les données POST répertoriées en regard d’une présentation graphique de tha cart et de pole.

Nettoyage

Lorsque vous avez terminé :

  1. Arrêtez l’entraînement dans l’interface Bonsai utilisateur.
  2. Arrêtez le serveur web local. Sur la plupart des systèmes, vous pouvez utiliser Ctrl-C pour arrêter le processus.

Configuration du comportement du visualiseur

Vous pouvez utiliser n’importe quel nombre de paramètres de requête pour transmettre des informations de configuration personnalisées à un visualiseur. Par exemple, pour fournir des mappages entre l’espace d’état de concept et les variables internes utilisées par le visualiseur.

En plus des paramètres de requête spécifiés dans l’URL du visualiseur, Bonsai ajoute un ensemble de paramètres de requête réservés lors du chargement d’un visualiseur avec le plug-in. Par exemple, si votre URL de visualiseur est la suivante :

http://localhost:8080/?someParam=1&anotherParam=true

l’URL complète envoyée au plug-in est la suivante :

http://localhost:8080/?someParam=1&anotherParam=true&_theme=light&_lang=en&_prefsKey=12345`

Tous les paramètres de requête réservés commencent par un trait de soulignement :

  • _theme: indique le thème d’affichage qui doit être utilisé pour l’application visualiseur lorsqu’il est affiché dans l’interface Bonsai utilisateur. Doit être light ou dark.
  • _lang: Indique la langue préférée pour la localisation. Doit être en.
  • _prefsKey: clé unique utilisée par le visualiseur pour enregistrer les préférences utilisateur pour différentes instances du visualiseur dans l’application Bonsai .

Vous pouvez personnaliser le comportement des paramètres par défaut en les interceptant dans votre application visualiseur et en effectuant les ajustements appropriés dans votre init fonction.

Messages d’événements du visualiseur

La bibliothèque Microsoft Bonsai Visualiseur fournit des définitions d’interface Javascript pour créer des visualiseurs détaillés Bonsai .

Le plug-in visualiseur fournit actuellement les messages entrants suivants :

type de message Description
IterationUpdate Contient toutes les données disponibles pour une seule itération dans un épisode.

Important

Les visualiseurs doivent ignorer tout message entrant avec un type qu’il ne reconnaît pas.

ItérationUpdate

IterationUpdate les messages incluent les champs suivants :

  • version : Actuellement « 1.0 ».
  • type : indique le type de message. Par exemple, « ItérationUpdate ».
  • config : contient toutes les informations de configuration utilisées pour initialiser l’épisode.
  • meta : contient des champs de métadonnées pour l’itération. Par exemple, valeur de récompense, indicateurs de terminal, limites d’épisode.
  • état : données d’état pour l’itération actuelle.
  • action : action résultante pour l’itération actuelle.
  • épisode : index unique pour identifier l’épisode dans une séquence d’un ou plusieurs épisodes. L’index d’épisode est utile pour noter lorsque le visualiseur est invité à afficher des données provenant de différents épisodes.
  • itération : Index de séquence pour les données d’itération dans un épisode. Notez que le simulateur doit être sans état et que les itérations peuvent être fournies dans n’importe quel ordre, car les données suivent les interactions utilisateur.

Notes

Les variables de configuration, d’état et d’action correspondent toujours aux variables du fichier Inkling utilisé lors de l’entraînement.

Étapes suivantes

Essayez d’expérimenter des exemples de visualisation plus avancés pour Cartpole ou Moab.