Syclops

Syclops

Syclops is a tool for creating synthetic data from 3D virtual environments.

🎯 Features

📷 Photorealistic renderings of the virtual environment with pixel-perfect annotations

📄 No-Code scene and sensor configuration with a simple YAML syntax

🔧 Extensive randomization tools to increase the diversity of the generated data

💾 Asset management and viewer to easily reuse assets across multiple scenes

📦 Easy to use and extend with a modular architecture

🔍 Annotations

Syclops supports a variety of annotated outputs for different use cases. The following outputs are currently supported:

| Output | Description | | :-----------------------: | :-------------------------------------------------------: | | RGB | Rendered color image | | Semantic Segmentation | Semantic segmentation mask with class ids | | Instance Segmentation | Unique instance id for each object in the scene | | Depth | Distance from the camera to each pixel | | Bounding Boxes | Bounding boxes for each object in the scene | | Object Positions | 3D position of each object in the scene | | Point Cloud | 3D location of each pixel in camera space | | Keypoints | Location of keypoints in camera space | | Object Volume | Volume of each object in the scene | | Structured Light | Projected dot pattern for structured light reconstruction |

⚡️Getting Started

Prerequisites

Before you install Syclops, ensure you have the following prerequisites:

• ✅ Tested Python Versions
  • Python 3.9 – 3.11
• ❌ Not yet compatible with Python 3.12+

We recommend using a virtual environment to avoid potential package conflicts. Below are instructions for setting up with virtualenv and conda.

Installing

Using virtualenv

If you don't have virtualenv installed:

bash pip install virtualenv

To create and activate a new virtual environment named syclops:

```bash

For Linux/macOS

virtualenv syclopsvenv source syclopsvenv/bin/activate

For Windows

virtualenv syclopsvenv .\syclopsvenv\Scripts\activate ```

Using conda

If you use Anaconda or Miniconda, you can create a new environment:

bash conda create --name syclops_venv python=3.9 conda activate syclops_venv

Installing Syclops

Once you have your environment set up and activated:

bash pip install syclops

Alternatively: Clone and Install from Source

To install Syclops directly from the source code:

bash git clone https://github.com/DFKI-NI/syclops.git cd syclops pip install .

Note for macOS Users

⚠️ IMPORTANT: Syclops is not currently supported on macOS. While installation theoretically might be possible, it has not been tested and likely will not work properly. If you attempt to use Syclops on macOS, Blender would be downloaded as a .dmg file for your architecture (arm64 or x64), but full functionality cannot be guaranteed.

We recommend using Linux or Windows for the best experience with Syclops.

Run a job

Next, the assets need to be crawled by the pipeline. This only needs to be done once, or if new assets are added.

bash syclops -c

To run a job, a job file is needed. You can find an example in the syclops/__example_assets__ folder.

To test the installation with the example job file run:

bash syclops --example-job

To run a job, simply pass the path to the job file to the syclops command:

bash syclops -j path/to/job.syclops.yaml

That's all you need to know to render images! 🎉

The rendered data will be in output/<timestamp> inside of your specified syclops directory. To quickly visuzalize the data, you can use the dataset viewer tool.

Adjust the output path accordingly.

bash syclops -da output/2022-09-01_12-00-00

🙏 Acknowledgements

We would like to thank our colleagues Timo Korthals (@tik0), Henning Wübben (@hwuebben), Florian Rahe (@frahe-ama), Thilo Steckel and Stefan Stiene for their valuable feedback during the development of Syclops. Their involvement and the resulting insightful discussions have played a key role in shaping the project and setting its direction.

Syclops was developed in the research project Agri-Gaia. This work was supported by the German Federal Ministry for Economic Affairs and Climate Action within the Agri-Gaia project (grant number: 01MK21004A). The DFKI Niedersachsen (DFKI NI) is sponsored by the Ministry of Science and Culture of Lower Saxony and the VolkswagenStiftung.

Citation

If used in research, please cite Syclops: @article{Elmiger2025, doi = {10.21105/joss.07854}, url = {https://doi.org/10.21105/joss.07854}, year = {2025}, publisher = {The Open Journal}, volume = {10}, number = {110}, pages = {7854}, author = {Anton Elmiger and Kai von Szadkowski and Timo Korthals}, title = {Syclops: A Modular Pipeline for Procedural Generation of Synthetic Data}, journal = {Journal of Open Source Software} }