Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dfki-ni/syclops

Syclops is a tool for creating synthetic data from 3D virtual environments with photorealistic renderings and pixel-perfect annotations.
https://github.com/dfki-ni/syclops

3d-rendering annotation asset-management bounding-boxes computer-vision data-generation dataset-creation depth-estimation instance-segmentation keypoints machine-learning photorealistic point-clouds randomization semantic-segmentation structured-light synthetic-data virtual-environments

Last synced: 12 days ago
JSON representation

Syclops is a tool for creating synthetic data from 3D virtual environments with photorealistic renderings and pixel-perfect annotations.

Awesome Lists containing this project

README 

          
# Syclops

![Documentation](https://github.com/dfki-ni/syclops/actions/workflows/docs_deployment.yaml/badge.svg)

[![DOI](https://joss.theoj.org/papers/10.21105/joss.07854/status.svg)](https://doi.org/10.21105/joss.07854)





  cgapp logo


  Syclops



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




  

    Documentation

  




---



# 🎯 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





  output-render





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 syclops_venv

source syclops_venv/bin/activate



# For Windows

virtualenv syclops_venv

.\syclops_venv\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\_\_](https://github.com/DFKI-NI/syclops/blob/main/syclops/__example_assets__/example_job.syclops.yaml) 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/` 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](https://github.com/tik0)), Henning Wübben ([@hwuebben](https://github.com/hwuebben)), Florian Rahe ([@frahe-ama](https://github.com/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. 





  AgriGaia

  AgriGaia

  AgriGaia




# 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}

 }

```