Metadata-Version: 2.4
Name: qhsim
Version: 0.1.1
Summary: Python SDK for simulation-carema.
Author: Qunhe
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# qhsim SDK

Python SDK for the simulation-carema backend API.

## Install

```bash
python -m pip install -e sdk
```

## Local Debug Flow

Run the prodtest HTTP flow from the repository root:

```powershell
python sdk\examples\debug_http_render_flow.py
```

The debug script loads the scene, submits one render task with two camera poses, polls the render result, and prints the task id, status, finished flag, image URLs, and result COS keys.

Defaults:

-   service base URL: `http://localhost:18080`
-   service base prefix: `/qh-sensor-simulation/api/c`
-   `QHSIM_USER_ID`: `3FO4KV8SHSLV`
-   `QHSIM_DESIGN_ID`: `3FO3BK4HCD6O`
-   `QHSIM_SNAPSHOT_TYPE_ID`: `720`
-   `QHSIM_POLL_INTERVAL`: `3`
-   `QHSIM_POLL_ATTEMPTS`: `20`

The service URL is fixed in the SDK. To change it, edit `DEFAULT_BASE_URL` in `qhsim.backends.http`. The service path prefix is fixed by `DEFAULT_SERVICE_BASE_PREFIX`. HTTPS certificate verification is disabled by default for prodtest self-signed certificates; pass `config={"verify_ssl": True, "cafile": "internal-ca.pem"}` to enable verification with a trusted CA.

If you use another example directly without editable install, set `PYTHONPATH` first:

```powershell
$env:PYTHONPATH="D:\fengguo\Agent\repo\simulation-carema\sdk"
python sdk\examples\basic_http_flow.py
```

## Example

```python
from qhsim import SimulationApp
from qhsim.core.api import World
from qhsim.core.math import Position, Target
from qhsim.sensors.camera import Camera

simulation_app = SimulationApp(
    user_id="3FO4KV8SHSLV",
    config={
        "snapshot_type_id": 720,
    },
)

world = World(simulation_app)
world.load_scene(design_id="3FO3BK4HCD6O")

camera = Camera(
    name="camera",
    position=Position(0.0, 0.0, 1600.0),
    target=Target(0.0, 1938.0, 1300.0),
    fov=80.0,
    clarity=1,
)

world.scene.add(camera)

camera.set_world_pose(
    position=Position(1090.0, 0.0, 1600.0),
    target=Target(100.0, 1938.0, 1300.0),
)

submitted = world.render()
print(submitted.task_id)

render_data = world.get_render_result(submitted.task_id)
print(render_data.finished)
print(render_data.image_urls)

final_data = world.poll_render_result(submitted.task_id)
print(final_data.status)
print(final_data.image_urls)

print(camera.get_history_pose())
print(world.scene.get_object(object_name=camera.name))

simulation_app.close()
```

The default backend calls the fixed local service API:

-   `GET /qh-sensor-simulation/api/c/scene/models?designId=...`
-   `POST /qh-sensor-simulation/api/c/camera/render`
-   `GET /qh-sensor-simulation/api/c/camera/render/result?rootTaskId=...`

`user_id` is sent as the required `x-qh-id` header and should already be the encrypted user id expected by the backend. The service URL cannot be overridden by config or environment variables. To change it, edit `DEFAULT_BASE_URL` in `qhsim.backends.http`. HTTPS certificate verification is disabled by default for prodtest self-signed certificates; pass `config={"verify_ssl": True, "cafile": "internal-ca.pem"}` to enable verification with a trusted CA. To swap the transport in tests, pass a backend object with `load_scene()`, `render()`, and `get_render_result()` methods:

```python
simulation_app = SimulationApp(config={"backend": custom_backend})
```

## Public API

Each module defines `__all__`; names not listed there are implementation details.

### `qhsim`

-   `SimulationApp`: SDK runtime entrypoint.
    -   `update()`
    -   `close()`
    -   `is_running()`

### `qhsim.backends`

-   `HttpBackend`: backend implementation for the service API.
    -   `load_scene(design_id)`
    -   `render(design_id, camera_history, camera_name)`
    -   `get_render_result(root_task_id)`
-   `BackendCameraData`
-   `BackendBoundingBoxData`
-   `BackendModelData`
-   `BackendVec3Data`
-   `RenderResultResponse`
-   `RenderSubmitResponse`
-   `RenderTaskRequest`
-   `SceneModelListResponse`
-   `DEFAULT_BASE_URL`
-   `DEFAULT_SERVICE_BASE_PREFIX`
-   `DEFAULT_SNAPSHOT_TYPE_ID`

### `qhsim.core`

-   `ModelData`: scene model metadata.
-   `SimulationContext`: app context holder.
-   `Scene`: loaded design scene.
    -   `add(obj)`
    -   `get_objects()`
    -   `get_object(object_id=None, object_name=None)`
-   `World`: high-level scene and render API.
    -   `load_scene(design_id)`
    -   `render(camera=None)`
    -   `get_render_result(task_id)`
    -   `poll_render_result(task_id, interval=3.0, max_attempts=20000, print_progress=True, require_result=True)`
-   `Position`
    -   `from_dict(data)`
    -   `to_dict()`
-   `Target`
    -   `from_dict(data)`
    -   `to_dict()`
-   `BoundingBox`
    -   `from_dict(data)`
    -   `to_dict()`
-   `RenderData`: render task result with `task_id`, `status`, `finished`, `result`, `image_urls`, `result_cos_key`, and `result_zip_cos_key`.

### `qhsim.sensors`

-   `Camera`: camera sensor used by `World.render()`.
    -   `set_world_pose(position, target)`
    -   `get_world_pose()`
    -   `get_history_pose()`
    -   `to_render_history()`
