Skip to main content

HuggingFace community-driven open-source library of simulation environments

Project description



GitHub GitHub release Contributor Covenant

Simulate

Simulate is a library for easily creating and sharing simulation environments for intelligent agents (e.g. reinforcement learning) or synthetic data generation.

Install

Install Simulate (preferentially in a virtual environment) with a simple pip install simulate Note: vtk is not built for Apple Silicon with Python 3.8. Please install with >3.9 in that case.

Install for contribution (from CONTRIBUTING.md)

Create a virtual env and then install the code style/quality tools as well as the code base locally

pip install --upgrade simulate

Before you merge a PR, fix the style (we use isort + black)

make style

Quick tour

Simulate's API is inspired by the great Kubric's API. The user create a Scene and add Assets in it (objects, cameras, lights etc).

Once the scene is created, you can save and share it as a file. This is a gIFT file, aka a JSON file with associated resources.

You can also render the scene or do simulations using one of the backend rendering/simulation engines (at the moment Unity, Blender and Godot).

The saving/sharing format is engine agnostic and using a graphic industry standard.

Let's do a quick exploration together.

import simulate as sm

scene = sm.Scene()

Project Structure

The Python API is located in src/simulate. It allows creation and loading of scenes, and sending commands to the backend.

We provide several backends to render and/or run the scene. The default backend requires no specific installation and is based on pyvista. It allows one to quick render/explored scene but doesn't handle physics simulation. To allow physic simulations, the Unity backend can for instance be used by setting engine="unity" (and soon the Godot and Blender Engines backend as well). A Unity build will be automatically downloaded (if not already) and spawed to run simulations. Alternatively, one can download and use the Unity editor themself, which must then be opened with Unity version 2021.3.2f1.

Loading a scene from the Hub or a local file

Loading a scene from a local file or the Hub is done with Scene.create_from(), saving locally or pushing to the Hub with scene.save() or scene.push_to_hub():

from simulate import Scene

scene = Scene.create_from('tests/test_assets/fixtures/Box.gltf')  # either local (priority) or on the Hub with full path to file
scene = Scene.create_from('simulate-tests/Box/glTF/Box.gltf', is_local=False)  # Set priority to the Hub file

scene.save('local_dir/file.gltf')  # Save to a local file
scene.push_to_hub('simulate-tests/Debug/glTF/Box.gltf')  # Save to the Hub - use a token if necessary

scene.show()



Creating a Scene and adding/managing Objects in the scene

Basic example of creating a scene with a plane and a sphere above it:

import simulate as sm

scene = sm.Scene()
scene += sm.Plane() + sm.Sphere(position=[0, 1, 0], radius=0.2)

>>> scene
>>> Scene(dimensionality=3, engine='PyVistaEngine')
>>> └── plane_01 (Plane - Mesh: 121 points, 100 cells)
>>>     └── sphere_02 (Sphere - Mesh: 842 points, 870 cells)

scene.show()

An object (as well as the Scene) is just a node in a tree provided with optional mesh (under the hood created/stored/edited as a pyvista.PolyData or pyvista.MultiBlock objects) and material and/or light, camera, agents special objects.

The following objects creation helpers are currently provided:

  • Object3D any object with a mesh and/or material
  • Plane
  • Sphere
  • Capsule
  • Cylinder
  • Box
  • Cone
  • Line
  • MultipleLines
  • Tube
  • Polygon
  • Ring
  • Text3D
  • Triangle
  • Rectangle
  • Circle
  • StructuredGrid
  • ... (see the doc)

Many of these objects can be visualized by running the following example:

python examples/basic/objects.py



Objects are organized in a tree structure

Adding/removing objects:

  • Using the addition (+) operator (or alternatively the method .add(object)) will add an object as a child of a previous object.
  • Objects can be removed with the subtraction (-) operator or the .remove(object) command.
  • Several objects can be added at once by adding a list/tuple to the scene.
  • The whole scene can be cleared with .clear().
  • To add a nested object, just add it to the object under which it should be nested, e.g. scene.sphere += sphere_child.

Accessing objects:

  • Objects can be directly accessed as attributes of their parents using their names (given with name attribute at creation or automatically generated from the class name + creation counter).
  • Objects can also be accessed from their names with .get_node(name).
  • The names of the object are enforced to be unique (on save/show).
  • Various tree_* attributes are available on any node to quickly navegate or list part of the tree of nodes.

Here are a couple of examples of manipulations:

# Add two copy of the sphere to the scene as children of the root node (using list will add all objects on the same level)
# Using `.copy()` will create a copy of an object (the copy doesn't have any parent or children)
scene += [scene.plane_01.sphere_02.copy(), scene.plane_01.sphere_02.copy()]

>>> scene
>>> Scene(dimensionality=3, engine='pyvista')
>>> ├── plane_01 (Plane - Mesh: 121 points, 100 cells)
>>> │   └── sphere_02 (Sphere - Mesh: 842 points, 870 cells)
>>> ├── sphere_03 (Sphere - Mesh: 842 points, 870 cells)
>>> └── sphere_04 (Sphere - Mesh: 842 points, 870 cells)

# Remove the last added sphere
>>> scene.remove(scene.sphere_04)
>>> Scene(dimensionality=3, engine='pyvista')
>>> ├── plane_01 (Plane - Mesh: 121 points, 100 cells)
>>> │   └── sphere_02 (Sphere - Mesh: 842 points, 870 cells)
>>> └── sphere_03 (Sphere - Mesh: 842 points, 870 cells)

Editing and moving objects

Objects can be easily translated, rotated, scaled

Here are a couple of examples:

# Let's translate our floor (with the first sphere, it's child)
scene.plane_01.translate_x(1)

# Let's scale the second sphere uniformly
scene.sphere_03.scale(0.1)

# Inspect the current position and scaling values
print(scene.plane_01.position)
>>> array([1., 0., 0.])
print(scene.sphere_03.scaling)
>>> array([0.1, 0.1, 0.1])

# We can also translate from a vector and rotate from a quaternion or along the various axis

Editing objects:

  • mesh of the object can be edited with all the manipulation operator provided by pyvista

Visualization engine

A default visualization engine is provided with the vtk backend of pyvista.

Starting the visualization engine can be done simply with .show().

scene.show()

You can find bridges to other rendering/simulation engines in the integrations directory.

Tips

If you are running on GCP, remember not to install pyvistaqt, and if you did so, uninstall it in your environment, since QT doesn't work well on GCP.

Citation

@misc{simulate,
  author = {Thomas Wolf, Edward Beeching, Carl Cochet, Dylan Ebert, Alicia Machado, Nathan Lambert, Clément Romac},
  title = {Simulate},
  year = {2022},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/huggingface/simulate}}
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

simulate-0.1.2.tar.gz (138.8 kB view details)

Uploaded Source

Built Distribution

simulate-0.1.2-cp310-cp310-macosx_12_0_arm64.whl (543.5 kB view details)

Uploaded CPython 3.10 macOS 12.0+ ARM64

File details

Details for the file simulate-0.1.2.tar.gz.

File metadata

  • Download URL: simulate-0.1.2.tar.gz
  • Upload date:
  • Size: 138.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.4

File hashes

Hashes for simulate-0.1.2.tar.gz
Algorithm Hash digest
SHA256 1f1e01a21d7caef2cbde8b6c242528ca43ee3830b7b08bcbcf285edea56759b5
MD5 3e0aff8c7116b3a7f49f083684eb8147
BLAKE2b-256 8925a26df0edb7c65b88a5b3ec252d7caa34a3399c60cc226ac7ab2702a27a54

See more details on using hashes here.

File details

Details for the file simulate-0.1.2-cp310-cp310-macosx_12_0_arm64.whl.

File metadata

File hashes

Hashes for simulate-0.1.2-cp310-cp310-macosx_12_0_arm64.whl
Algorithm Hash digest
SHA256 7dbf16f4046fe24afd0e3f5f389b60c89ce7b8b03caac22388a1e2562d7e4bbc
MD5 47637a3a455dd237d93d7580e1f6a9cc
BLAKE2b-256 806e6c96ba7c466390c350f50b65b6ec63444c63c6893bed27f5c2681639b1d3

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page