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
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-pip 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]
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
whereX
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
- 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).


