{"id":19768256,"url":"https://github.com/squareslab/gzscenic","last_synced_at":"2025-04-30T16:34:10.813Z","repository":{"id":48860953,"uuid":"320429110","full_name":"squaresLab/GzScenic","owner":"squaresLab","description":null,"archived":false,"fork":false,"pushed_at":"2021-07-08T08:18:42.000Z","size":3657,"stargazers_count":18,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T03:11:42.199Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/squaresLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-11T00:58:05.000Z","updated_at":"2024-10-03T02:35:11.000Z","dependencies_parsed_at":"2022-09-01T10:41:38.736Z","dependency_job_id":null,"html_url":"https://github.com/squaresLab/GzScenic","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2FGzScenic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2FGzScenic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2FGzScenic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squaresLab%2FGzScenic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/squaresLab","download_url":"https://codeload.github.com/squaresLab/GzScenic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251742822,"owners_count":21636516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T04:36:41.072Z","updated_at":"2025-04-30T16:34:09.346Z","avatar_url":"https://github.com/squaresLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## GzScenic\n\nThis tool allows you to create static worlds for Gazebo using\n[Scenic](https://scenic-lang.readthedocs.io/en/latest/quickstart.html) language.\nAs an input, `gzscenic` expects a description of the models used in the scenarios,\nand a scenario written in Scenic language. GzScenic outputs a plot of the scene\ngenerated from the described scenario and a set of gazebo models\nand a world descriptor that can be used by Gazebo to recreate the scene.\n\n\n### How to install\n\nGzScenic requires Python 3.8 or newer. We encourage using virtual environments.\nUsing [pipenv](https://pipenv-fork.readthedocs.io/en/latest/) you can create such\nenvironment by running:\n```\n$ pipenv shell\n```\nTo install `gzscenic` simply run:\n```\n$ pip install .\n```\n\n### How to run\n\n`gzscenic` accepts three mandatory arguments and many optionals. You can get a full\nlist of the arguments using `gzscenic -h`.\n```\n$ gzscenic \u003cscenario input\u003e \u003cmodel description input\u003e \u003cpath to output directory\u003e\n```\n\nScenario Input\n--------------\n\nThe scenario input file is a `.scenic` file written in the Scenic language, which\ndescribes the scenario you are interested in generating. The models you use in this\nscenario file are described in the `\u003cmodel description input\u003e`, and imported using\n`from gzscenic.model import *`. You can find a simple example of such scenario\nin [example/scenarios](example/scenarios) directory.\n\n\nModel Description Input\n-----------------------\n\nGzScenic needs to build classes for models that are used in scenarios in order to\nbe able to properly interpret them. As a result it expects a YAML file that provides\ninformation about the used models and the initial world environment.\n\nThe YAML file should have the following format:\n```\nworld: \u003cpath to an empty gazebo world file (default: the GzScenic empty world)\u003e\nmodels_dir: \u003cpath to a directory holding custom models (default: same directory as where this input file is stored)\u003e\nmodels:\n  - name: \u003cname of the model\u003e\n    type: \u003ctype of the model: MISSION_ONLY, CUSTOM_MODEL, GAZEBO_MODEL\u003e\n  - name: \u003c..\u003e\n    type: \u003c..\u003e\n```\n\nGzScenic's goal is to arrange the objects in the environment as described by the\nscenario input file. As a result it expects a world description (e.g., `.world` or\n`.sdf` format) that is usually referred to as `empty_world`; a world that is empty of\nobjects but includes the desired settings for light and the ground plane.\n\nThere are three types of models that GzScenic can handle:\n1. GAZEBO\\_MODEL: these are standard Gazebo models listed [here](https://github.com/osrf/gazebo_models). GzScenic automatically determines the size of these models and\ncreates the specified objects. You can optionally specify if you would like the\nobjects of these models to keep their original size or be able to scale up and down\nwhenever possible by setting `dynamic_size` to `True` or `False`.\n2. CUSTOM\\_MODEL: these are models that are either custom made by you, or need to\nbe downloaded from a source other than Gazebo models. In the former case, GzScenic\nwill look for a directory with the same name as this model in the `models_dir`. This\ndirectory should include a `model.sdf` file that describes this custom model, and all\nnecessary mesh files if the exist. In the later case, GzScenic will download the\nmodel from the `url` specified in the YAML file.\n3. MISSION\\_ONLY: these models describe objects that are described in the scenario, but\nshould not be included in the final worl model. For example, using the scenario\nyou can specify waypoints that are of interest to you. However, waypoints cannot\nbe described in the world model. Instead, GzScenic outputs a list of\nthe position and heading information of the objects with no models. Since GzScenic\ncannot automatically learn information about the size of these MISSION\\_ONLY object,\nit expects `length` and `width` of the model to be provided in the YAML file.\n\nThere are a number of optional information you can provide for each model:\n- `z`: since Scenic only operates in 2D, GzScenic sets the `z` coordinate of all\nobjects to zero. However, you can optionaly set that to a different value for each\nmodel.\n- `heading`: by default the heading of object are determined randomly or as specified\nby the scenario. If you want the object to always have a fixed heading you can use\nthis attribute.\n- `dynamic_size`: GzScenic automatically determines whether an objoct can have dynamic\nsize or its size should be fixed. If you want to rewrite that you can explicitely specify.\n\nA full example of this YAML file and accompanying files are provided in [example/input](example/input). Pay attention that paths provided in the YAML file are relative to\nwhere the file is stored.\n\n\nPath to Output Directory\n------------------------\n\nGzScenic outputs a `.world` file that describes the scene generated and ploted,\na set of models in the `models` directory, and a list of positions for objects\nof NO\\_MODEL type `poses.yaml`.\n\n\n### Example\n\nThe [example](example/) directory includes a simple example of creating scenes for\nTurtlebot3. By running the following command you can recreate these scenes:\n```\n$ gzscenic example/scenarios/test.scenic example/input/objects.yml example/out/test\n```\n\nHere is the plot generated by GzScenic for this scenario:\n![gzscenic plot](example/out/test/scenic_plot.png)\n\nHere is how the scene looks like when launched by Gazebo:\n![Gazebo screenshot](example/out/test/gazebo.png)\n\n##### Useful links\n\n- [Scenic documentation](https://scenic-lang.readthedocs.io/en/latest/quickstart.html#)\n- [SDF Format](http://sdformat.org/spec)\n- [Gazebo model format](http://gazebosim.org/tutorials/?tut=build_robot)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquareslab%2Fgzscenic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquareslab%2Fgzscenic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquareslab%2Fgzscenic/lists"}