- Installation
- Usage
a. Rendering a robot
b. Collisions and out of bounds
c. Navigating the viewing window
d. Building a robot - Testing
- Appendix
a. File Formats
- Python 3.10.2 or higher
- Pip
- RoboViz source code
To install the required Python packages, from the root project directory run:
pip install -r requirements.txt
RoboViz can be run in both command line (CLI) mode and graphical (GUI) mode. To load a Robot in the Environment, 3 files are required:
- Configuration file (.txt) - contains the environment and robot swarm size
- Positions file (.txt) - contains the <x, y, z> positions for each robot
- Robot file (.json) - contains specs for one or many robots
Formats for these files are provided in the Appendix.
To use the CLI, simply run the script by providing the relevant file paths args:
python robotHandler.py <config_path> <positions_path> <robot_json_path>
The Environment will then be loaded and the Robots rendered, before the viewing window appears. Note: Collision and out of bounds detection is not supported for the CLI
python robotHandler.py ./config/config.txt ./positions/pos.txt ./json/robot.json
To use the GUI, simply run the script without any args:
python robotHandler.py
Then:
- Select the 3 required files by clicking the 'Browse' buttons
- Click on the 'Submit' button
The Environment will then be loaded and the Robots rendered, before the viewing window appears.
Note: the last used file paths will be saved and loaded the next time the program opens. These are stored in the file LastRender.txt.
If you do not want to specify the positions for each Robot in the scene (e.g. if you have a great many Robots in your swarm), you can enable the auto-pack option from the bottom left of the main GUI window (This means you will not have to specify a positions file).
This will attempt to fit all of the Robots into the environment of dimensions specified in the configuration file.
If it cannot fit all the Robots into the specified environment, it will attempt to incrementally enlarge the environment until it can (this increment can be changed by editing the INCT_AMT constant in the robotUtils.py file). The buffer or spacing between these packed Robots can also be changed by editing the BUFFER constant in the robotUtils.py file.
Any combination of configuration and robot files can be used as long as auto-pack is enabled (provided that, for a hetergeneous robot file, the swarm size in config matches the number of hetergeneous robots).
RoboViz has a system for detecting possible collisions between Robots and any Robots that are out of the bounds of the Environment. If collisions or bound violations are detected, a window will appear after clicking the 'Submit' button. This will list possible collisions between Robots in the scene and any Robots that are out of bounds and the units by which they are.
Note: Collisions are reported as possible as the collision detection system simply uses the rectangular bounding boxes of the Robots and not their actual shapes. There may not be a collision after all as the actual components of 2 'colliding' Robots may not actually collide while there bounding boxes do. This method was chosen as it hardly introduces any overhead with regards to load times and was deemed all right for the application.
The camera is automatically centered on the first Robot to be loaded
- Orbit: Hold 'middle mouse button' and drag
- Shift: Hold 'left mouse button' and drag
- Zooming: Hold 'right mouse button' and drag back and forth
- Switching Focus: 'C' - cycle the camera's focus between Robots
- Clicking on a Robot will select it and toggle its selection outline box
- Clicking on a Component will enlarge its label for easier viewing (The selected Robot and Component are also shown in the menu near the top right)
With a Robot selected:
- Movement left/right: 'left/right arrows'
- Movement forward/back: 'up/down arrows'
- Movement up/down: 'ctrl + up/down arrows'
- Rotation: 'ctrl + left/right arrows'
- Toggle Component Labels: 'L'
- Hide Help Menu: 'H'
Note: The Robot Builder currently only supports the building and loading of single Robots.
You can create your own Robots using the file formats specified in the Appendix. Alternatively, you can use the Robot builder, accessed by clicking on the 'Build' button on the initial GUI window.
A CoreComponent will be pre-loaded into the Robot tree. To add additional components:
- select a 'parent' component by clicking on it (at first this will only be the CoreComponent)
- select a component type from the dropdown
- give it a name in the text box
- click on the '+' button in the top left
A new dialog will then appear, requiring you to select a source slot, destination slot, and orientation for the component. Clicking on 'Submit' will then add the component to the tree.
To render the Robot, simply click on the 'Submit' button and the viewing window will appear. If you would like to save your custom Robot to a JSON file, make sure the 'Write to file' box is checked to the right of the lower buttons (and name your custom Robot file using the text box to the right of that).
You can also load and edit a pre-existing Robot from a file by clicking on the 'Load' button and selecting a Robot JSON file.
RoboGen's system for orientation and slot naming is slightly confusing at first, so here's how it works:
- slot numbers for components are labelled as follows:
- 0 - front (side closest to viewer)
- 1 - back (side furthest from viewer)
- 2 - right (side to right of viewer)
- 3 - left (side to left of viewer)
BRICK HINGE
1 1 Note that hinges only have
3 |B| 2 |H| slots 0 and 1 available
0 0
viewer viewer
- orientation refers to the roll of a component and is based on the orientation of the component it is connected to (its 'parent' component). Orientation is visually applied to hinges, but not to bricks.
The 'brain' of the Robot will be constructed into an ANN if the CREATE_BRAIN constant in robotUtils.py is set to True. While this does construct an ANN, it currently serves no purpose and is meant only for future development. Furthermore, the methods step in robot.py, stepNetwork in environment.py, calcAccelaration in robotComp.py and other class attributes are unused and merely written for future extension.
Note: the brain can only be constructed for a homogeneous swarm
Tests were created with unittest and pytest in 2 different suites. First there is the activation suite (test_activation.py) for testing the initialisation of classes and the second is the method suite (test_method.py) for testing class methods.
To run the activation tests, use python test_activation.py from the root directory.
To run the method tests, use pytest -q test_method.py from the root directory to run the automatic tests and python test_method.py to run the manual, visual tests.
Listed below are all included example files that can be used in combination:
- config/config.txt, positions/pos.txt, json/robot.json - simple 1 robot scene
- config/config4.txt, positions/pos4.txt, json/multipleRobots.json - 4 hetergeneous robots with out of bounds & collision errors
- config/config100.txt, -, json/robot.json (with auto-pack enabled) - 100 homogeneous robots
As stated before, any combination of configuration and robot files can be used as long as auto-pack is enabled (provided that, for a hetergeneous robot file, the swarm size in config matches the number of hetergeneous robots).
The configuration file contains the x and y dimensions of the environment plane and the robot swarm size. It should be a text (.txt) file.
The format should be as follows:
x_length
y_length
swarm_size
1000
1500
10
The positions file contains the <x, y, z> positions of each Robot in the swarm. It should be a text (.txt) file.
The format should be as follows:
x y z # robot 1
x y z # robot 2
x y z # etc.
0 0 0
100 0 0
-200 800 50
The robot file contains the specifications for one or many Robots. It should be a JSON (.json) file.
The format should be as follows: Single Robot (Homogeneous)
{
"id": 0,
"body": {
"part": [
{
"id": "Core",
"type": "CoreComponent",
"root": true,
"orientation": 0
},
{
"id": "Hip1",
"type": "ActiveHinge",
"root": false,
"orientation": 1
},
],
"connection": [
{
"src": "Core",
"dest": "Hip1",
"srcSlot": 0,
"destSlot": 0
},
]
},
"brain": {
"neuron": [
{
"id": "Core-0",
"layer": "input",
"type": "simple",
"bodyPartId": "Core",
"ioId": 0,
"gain": 1.0
},
],
"connection": [
{
"src": "Core-0",
"dest": "Hip1-0",
"weight": -1.7611217498779297
},
]
}
}
Multiple Robots (Heterogeneous)
{
"swarm": [
{
"id": 1,
"body": {
"part": [
{
"id": "Core",
"type": "CoreComponent",
"root": true,
"orientation": 0
},
{
"id": "Hip1",
"type": "ActiveHinge",
"root": false,
"orientation": 1
},
],
"connection": [
etc...
...
...
]
}
}
]
}
Note: The "brain" section can be left out if CREATE_BRAIN is set to False in robotHandler.py.
Two full example JSON files are given in the source code (homogeneous + heterogeneous)
For this project, Panda3D version 1.10.11 was used. This is not currently the latest version but it is recommended for two reasons:
- To keep current Panda3D code from breaking with potential new additions
- To keep the BAM model files for each component compatible
- Panda can use 2 types of model files, .egg or .bam files. BAM files are optimised versions of EGG files and are faster to load. However, they are often version-specific.
- To update Panda3D one would have to use YABEE to export the Blender models to EGG files and then use egg2bam to convert those EGG files into BAM files if desired.