scenery_builder

The scenery_builder is a tool that generates execution artefacts from the composable representation of the FloorPlan DSL models.

Features

The scenery builder uses rdflib to compose models into a graph. Using queries, it generates a variety of artefacts for the execution of robotic tasks in simulation and the real-world. A non-extensive list includes:

• Generation of occupancy grid maps (e.g., for the ROS navigation stack) which can be parametrized by the height of a robot's sensors.
• Generation of the 3D mesh and Gazebo SDF models and worlds for a floor plan.
• Composing static floor plan models (using the FloorPlan DSL) with other objects (e.g., doors) in the scenery that were modelled in JSON-LD.
• Together with the FloorPlan Gazebo plugins:
  • The Gazebo world generation reflects the initial state of articulated objects (e.g., initial joint angle of a door).
  • Supports the specification of dynamic behaviors (e.g. changes in the joint angle) for articulated objects. Currently supporting (a) distance-based triggers and (b) sampled time-based triggers.
• Task specifications for a disinfecting robot, generated by querying internal wall corners of each space in a floorplan and translating them according to a parameter

Installation

Docker

You can directly pull the Docker images from the repository packages. For example:

docker pull ghcr.io/secorolab/scenery_builder:devel

If you are using a fork, replace secorolab above with your username or the organization where you are pulling this from.

Locally building the docker image

After cloning this repository, at its root run docker build and choose a tag for the image. For example:

 docker build . --tag scenery_builder:latest 

Local installation

Requirements

Note

Blender and bpy requires Python 3.11, to install this specific version:

• On Ubuntu, you will probably need to add the deadsnakes ppa in order to be able to install Python 3.11.
• For MacOS, you can use this brew formula.

Install all the requirements:

sudo apt-get install software-properties-common git blender python3.11 python3.11-venv -y

Installing the scenery_builder python package

First, create a virtual environment and activate it:

python -m venv .venv
source .venv/bin/activate

For Blender to regonize the virtual environment, add it to your PYTHONPATH:

export PYTHONPATH=<Path to .venv directory>/lib/python3.11/site-packages   

From the root directory of the repo, install the python packages by running:

pip install -e .

Optionally, instead of blender, you can install bpy. We have conveniently added them as optional dependencies:

pip install -e .[blender]

Note

bpy has issues when being installed inside Docker. This is only recommended as an alternative for the local installation.

Usage

This module adds floorplan as a command line interface. You can use the generate command as shown below:

floorplan generate -i <path to input folder> COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Where the input folder(s) must contain:

• the composable models generated from the FloorPlan DSL
  • coordinate.json
  • floorplan.json
  • polyhedron.json
  • shape.json
  • skeleton.json
  • spatial_relations.json
• the door object models (optional)
  • object-door.json
  • object-door-states.json
• any object instance models (optional), e.g. object-door-instance-X.json where X is a unique numeric ID.

For more information on the artefacts and parameters that can be used to customize the generation check the documentation or simply call

floorplan generate --help

The command above currently generates the following artefacts:

• 3D mesh in .stl format
• Gazebo models and worlds (.sdf, .config)
• Launch files for ROS1 and/or ROS2 (.launch)
• Occupancy grid map for the ROS map_server (.pgm and .yaml)
• Tasks with a list of waypoints in .yaml
• A 3D polyline representation for the SOPRANO project (.poly)

Docker

To use the scenery_builder via Docker, simply pass the input and output paths with the -v volume argument and run the container. This will run the floorplan generate command with the default values defined in the entrypoint.

docker run -v <local input path>:<container path with models> -v <local output path>:<container path for outputs> <scenery_builder image>:<version>

For example, if you built the Docker image yourself and tagged it scenery_builder:latest, and are using the default paths inside the container for the input and output models, you only need to specify your <local input path> and <local output path>:

docker run -v <local input path>:/usr/src/app/models -v <local output path>:/usr/src/app/output scenery_builder:latest

The command above is equivalent to running the following:

floorplan generate -i <local input path> -o <local output path> mesh tasks gazebo occ-grid polyline door-keyframes

If you want to change the path of the volumes inside the Docker container (i.e., /usr/src/app/models or /usr/src/app/output) or want to customize the commands or arguments, use the following:

docker run -v <local input path>:/new/input/path -v <local output path>:/new/output/path scenery_builder:latest -i /new/input/path -o /new/output/path <optional arguments>

Example

An example model for a building is available here. After transforming the floorplan model into its composable representation, generate the artefacts by passing the folder with the JSON-LD models as inputs:

floorplan generate -i hospital/json-ld -o gen/hospital mesh gazebo occ-grid door-keyframes polyline tasks

That should generate the following files:

gen/hospital
├── 3d-mesh
│   └── hospital.stl
├── doors
│   └── behaviours
│       └── keyframes
│           ├── door-instance-1.json
│           ├── ...
│           └── door-instance-n.json
├── gazebo
│   ├── models
│   │   ├── hospital
│   │   │   ├── model.config
│   │   │   └── model.sdf
│   │   └── door
│   │       ├── model.config
│   │       └── model.sdf
│   └── worlds
│       └── hospital.sdf
├── maps
│   ├── hospital.jpg
│   ├── hospital.pgm
│   └── hospital.yaml
├── polyline
│   └── hospital.poly
├── ros
│   └── launch
│       └── hospital.ros2.launch
└── tasks
    └── disinfection
        ├── hallway_route.yaml
        ├── ...
        └── room_B_route.yaml

Tutorials

Tutorials on how to model objects with movement constraints, and how to place them in floor plan models is available here.

Publications

1. A. Ortega Sainz, S. Parra, S. Schneider, and N. Hochgeschwender, ‘Composable and executable scenarios for simulation-based testing of mobile robots’, Frontiers in Robotics and AI, vol. 11, 2024, doi: 10.3389/frobt.2024.1363281.

   bib

   @ARTICLE{ortega2024frontiers,
   AUTHOR={Ortega, Argentina  and Parra, Samuel  and Schneider, Sven  and Hochgeschwender, Nico },
   TITLE={Composable and executable scenarios for simulation-based testing of mobile robots},
   JOURNAL={Frontiers in Robotics and AI},
   VOLUME={Volume 11 - 2024},
   YEAR={2024},
   URL={https://www.frontiersin.org/journals/robotics-and-ai/articles/10.3389/frobt.2024.1363281},
   DOI={10.3389/frobt.2024.1363281},
   ISSN={2296-9144},
   }

Acknowledgments

This work has been partly supported by the European Union's Horizon 2020 projects SESAME (Grant No. 101017258) and SOPRANO (Grant No. 101120990).