Tutoriel : Connecter votre visualisation de simulation à Bonsai

Article
11/08/2022

Le contenu suivant prend en charge la phase ASSEMBLE dans le Bonsai parcours utilisateur

Suivez ce tutoriel pour savoir comment :

Quels sont les visualiseurs web.
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 en particulier. Si vous n’avez jamais codé en Javascript auparavant, nous vous recommandons de suivre le parcours d’apprentissage Développement web pour 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.
NPM doit être installé.

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 créé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 créé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 de l’interface Bonsai utilisateur.

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

Le Bonsai plug-in visualiseur connecte des visualisations web de votre état de simulation et de votre espace d’action à votre Bonsai espace de travail. Les visualisations connectées se chargent dans l’interface Bonsai utilisateur avec 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 du visualiseur

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

Paramètre de requête (_theme) pour passer du mode clair au mode sombre.
Variables personnalisables pour la position du chariot et l’angle de 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 panier, le poteau 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 des constantes utiles pour accéder aux données de paramètres personnalisés 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 visualiseur prend en charge un paramètre de requête réservé, _theme pour basculer entre le mode clair et le mode 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 correctement la page web

Ajoutez du code à la <script> balise pour initialiser la 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

Ouvrez une fenêtre de console et installez le local-web-server package NPM :
```
npm install -g local-web-server
```

Servez votre page HTML sur le port 8080 :

ws -p 8080 --spa PATH_TO_YOUR_HTML_FILE

Ouvrez http://localhost:8080 dans votre navigateur pour vérifier que le visualiseur est accessible et rendu correctement.

Étape 7 : Connecter votre visualiseur à un Bonsai cerveau

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

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

Exemple de visualiseur web

Nettoyage

Lorsque vous avez terminé :

Arrêtez l’entraînement dans l’interface Bonsai utilisateur.
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 du 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 l’URL de votre visualiseur est :

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

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

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 de visualiseur et en effectuant les ajustements appropriés dans le cadre de votre init fonction.

Messages d’événements du visualiseur

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

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

type de message	Description
`IterationUpdate`	Contient toutes les données disponibles pour une itération unique au sein d’un épisode.

Important

Les visualiseurs doivent ignorer tout message entrant avec un type qu’ils ne reconnaissent 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, la valeur de récompense, les indicateurs de terminal, les limites des épisodes.
state : données d’état pour l’itération actuelle.
action : action résultante de l’itération actuelle.
episode : index unique permettant d’identifier l’épisode dans une séquence d’un ou plusieurs épisodes. L’index d’épisode est utile pour noter quand le visualiseur est invité à afficher des données 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 se présenter 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é pendant l’entraînement.

Étapes suivantes

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