{"id":20266354,"url":"https://github.com/pwrdc/pytransdec","last_synced_at":"2026-05-01T00:31:38.450Z","repository":{"id":57458044,"uuid":"173379264","full_name":"pwrdc/PyTransdec","owner":"pwrdc","description":"Python library for TransdecEnvironment Unity model","archived":false,"fork":false,"pushed_at":"2020-08-13T20:21:48.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-03T22:09:07.104Z","etag":null,"topics":["ml-agents","python","robosub","simulation","unity3d"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pwrdc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-01T23:02:47.000Z","updated_at":"2019-11-04T11:34:23.000Z","dependencies_parsed_at":"2022-09-07T04:10:09.475Z","dependency_job_id":null,"html_url":"https://github.com/pwrdc/PyTransdec","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/pwrdc%2FPyTransdec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdc%2FPyTransdec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdc%2FPyTransdec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwrdc%2FPyTransdec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pwrdc","download_url":"https://codeload.github.com/pwrdc/PyTransdec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241746795,"owners_count":20013165,"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":["ml-agents","python","robosub","simulation","unity3d"],"created_at":"2024-11-14T12:08:49.302Z","updated_at":"2026-05-01T00:31:38.379Z","avatar_url":"https://github.com/pwrdc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyTransdec\n\n**PyTransdec** is a Python library prepared for controlling [**TransdecEnvironment**](https://github.com/PiotrJZielinski/TransdecEnvironment) by PWr Diving Crew (KN Robocik) at Wrocław University of Science and Technology.\n\nIt wraps [Unity ML-Agents library](https://github.com/Unity-Technologies/ml-agents/tree/master/ml-agents).\n\nThe project is maintained by Pwr Diving Crew software team members (Unity3D section).\n\n[KN Robocik website](http://www.robocik.pwr.edu.pl/)\n\nShould any issues be noticed, please submit a **New issue** on GitHub.\n\n## Installation\n\n### Python\n\nTo use Python API **Python 3.6** is required. On Windows it is recommended to use Anaconda ([64-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86_64.exe) or [32-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86.exe), but you can use your own preferred Python installation.\n\nFor Anaconda use default installation settings. After installation open **Anaconda Navigator** to finish the setup.\n\n![image](https://user-images.githubusercontent.com/23311513/53694120-659c7d80-3daa-11e9-967d-adccde7ca095.png)\n\nIn case environment variables were not created, you will see error `conda is not recognized as internal or external command` when you type `conda` into command line. To solve this problem set the environment variables: open `Edit environment variables for your account`, click `Environment Variables` button, then double click `Path under` under `System variable`. Add the following paths using `New` button:\n\n```\n%UserProfile%\\Anaconda3\\Scripts\n%UserProfile%\\Anaconda3\\Scripts\\conda.exe\n%UserProfile%\\Anaconda3\n%UserProfile%\\Anaconda3\\python.exe\n```\n![image](https://user-images.githubusercontent.com/23311513/53694104-371ea280-3daa-11e9-8351-23eba97e3793.png)\n\nBefore proceeding check your installation by executing `python --version`, which should output something like this:\n\n```\nPython 3.6.x :: ...\n```\n\nYou also need **pip** (which is installed by default in Anaconda). Check if it is correctly installed by executing `pip --version`. The output should look like this:\n\n```\npip x.x...\n```\n\nIf any error occurred, please check your installation.\n\n### PyTransdec package\n\nTo use the package install it using pip (it is recommended to use a **virtual environment** such as [**Pipenv**](https://pipenv.readthedocs.io/en/latest/) (preferred), [**conda env**](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) or [**virtualenv**](https://virtualenv.pypa.io/en/latest/).\n\nInstallation command:\n\n```\npip install git+https://github.com/PiotrJZielinski/PyTransdec\n```\n\nPyTransdec package automatically installs all required dependencies.\n\n## Usage\n\nPyTransdec package contains `TransdecCommunication([file_name, worker_id])` class, which can be used to communicate with TransdecEnvironment. To import the package use following Python script:\n\n```python\nfrom pytransdec import TransdecCommunication\n```\n\nYou can then apply it using `with` statement:\n\n```python\nwith TransdecCommunication() as tc:\n  ...\n```\n\n#### Parameters:\n  * `file_name`: `str`, *optional* - Unity Environment file to operate on; defaults to `None` (connect to Unity Editor)\n  * `worker_id`: `int`, *optional* - for more than 1 parallel workers - port incremental to be used for connection; defaults to `0`\n\n\n### Methods\n|method/property|description|\n|---|---|\n|`tc.reset([message, training])`|Reset the environment with reset `message`; update observations|\n|`tc.step([action])`|Make a step in the environment (specified with `action`); update observations|\n|`tc.reward`|Current reward value|\n|`tc.vector`|Current vector observations dictionary|\n|`tc.visual`|Current visual observations list|\n|`tc.collect_data(positive, add_noise, add_background, n_images[, save_dir, start_num, annotation_margin, used_observations, object_number, show_img, draw_annotations, print_annotations, progress_bar])`|Automatically collect data from Transdec Environment|\n\n|**`tc.reset(self, message={}, training=True)`**|[*[source]*](https://github.com/PiotrJZielinski/PyTransdec/blob/b915c1b25653386024066c6c9f099181498fe5de/pytransdec/communication.py#L65)|\n|---|---|\n\nReset the environment with reset `message` and update observations.\n\n#### Parameters:\n  * `message`: `Dict[str, int]`, *optional* - a dictionary specifying TransdecEnvironment reset settings; defaults to empty `Dict`; available keys:\n    * `'CollectData'`: if `0` - navigation mode; if `1` - data collection mode\n    * `'EnableNoise'`: has effect only when `'CollectData' == 1`; if `0` - no noise added; if `1` - noise objects added on the image\n    * `'Positive'`: has effect only when `'CollectData' == 1`; if `0` - collect negative examples (target object hidden); if `1` - collect positive examples (target object visible)\n    * `FocusedObject` - has effect only when `'CollectData' == 1`; specify which object is focused on collecting data (input: object number from `Data collection settings`)\n    * `EnableBackgroundImage` - has effect only when `'CollectData' == 1`; if `0` - transdec is background; if `1` - random images is background\n    * `ForceToSaveAsNegative` - focus to save image as negative example, even if `Postive` is set to `True`\n    * `'AgentMaxSteps'`: after how many steps is the agent reset; if `0` - never\n  * `training`: `bool`, *optional* - use TransdecEnvironment in training mode (if `True`) or in inference mode (if `False`); defaults to `true`\n      \n|**`tc.step(action=[0.0, 0.0, 0.0, 0.0])`**|[*[source]*](https://github.com/PiotrJZielinski/PyTransdec/blob/b915c1b25653386024066c6c9f099181498fe5de/pytransdec/communication.py#L76)|\n|---|---|\n\nMake a step in the environment (specified with `action`) and update observations.\n\n#### Parameters:\n  * `action`: `Tuple[float, float, float, float]`, *optional* - movement settings for the robot in range `[-1, 1]`; defaults to `[0.0, 0.0, 0.0, 0.0]`; action sequence:\n    * longitudinal movement (`1.0`: max forward, `-1.0`: max backward)\n    * lateral movement (`1.0`: max right, `-1.0`: max left)\n    * vertical movement (`1.0`: max upward, `-1.0`: max downward)\n    * yaw rotation (`1.0`: max right turn, `-1.0`: max left turn)\n    * camera focus (`0`: front camera, `1`: bottom camera)\n\n|**`tc.reward`**|[*[source]*](https://github.com/PiotrJZielinski/PyTransdec/blob/b915c1b25653386024066c6c9f099181498fe5de/pytransdec/communication.py#L87)|\n|---|---|\n\nGet current reward value.\n      \n#### Returns:\n  * `float` representing current reward value calculated inside TransdecEnvironment\n\n|**`tc.vector`**|[*[source]*](https://github.com/PiotrJZielinski/PyTransdec/blob/b915c1b25653386024066c6c9f099181498fe5de/pytransdec/communication.py#L117)|\n|---|---|\n\nGet current vector observations dictionary.\n\n#### Returns:\n  * The dictionary of observations with keys:\n    * `'acceleration_x'` - linear acceleration value in all axes,\n    * `'acceleration_y'`,\n    * `'acceleration_z'`,\n    * `'angular_acceleration_x'` - angular acceleration value in all axes,\n    * `'angular_acceleration_y'`,\n    * `'angular_acceleration_z'`,\n    * `'rotation_x'` - rotation position value in all axes,\n    * `'rotation_y'`,\n    * `'rotation_z'`,\n    * `'depth'` - robot's depth measured from water surface,\n    * `'bounding_box_x'` - bounding box parameters (central point coordinates, width and height),\n    * `'bounding_box_y'`,\n    * `'bounding_box_w'`,\n    * `'bounding_box_h'`,\n    * `'bounding_box_p'` - probability of containing target (`1` or `0`),\n    * `'relative_x'` - robot's position relative to target in all axes,\n    * `'relative_y'`,\n    * `'relative_z'`,\n    * `'relative_yaw'` - robot's orientation relative to target in vertical axis\n\n|**`tc.visual`**|[*[source]*](https://github.com/PiotrJZielinski/PyTransdec/blob/b915c1b25653386024066c6c9f099181498fe5de/pytransdec/communication.py#L131)|\n|---|---|\n\nGet current visual observations list.\n      \n#### Returns:\n  * `List` of all available visual observations as Numpy arrays in range `[0, 255]`\n\n|**`tc.collect_data(positive, add_noise, n_images, save_dir='collected_data', start_num=1, annotation_margin=5, used_observations=('x', 'y', 'w', 'h', 'p'), show_img=False, draw_annotations=False, print_annotations=False, progress_bar=True)`**|[*[source]*](https://github.com/PiotrJZielinski/PyTransdec/blob/b915c1b25653386024066c6c9f099181498fe5de/pytransdec/communication.py#L146)|\n|---|---|\n\nAutomatically collect data from Transdec Environment, saving images to `save_dir`, together with `annotations.csv` of preset content.\n\n#### Parameters:\n  * `positive`: `bool` - if `True` collect positive examples (target object visible), else collect negative examples (target object hidden)\n  * `add_noise`: `bool` - if `True add noise objects on the image, else do not\n  * `n_images`: `int` - number of images to be saved\n  * `save_dir`: `str`, *optional* - folder to put images and annotations file; defaults to `'collected_data'`\n  * `start_num`: `int`, *optional* - starting number to for image filename; defaults to `1`\n  * `annotation_margin`: `int`, *optional* - value added to all bounding box' dimensions; defaults to `5`\n  * `used_observations`: `Union[str, Tuple[str, ...]]`, *optional* - which of the observations should be saved to `annotations.csv` file; if `all` save all vector observations; defaults to `('x', 'y', 'w', 'h', 'p')`; available keys:\n    * `'a_x'` - linear acceleration value in all axes,\n    * `'a_y'`,\n    * `'a_z'`,\n    * `'eps_x'` - angular acceleration value in all axes,\n    * `'eps_y'`,\n    * `'eps_z'`,\n    * `'phi_x'` - rotation position value in all axes,\n    * `'phi_y'`,\n    * `'phi_z'`,\n    * `'d'` - robot's depth measured from water surface,\n    * `'x'` - bounding box parameters (central point coordinates, width and height),\n    * `'y'`,\n    * `'w'`,\n    * `'h'`,\n    * `'p'` - probability of containing target (`1` or `0`),\n    * `'relative_x'` - robot's position relative to target in all axes,\n    * `'relative_y'`,\n    * `'relative_z'`,\n    * `'relative_yaw'` - robot's orientation relative to target in vertical axis\n  * `show_img`: `bool`, *optional* - show each collected image; defaults to `False`\n  * `draw_annotations`: `bool`, *optional* - draw annotations on each showed image; has effect only when `show_img==True`; defaults to `False`\n  * `print_annotations`: `bool`, *optional* - print each annotation in console; defaults to `False`\n  * `progress_bar`: `bool`, *optional* - show neat progressbar for data collection; defaults to `True`\n\n### Example code for data collection\n\n```python\nwith TransdecCommunication() as tc:\n        # collect 1000 positive examples with noise of object 0\n        tc.collect_data(positive=True, add_noise=True, add_background=False, n_images=1000, save_dir='collected_data/{}/train'.format(0),\n                        used_observations='all', object_number=0, show_img=True, draw_annotations=True)\n        # collect 1000 positive examples with custom backgrount of object 0\n        tc.collect_data(positive=True, add_noise=False, add_background=True, n_images=1000, save_dir='collected_data/{}/train'.format(0),\n                        used_observations='all', object_number=0, show_img=True, draw_annotations=True) \n        # collect 1000 negative examples with noise of object 0\n        tc.collect_data(positive=False, add_noise=True, add_background=False, n_images=1000, save_dir='collected_data/{}/train'.format(0),\n                        used_observations='all', object_number=0, show_img=True, draw_annotations=True)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwrdc%2Fpytransdec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpwrdc%2Fpytransdec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwrdc%2Fpytransdec/lists"}