Självstudie: Anslut simuleringsvisualiseringen tillBonsai

Följ den här självstudien för att lära dig:

  • Vad webbvisualiserare är.
  • Så här fungerar plugin-programmet Visualizer.
  • Så här skapar du en grundläggande visualiserare för Cartpole-provhjärnan.

Innan du börjar

  • Du måste känna till grundläggande webbutveckling. Anvisningarna nedan förutsätter att du förstår grunderna i webbutveckling och Javascript-kodning specifikt. Om du aldrig har kodat i Javascript tidigare rekommenderar vi att du går kursen MS Learn: Web Development for Beginners innan du fortsätter.
  • Du måste vara bekant med JSON. Anvisningarna nedan förutsätter att du förstår grundstrukturen för ett JSON-objekt. Om du aldrig har arbetat med JSON tidigare rekommenderar vi att du läser avsnittet Om JSON-format i Arbeta med CSV- och JSON-filer innan du fortsätter.
  • Du måste ha NPM installerat.

Vad är en webbvisualiserare?

Det finns två typer av simuleringsvisualiserare:

  • Inbäddade visualiseringar
  • Webbvisualiserare

Inbäddade visualiseringar skapas som en del av den relaterade simulatorn. Du kan se exempel på inbäddade visualiserare när du tränar Cartpole- och Moab-provhjärnorna i Bonsai.

Webbvisualiseringar skapas oberoende av den relaterade simulatorn som ett webbprogram. Webbprogrammet accepterar POST-meddelanden med tillståndsinformation och återger en lämplig representation av simuleringen. Du anger URL:en för din visualiserare och Bonsai läser in webbappen i en IFrame i användargränssnittet Bonsai .

Vad är plugin-programmet visualiserare Bonsai ?

Plugin-programmet Bonsai visualiserare ansluter webbvisualiseringar av simuleringstillståndet och åtgärdsutrymmet till din Bonsai arbetsyta. Anslutna visualiseringar läses in i användargränssnittet Bonsai tillsammans med avsnittsdata för att göra det lättare att förstå avsnittsresultat.

Visualizer-plugin-programmet använder webb-API:et Window.postMessage() för att kommunicera med din webbapp via IFrame. Därför kan visualiserare skrivas på valfritt språk eller ramverk som kan bearbeta POST-meddelanden. Till exempel JavaScript, Node.js eller ett webbramverk som React eller Angular.

Exempel på visualiseringselement

Följ stegen nedan för att skapa en grundläggande webbvisualiserare för Cartpole-provstjärnan i Bonsai som innehåller:

  • En frågeparameter (_theme) för att ändra mellan ljust och mörkt läge.
  • Anpassningsbara variabler för vagnens position och polvinkel.
  • En händelsehanterare för Window.postMessage att ta emot tillståndsdata från Bonsai.

Steg 1: Skapa en grundläggande HTML-sida

Börja med att skapa en HTML-sida som innehåller visualiserarens visuella element. Exempelkoden nedan definierar två element:

  • ett kodblock (jsonBox) för att visa råtillståndsinformationen som tagits emot.
  • en SVG-bild som består av tre rektanglar som representerar vagnen, stången och spåret.
<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>

Steg 2: Skapa konstanter för att komma åt frågeparametrar

Lägg till kod i taggen <script> för att definiera några användbara konstanter för att komma åt anpassade parameterdata och anpassa datanycklarna POST :

// 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';

Tillståndsparameternamnen måste matcha namnen som skickas av simulatorn. Om du lägger till åsidosättningsuttryck blir det enklare för visualiseraren att arbeta med olika simuleringar av samma händelse.

Steg 3: Skapa en funktion för att ange visningstemat

Plugin-programmet visualiserare stöder en reserverad frågeparameter för _theme att växla mellan ljust och mörkt läge. Om du vill anpassa temabeteendet lägger du till kod i taggen <script> för att ändra visningsfärgerna baserat på värdet _themeför :

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';
  }  
}

Steg 4: Lägg till visualiserarens uppdateringsfunktion

Lägg till kod i taggen <script> för att uppdatera sidinnehållet baserat på den nya tillståndsinformationen som skickas av 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)`);  
}

Steg 5: Lägg till kod för att initiera webbsidan korrekt

Lägg till kod i taggen <script> för att initiera webbsidan när den läses in med rätt visningstema och ange händelselyssnaren.

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;

Steg 6: Värd för visualiseringsappen lokalt

  1. Öppna ett konsolfönster och installera NPM-paketet local-web-server :
    npm install -g local-web-server
    
  2. Visa HTML-sidan på port 8080:
    ws -p 8080 --spa PATH_TO_YOUR_HTML_FILE
    
  3. Öppna http://localhost:8080 i webbläsaren för att bekräfta att visualiseraren är tillgänglig och återges korrekt.

Steg 7: Anslut din visualiserare till en Bonsai hjärna

  1. Öppna användargränssnittetBonsai.
  2. Skapa en ny hjärna genom att välja Cartpole-exemplet .
  3. Längst ned i Inkling-filen kommenterar du ut standardreferensen för visualiseraren och lägger till en länk i webbappen:
    #const SimulatorVisualizer = "/cartpoleviz/"
    const SimulatorVisualizer="http://localhost:8080"
    

Börja träna hjärnan för att se hur visualiseraren fungerar.

Sample web visualizer

Skärmbild av cartpole-exempelvisualiseraren som körs i användargränssnittet Bonsai med POST-data listade bredvid en grafisk presentation av tha cart och pole.

Rensa

När du är klar:

  1. Sluta träna i användargränssnittet Bonsai .
  2. Stoppa den lokala webbservern. På de flesta system kan du använda Ctrl-C för att stoppa processen.

Konfigurera beteende för visualiserare

Du kan använda valfritt antal frågeparametrar för att skicka anpassad konfigurationsinformation till en visualiserare. Till exempel för att tillhandahålla mappningar mellan begreppet tillståndsutrymme och interna variabler som används av visualiseraren.

Förutom frågeparametrar som anges i visualiserarens URL lägger Bonsai till en uppsättning reserverade frågeparametrar när du läser in en visualiserare med plugin-programmet. Om din visualiserar-URL till exempel är:

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

den fullständiga URL:en som skickas till plugin-programmet är:

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

Alla reserverade frågeparametrar börjar med ett understreck:

  • _theme: Anger det visningstema som ska användas för visualiserarappen när det visas i användargränssnittet Bonsai . Måste vara light eller dark.
  • _lang: Anger önskat språk för lokalisering. Måste vara en.
  • _prefsKey: En unik nyckel som används av visualiseraren för att spara användarinställningar för olika instanser av visualiseraren Bonsai i appen.

Du kan anpassa beteendet för standardparametrarna genom att fånga dem i visualiseringsappen och göra lämpliga justeringar som en del av din init funktion.

Händelsemeddelanden för Visualizer

Microsoft Bonsai Visualizer-biblioteket innehåller Javascript-gränssnittsdefinitioner för att skapa detaljerade Bonsai visualiseringar.

Visualizer-plugin-programmet innehåller för närvarande följande inkommande meddelanden:

Meddelandetyp Description
IterationUpdate Innehåller alla tillgängliga data för en enskild iteration i ett avsnitt.

Viktigt

Visualiserare bör ignorera alla inkommande meddelanden med en typ som den inte känner igen.

IterationUpdate

IterationUpdate meddelanden innehåller följande fält:

  • version: För närvarande "1.0".
  • type: Anger meddelandetypen. Till exempel "IterationUpdate".
  • config: Innehåller all konfigurationsinformation som används för att initiera avsnittet.
  • meta: Innehåller metadatafält för iterationen. Till exempel belöningsvärde, terminalflaggor, avsnittsgränser.
  • state: Tillståndsdata för den aktuella iterationen.
  • action: Den resulterande åtgärden för den aktuella iterationen.
  • episode: Ett unikt index för att identifiera episoder inom en sekvens av en eller flera episoder. Avsnittsindexet är användbart för att notera när visualiseraren uppmanas att visa data från olika avsnitt.
  • iteration: Sekvensindexet för iterationsdata i ett avsnitt. Observera att simulatorn ska vara tillståndslös och att iterationer kan komma i valfri ordning eftersom data följer användarinteraktioner.

Anteckning

Konfigurations-, tillstånds- och åtgärdsvariabler matchar alltid variablerna från Inkling-filen som används under träningen.

Nästa steg

Prova att experimentera med mer avancerade visualiseringsexempel för Cartpole eller Moab.