syclops 1.4.4

Syclops is a Python library for generating synthetic data for machine learning.

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:

pip install virtualenv

To create and activate a new virtual environment named syclops:

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

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

Installing Syclops

Once you have your environment set up and activated:

pip install syclops

Alternatively: Clone and Install from Source

To install Syclops directly from the source code:

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.

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:

syclops --example-job

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

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.

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.