# embodied-city-python-sdk
A Simple Python SDK to interact with the Embodied City API.
Users can easily achieve perception and control of drone agents through the following functions.
When the command is issued via the API, changes in the agent's first-person view will be observed in the Console.
## Installation
```bash
pip install embodiedcity
```
## Usage
#### Acquire ID and token
Before you can use the SDK, you need to acquire a drone and obtain its token.
You can get one by signing up at [Embodied City](https://embodied-city.fiblab.net/).
In the website, you should go to the "Console" page, choose an available drone, and click on the "Acquire" button.
After that, you will see a token with the drone ID.
> ATTENTION: The token is a secret key that should not be shared with anyone.
> ATTENTION: The token will expire after a certain period of time if you do not use it. (the time constrain will be notified in the website)
#### Initialize the client
```python
from embodiedcity import DroneClient, ImageType, CameraID
base_url = "https://embodied-city.fiblab.net"
drone_id = "xxx"
token = "xxxxxxxx"
client = DroneClient(base_url, drone_id, token)
```
#### Move the drone
```python
# Move the drone forward by 10 meter (Short movement distance may result in action failure)
client.move_back_forth(10)
```
#### Obtain the RGB image of the front camera
```python
# Get a RGB image from the front-center camera
image = client.get_image(ImageType.Scene, CameraID.FrontCenter)
```
#### Get the depth image
```python
# Get an image of the depth from the front-center camera
image = client.get_image(ImageType.DepthPlanar, CameraID.FrontCenter)
```
## Release the drone
After you finish using the drone, you should release it to make it available for others.
You can do this by clicking on the "Release" button in the "Console" page.
## FAQ
#### After invoking the control action, the drone did not move.
It is possible that the drone collided with a building.
Try issuing a command to move the drone in a direction without obstacles.
Alternatively, use the function DroneClient.move_to_position to force it to a specified location.
#### What should I do if I need the drone to perform more complex operations?
Please download and install the full embodiedcity simulator.
## HTTP Protocol
POST /api/call-function
Body:
```json
{
"droneId": "drone ID",
"action": "action string",
"args": [arg1, arg2, ...],
"token": "(optional) token for authorization"
}
```
Status code is 200 if the action is successful.
Action string, arg, return value:
| Action | Args | Description | Return | Description |
| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------ |
| `move_back_forth` | [`distance`: float] | Move the drone back (<0) and forth (>0) by a certain distance (unit: meters) | `None` | - |
| `move_horizontal` | [`distance`: float] | Move the drone left (>0) and right (<0) by a certain distance (unit: meters) | `None` | - |
| `move_vertical` | [`distance`: float] | Move the drone up (>0) and down (<0) by a certain distance (unit: meters) | `None` | - |
| `move_by_yaw` | [`yaw`: float] | Rotate the drone by a certain angle. Positive values mean rotating counterclockwise, negative values mean rotating clockwise. (unit: radians) | `None` | - |
| `get_image` | [`image_type`: int, `camera_id`: str] | Get an image from the specified camera. `image_type` can be 0 (Scene), 1 (DepthPlanar), 2 (Segmentation). `camera_id` can be 0 (FrontCenter), 1 (FrontRight), 2 (FrontLeft), 3 (BottomCenter), 4 (BackCenter) | `image`: bytes | The image data in bytes (MIME: image/jpeg) |
| `get_current_state` | [] | Get the current state of the drone | `[[x, y, z], [pitch, roll, yaw]]` | The current state of the drone |
| `move_to_position` | [`x`: float, `y`: float, `z`: float] | Move the drone to the specified position | `None` | - |
| `set_vehicle_pose` | [`x`: float, `y`: float, `z`: float, `pitch`: float, `roll`: float, `yaw`: float] | Set the pose of the drone | `None` | - |
Raw data
{
"_id": null,
"home_page": "https://embodied-city.fiblab.net",
"name": "embodiedcity",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "city, embodied",
"author": "Jun Zhang",
"author_email": "zhangjun990222@qq.com",
"download_url": "https://files.pythonhosted.org/packages/1f/55/6d2306c3a567f50bccf91f5ec3b3836ed6c00de14abdabbe9ae3ac545fe1/embodiedcity-0.3.0.tar.gz",
"platform": null,
"description": "# embodied-city-python-sdk\n\nA Simple Python SDK to interact with the Embodied City API.\nUsers can easily achieve perception and control of drone agents through the following functions.\nWhen the command is issued via the API, changes in the agent's first-person view will be observed in the Console.\n\n## Installation\n\n```bash\npip install embodiedcity\n```\n\n## Usage\n\n#### Acquire ID and token\n\nBefore you can use the SDK, you need to acquire a drone and obtain its token.\nYou can get one by signing up at [Embodied City](https://embodied-city.fiblab.net/).\n\nIn the website, you should go to the \"Console\" page, choose an available drone, and click on the \"Acquire\" button.\nAfter that, you will see a token with the drone ID.\n\n> ATTENTION: The token is a secret key that should not be shared with anyone.\n\n> ATTENTION: The token will expire after a certain period of time if you do not use it. (the time constrain will be notified in the website)\n\n#### Initialize the client\n\n```python\nfrom embodiedcity import DroneClient, ImageType, CameraID\n\nbase_url = \"https://embodied-city.fiblab.net\"\ndrone_id = \"xxx\"\ntoken = \"xxxxxxxx\"\nclient = DroneClient(base_url, drone_id, token)\n```\n\n#### Move the drone\n\n```python\n# Move the drone forward by 10 meter (Short movement distance may result in action failure)\nclient.move_back_forth(10)\n```\n\n#### Obtain the RGB image of the front camera\n \n```python\n# Get a RGB image from the front-center camera\nimage = client.get_image(ImageType.Scene, CameraID.FrontCenter)\n```\n\n#### Get the depth image\n \n```python\n# Get an image of the depth from the front-center camera\nimage = client.get_image(ImageType.DepthPlanar, CameraID.FrontCenter)\n```\n\n## Release the drone\n\nAfter you finish using the drone, you should release it to make it available for others.\n\nYou can do this by clicking on the \"Release\" button in the \"Console\" page.\n\n\n## FAQ\n\n#### After invoking the control action, the drone did not move.\n\nIt is possible that the drone collided with a building.\nTry issuing a command to move the drone in a direction without obstacles.\nAlternatively, use the function DroneClient.move_to_position to force it to a specified location.\n\n#### What should I do if I need the drone to perform more complex operations?\n\nPlease download and install the full embodiedcity simulator.\n\n## HTTP Protocol\n\nPOST /api/call-function\n\nBody:\n```json\n{\n \"droneId\": \"drone ID\",\n \"action\": \"action string\",\n \"args\": [arg1, arg2, ...],\n \"token\": \"(optional) token for authorization\"\n}\n```\n\nStatus code is 200 if the action is successful.\n\nAction string, arg, return value:\n\n| Action | Args | Description | Return | Description |\n| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------ |\n| `move_back_forth` | [`distance`: float] | Move the drone back (<0) and forth (>0) by a certain distance (unit: meters) | `None` | - |\n| `move_horizontal` | [`distance`: float] | Move the drone left (>0) and right (<0) by a certain distance (unit: meters) | `None` | - |\n| `move_vertical` | [`distance`: float] | Move the drone up (>0) and down (<0) by a certain distance (unit: meters) | `None` | - |\n| `move_by_yaw` | [`yaw`: float] | Rotate the drone by a certain angle. Positive values mean rotating counterclockwise, negative values mean rotating clockwise. (unit: radians) | `None` | - |\n| `get_image` | [`image_type`: int, `camera_id`: str] | Get an image from the specified camera. `image_type` can be 0 (Scene), 1 (DepthPlanar), 2 (Segmentation). `camera_id` can be 0 (FrontCenter), 1 (FrontRight), 2 (FrontLeft), 3 (BottomCenter), 4 (BackCenter) | `image`: bytes | The image data in bytes (MIME: image/jpeg) |\n| `get_current_state` | [] | Get the current state of the drone | `[[x, y, z], [pitch, roll, yaw]]` | The current state of the drone |\n| `move_to_position` | [`x`: float, `y`: float, `z`: float] | Move the drone to the specified position | `None` | - |\n| `set_vehicle_pose` | [`x`: float, `y`: float, `z`: float, `pitch`: float, `roll`: float, `yaw`: float] | Set the pose of the drone | `None` | - |\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Embodied City Python SDK",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://embodied-city.fiblab.net/docs",
"Homepage": "https://embodied-city.fiblab.net"
},
"split_keywords": [
"city",
" embodied"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cac8a07e8e9d842904cdab826dedcefcb33abeed9c561045b7bc6c0387fd80ec",
"md5": "99555b8a667f4818e1cdfe9ff48860dc",
"sha256": "83dee5c1bec2916495305b27ee2ba425c859ca02c54e76261d19e29786d040e6"
},
"downloads": -1,
"filename": "embodiedcity-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "99555b8a667f4818e1cdfe9ff48860dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 8509,
"upload_time": "2024-09-23T13:56:09",
"upload_time_iso_8601": "2024-09-23T13:56:09.451219Z",
"url": "https://files.pythonhosted.org/packages/ca/c8/a07e8e9d842904cdab826dedcefcb33abeed9c561045b7bc6c0387fd80ec/embodiedcity-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1f556d2306c3a567f50bccf91f5ec3b3836ed6c00de14abdabbe9ae3ac545fe1",
"md5": "1406107ab0d8547efa42d2a4f7aaed14",
"sha256": "f8db0c76054fba59f079085003ea2e6a4ec8c6d202fca1871c16036a62f1f0e4"
},
"downloads": -1,
"filename": "embodiedcity-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "1406107ab0d8547efa42d2a4f7aaed14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 6757,
"upload_time": "2024-09-23T13:56:10",
"upload_time_iso_8601": "2024-09-23T13:56:10.868228Z",
"url": "https://files.pythonhosted.org/packages/1f/55/6d2306c3a567f50bccf91f5ec3b3836ed6c00de14abdabbe9ae3ac545fe1/embodiedcity-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 13:56:10",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "embodiedcity"
}
JSON