m-abdulhak / swarmjs

Interactive 2D swarm robotics simulation platform developed to prototype, benchmark, and showcase control algorithms for multi robot systems.

SwarmJS: Interactive Swarm Robotics Simulation

About

SwarmJS is an interactive 2D simulation platform developed to prototype, benchmark, and showcase control algorithms for multi robot systems.

Our goal with this project is to create a simple and flexible simulation platform that allows users to easily write and share multi-robot control algorithms. SwarmJS is a web application written in JavaScript, and runs completely in the browser. Users can interact with the robots and write control code directly in the browser. SwarmJS is tailored towards mobile robots operating in the plane and engaged in tasks such as aggregation, object clustering, object sorting, planar construction, and pheromone-guided foraging.

Built with:

• Matter.js: Physics engine.
• D3.js: Rendering.
• React: User interface.
• Material UI: UI components.

Getting Started

You can start by watching the video introduction or trying SwarmJS yourself here.

Simulations in SwarmJS are defined as 'scenes'. A scene defines a set of configurations that describe every detail in the simulation. Multiple scenes are provided in SwarmJS to showcase the various capabilities of the simulator, some of which offer the ability to modify the control algorithm directly from the browser while others only enable modifications by cloning the repository and changing the code. Scenes can be selected and run with the scene selector in the quick actions menu.

The latest version of the simulator is available on https://m-abdulhak.github.io/SwarmJS, you can modify, run, and benchmark control algorithms for scenes that support user-defined controllers directly in the browser.

You can also run a local instance with the following steps:

Prerequisites

• Node.js (version 18 or later)
• npm

Installation

git clone https://github.com/m-abdulhak/SwarmJS.git
cd SwarmJS
npm install
npm run dev

The simulator should then be available on: http://localhost:8080/

How to Use

SwarmJS can be used in two ways:

• Directly from the browser:

  In this mode, you can change how the robots behave by modifying the controller code directly in the browser (accessible through the 'Controller' tab). This works in scenes that support user-defined controller code, such as the demo scene provided with SwarmJS. In this mode, you can only change the controller code for the robots, and other simple configurations available through the UI, such as the rendering options in the 'Options' tab. You can follow the basics tutorial to define and run a simple algorithm directly from the browser.

• Define a new scene:

  The full power of SwarmJS can be accessed by creating a new scene, which allows changing every detail of the simulation including, but not limited to: environment size, static obstacles, environment background, environment fields, number and size of robots, shape of robots, custom robot controllers, robot sensors (including ones provided by SwarmJS or custom sensors defined in the scene), robot actuators (including ones provided by SwarmJS or custom actuators defined in the scene), puck groups (including number, size, and color of each group), rendering configuration, benchmarking configuration (including different sets of configuration to benchmark, duration of each benchmark run, and the ability to automatically generate benchmarking graph using performance trackers and graph configuration such as time-step). You can follow the advanced tutorial to create and configure a new scene.

Documentation

The documentation is divided into several sections:

• User Interface
• How to Modify Scenes In the Browser
• How to Create New Scenes
• Configuration Reference
• Rendering Reference
• Code Structure and Main Concepts

swarmjs's Issues

Incorporate variable speed

At the moment the speed bar is non-functional. This should govern the length of the simulation time step.

Add Ability to Drive Physical Robots

Add option to use simulation to drive actual robots by connecting to an external server and receiving live robot positions, and sending updated robot goals back to server.

When this option is active, disable the internal physics engine as robot positions and interactions will be retrieved from the external server.

npm install error

I have problems installing SwarmJS. Running "npm install" returns 5 vulnerabilities:

• npm ERR! code 1
• npm ERR! path C:\Windows\System32\SwarmJS
• npm ERR! command failed
• npm ERR! command C:\WINDOWS\system32\cmd.exe /d /s /c (cd src/client && npm install) && (cd src/common && npm install) && (cd src/scenes && npm install)
• npm ERR! A complete log of this run can be found in: C:\Users\patri\AppData\Local\npm-cache_logs\2023-09-07T11_47_43_880Z-debug-0.log

Unfortuntely "npm audit fix" dosent seem to fix the issue. I am using Node.js version 18.17.1. Can someone help me with this?

Change Speed Controller Into Generic Runtime Robot Parameters

Also fix other styling issues

An additional slider to control the number of updates between renders

There is a button to toggle whether the simulation is rendered, but it would be preferable to put this functionality on a slider that controlled the number of updates in between renders. If the simulation were running faster than real-time (next issue) then the user could use this slider to accelerate through until results of interest were becoming visible.

Optimize simulation speed

I believe that SwarmJS could run significantly faster. It seems much slower than Waggle at present, yet both are using Matter.js for the underlying physics.

Add State Indicators to Quick Action Buttons

Add state indicators to quick action buttons to make it easier to identify when a button is pressed and the current state associated with the button (simulations is paused, benchmarking is active, etc...).

Also change the background change button into a drop down menu.

Incorporate the ability for robots to modify scalar fields

The idea would be to simulate the deposit, sensing, and spread of pheromones. A centralized disembodied agent that could compute a scalar field to guide the swarm would also be interesting to explore.

Allow users to define custom controllers

Add a code editor that allows users to dynamically define and use their own controllers for the specified scene from the UI without the need to modify the code and redeploy.

Add Option to Specify Scene with a Query Parameter

Make it easier to share and link to a specific scene by adding the option to pass a query parameter to specify the scene that should be loaded.

Update Documentation

• Reflect recent changes such as 'Scenes' in the documentations.
• Add tutorials for in-browser controllers and creating a new scene from scratch.

Add Static Configurations

Add ability to define static options that can be changed by the user and take effect after reloading the scene.
These will provide more flexibility as they can support options that do not work dynamically such as changing the environment size or robot size.
Static properties set by the user will remain into effect until the scene is changed or the page is reloaded.
Static properties definitions can be passed along with other scene configurations.
UI elements are automatically created based on the dynamic properties definitions.

Update Position Generators and Re-implement Collision Avoidance Scenes

Add Debugging Options

Make scene globally available so it can be accessed from the developer console.
Possibly, also add a debugging panel where the scene state can be accessed from within the app without the need to access the developer console.

Fix External Engine Scene

Also add details on how to start the scene and connect it to the provided python server to the scene description.

Add Dynamic Configurations

Add ability to define dynamic options that can be changed by the user without reloading the scene (similar to the robot velocity slider).
Dynamic properties definitions can be passed along with other scene configurations.
UI elements are automatically created based on the dynamic properties definitions.

Error when switching to Field Manipulation Demo

This is the error message:

Uncaught TypeError: Cannot read properties of undefined (reading 'width')
at Object.fieldDiffusion [as func] (fieldsDiffusion.js:8:67)
at Scene.update (index.js:253:21)
at _renderScene (index.js:100:15)

Fix Field Selector Default Value

Field selector is not handling defaults correctly, an example is when no field is configured with the 'defaultBackground' option.

Add Options to See and Modify Current Scene And Benchmarking Configurations

• Add a panel to see the current scene configuration from within the app.
• Make the configuration user-modifiable and add option to reload the scene with the new configurations.

Fix Scene Url Not Working on Github Pages