qhsim 0.1.0__tar.gz

qhsim-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: qhsim
+Version: 0.1.0
+Summary: Mock-backend Python SDK for simulation-carema.
+Author: Qunhe
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# qhsim SDK
+
+Mock-backend Python SDK for the simulation-carema v1 API.
+
+## Install
+
+```bash
+python -m pip install -e sdk
+```
+
+## 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")
+
+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),
+)
+
+render_data = world.render()
+print(render_data.image_urls)
+print(world.result[render_data.task_id])
+print(camera.get_history_pose())
+print(world.scene.get_object(object_name=camera.name))
+
+simulation_app.close()
+```
+
+The default backend is in-process and deterministic. To swap it out, pass a backend object with `load_scene()` and `render()` methods:
+
+```python
+simulation_app = SimulationApp(config={"backend": custom_backend})
+```

qhsim-0.1.0/README.md

@@ -0,0 +1,52 @@
+# qhsim SDK
+
+Mock-backend Python SDK for the simulation-carema v1 API.
+
+## Install
+
+```bash
+python -m pip install -e sdk
+```
+
+## 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")
+
+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),
+)
+
+render_data = world.render()
+print(render_data.image_urls)
+print(world.result[render_data.task_id])
+print(camera.get_history_pose())
+print(world.scene.get_object(object_name=camera.name))
+
+simulation_app.close()
+```
+
+The default backend is in-process and deterministic. To swap it out, pass a backend object with `load_scene()` and `render()` methods:
+
+```python
+simulation_app = SimulationApp(config={"backend": custom_backend})
+```

qhsim-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qhsim"
+version = "0.1.0"
+description = "Mock-backend Python SDK for simulation-carema."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Qunhe" }]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["qhsim*"]

qhsim-0.1.0/qhsim/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .backends.mock import MockBackend
+
+
+class SimulationApp:
+    """SDK runtime entrypoint."""
+
+    def __init__(self, user_id: str | None = None, config: dict[str, Any] | None = None) -> None:
+        self.user_id = user_id
+        self.config = dict(config or {})
+        self.backend = self.config.get("backend") or MockBackend()
+        self._running = True
+        self._update_count = 0
+
+    def update(self) -> None:
+        if not self._running:
+            raise RuntimeError("SimulationApp is closed")
+        self._update_count += 1
+
+    def close(self) -> None:
+        self._running = False
+
+    def is_running(self) -> bool:
+        return self._running
+
+
+__all__ = ["SimulationApp"]

qhsim-0.1.0/qhsim/backends/__init__.py

@@ -0,0 +1,3 @@
+from .mock import MockBackend
+
+__all__ = ["MockBackend"]

qhsim-0.1.0/qhsim/backends/mock.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+
+class MockBackend:
+    """Deterministic in-process backend used by the SDK by default."""
+
+    def load_scene(self, design_id: str) -> dict[str, Any]:
+        normalized = design_id.strip()
+        if not normalized:
+            raise ValueError("design_id is empty")
+
+        digest = hashlib.sha1(normalized.encode("utf-8")).hexdigest()[:8]
+        return {
+            "design_id": normalized,
+            "objects": {
+                "camera_target": {
+                    "id": f"{digest}-target",
+                    "name": "camera_target",
+                    "position": {"x": 0.0, "y": 1938.0, "z": 1300.0},
+                    "bbox": {"x": 100.0, "y": 100.0, "z": 100.0},
+                },
+                "robot_base": {
+                    "id": f"{digest}-robot-base",
+                    "name": "robot_base",
+                    "position": {"x": 0.0, "y": 0.0, "z": 0.0},
+                    "bbox": {"x": 1200.0, "y": 1200.0, "z": 1600.0},
+                },
+            },
+        }
+
+    def render(
+        self,
+        design_id: str,
+        camera_history: list[dict[str, Any]],
+        camera_name: str | None,
+    ) -> dict[str, Any]:
+        normalized = design_id.strip()
+        if not normalized:
+            raise ValueError("design_id is empty")
+        if not camera_history:
+            raise ValueError("camera_history is empty")
+
+        raw = f"{normalized}:{camera_name or 'camera'}:{len(camera_history)}"
+        task_id = f"mock-render-{hashlib.sha1(raw.encode('utf-8')).hexdigest()[:12]}"
+        return {
+            "task_id": task_id,
+            "status": "completed",
+            "image_urls": [
+                f"mock://render/{task_id}/image-{index + 1}.png"
+                for index in range(len(camera_history))
+            ],
+        }

qhsim-0.1.0/qhsim/core/__init__.py

@@ -0,0 +1,14 @@
+from .api import ModelData, Scene, SimulationContext, World
+from .math import BoundingBox, Position, Target
+from .types import RenderData
+
+__all__ = [
+    "BoundingBox",
+    "ModelData",
+    "Position",
+    "RenderData",
+    "Scene",
+    "SimulationContext",
+    "Target",
+    "World",
+]

qhsim-0.1.0/qhsim/core/api.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from qhsim import SimulationApp
+from qhsim.core.math import BoundingBox, Position
+from qhsim.core.types import RenderData
+
+
+@dataclass(frozen=True)
+class ModelData:
+    id: str
+    name: str
+    position: Position
+    bbox: BoundingBox
+
+
+class SimulationContext:
+    def __init__(self, app: SimulationApp | None = None) -> None:
+        self.app = app or SimulationApp()
+
+
+class Scene:
+    def __init__(self, design_id: str, objects: dict[str, object] | None = None) -> None:
+        self.design_id = design_id
+        self.objects: dict[str, object] = dict(objects or {})
+
+    def add(self, obj: object) -> None:
+        name = getattr(obj, "name", None)
+        if not name:
+            raise ValueError("scene object must have a non-empty name")
+        self.objects[str(name)] = obj
+
+    def get_objects(self) -> dict[str, object]:
+        return dict(self.objects)
+
+    def get_object(self, object_id: str | None = None, object_name: str | None = None) -> object:
+        if object_id is None and object_name is None:
+            raise ValueError("object_id or object_name is required")
+
+        if object_name is not None:
+            try:
+                return self.objects[object_name]
+            except KeyError as exc:
+                raise KeyError(f"object not found by name: {object_name}") from exc
+
+        for obj in self.objects.values():
+            if getattr(obj, "id", None) == object_id:
+                return obj
+        raise KeyError(f"object not found by id: {object_id}")
+
+
+class World:
+    def __init__(self, app: SimulationApp | None = None) -> None:
+        self.app = app or SimulationApp()
+        self.scene: Scene | None = None
+        self.result: dict[str, RenderData] = {}
+
+    def load_scene(self, design_id: str) -> Scene:
+        normalized = design_id.strip()
+        if not normalized:
+            raise ValueError("design_id is empty")
+
+        response = self.app.backend.load_scene(normalized)
+        objects = {
+            name: _model_from_payload(payload)
+            for name, payload in dict(response.get("objects", {})).items()
+        }
+        self.scene = Scene(str(response.get("design_id") or normalized), objects)
+        return self.scene
+
+    def render(self, camera: object | None = None) -> RenderData:
+        if self.scene is None:
+            raise RuntimeError("load_scene must be called before render")
+
+        resolved_camera = camera or self._first_camera()
+        if resolved_camera is None:
+            raise RuntimeError("render requires a camera in the scene")
+
+        to_render_history = getattr(resolved_camera, "to_render_history", None)
+        if not callable(to_render_history):
+            raise TypeError("render camera must provide to_render_history()")
+
+        camera_history = to_render_history()
+        if not camera_history:
+            raise ValueError("camera history is empty")
+
+        response = self.app.backend.render(
+            self.scene.design_id,
+            camera_history,
+            getattr(resolved_camera, "name", None),
+        )
+        render_data = RenderData(
+            task_id=str(response["task_id"]),
+            status=str(response.get("status", "unknown")),
+            image_urls=[str(url) for url in response.get("image_urls", [])],
+        )
+        self.result[render_data.task_id] = render_data
+        return render_data
+
+    def _first_camera(self) -> object | None:
+        for obj in self.scene.objects.values() if self.scene else []:
+            if callable(getattr(obj, "to_render_history", None)):
+                return obj
+        return None
+
+
+def _model_from_payload(payload: Any) -> ModelData:
+    data = dict(payload)
+    return ModelData(
+        id=str(data["id"]),
+        name=str(data["name"]),
+        position=Position.from_dict(dict(data["position"])),
+        bbox=BoundingBox.from_dict(dict(data["bbox"])),
+    )

qhsim-0.1.0/qhsim/core/math.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Position:
+    x: float
+    y: float
+    z: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "Position":
+        return cls(float(data["x"]), float(data["y"]), float(data["z"]))
+
+    def to_dict(self) -> dict[str, float]:
+        return {"x": self.x, "y": self.y, "z": self.z}
+
+
+@dataclass(frozen=True)
+class Target:
+    x: float
+    y: float
+    z: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "Target":
+        return cls(float(data["x"]), float(data["y"]), float(data["z"]))
+
+    def to_dict(self) -> dict[str, float]:
+        return {"x": self.x, "y": self.y, "z": self.z}
+
+
+@dataclass(frozen=True)
+class BoundingBox:
+    x: float
+    y: float
+    z: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "BoundingBox":
+        return cls(float(data["x"]), float(data["y"]), float(data["z"]))
+
+    def to_dict(self) -> dict[str, float]:
+        return {"x": self.x, "y": self.y, "z": self.z}

qhsim-0.1.0/qhsim/core/types.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class RenderData:
+    task_id: str
+    status: str
+    image_urls: list[str] = field(default_factory=list)

qhsim-0.1.0/qhsim/sensors/__init__.py

@@ -0,0 +1,3 @@
+from .camera import Camera
+
+__all__ = ["Camera"]

qhsim-0.1.0/qhsim/sensors/camera.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from uuid import uuid4
+
+from qhsim.core.math import Position, Target
+
+
+class Camera:
+    def __init__(
+        self,
+        position: Position,
+        target: Target,
+        name: str = "camera",
+        resolution: tuple[int, int] | None = None,
+        fov: float = 80.0,
+        clarity: int = 1,
+    ) -> None:
+        self.id = f"camera-{uuid4().hex}"
+        self.name = name
+        self.position = position
+        self.target = target
+        self.resolution = resolution
+        self.fov = float(fov)
+        self.clarity = int(clarity)
+        self.history_pose: list[tuple[Position, Target]] = []
+        self._record_pose()
+
+    def set_world_pose(self, position: Position, target: Target) -> None:
+        self.position = position
+        self.target = target
+        self._record_pose()
+
+    def get_world_pose(self) -> tuple[Position, Target]:
+        return self.position, self.target
+
+    def get_history_pose(self) -> list[tuple[Position, Target]]:
+        return list(self.history_pose)
+
+    def to_render_history(self) -> list[dict[str, object]]:
+        return [
+            {
+                "position": position.to_dict(),
+                "target": target.to_dict(),
+                "fov": self.fov,
+                "resolution": self.resolution,
+                "clarity": self.clarity,
+            }
+            for position, target in self.history_pose
+        ]
+
+    def _record_pose(self) -> None:
+        self.history_pose.append((self.position, self.target))

qhsim-0.1.0/qhsim.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: qhsim
+Version: 0.1.0
+Summary: Mock-backend Python SDK for simulation-carema.
+Author: Qunhe
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# qhsim SDK
+
+Mock-backend Python SDK for the simulation-carema v1 API.
+
+## Install
+
+```bash
+python -m pip install -e sdk
+```
+
+## 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")
+
+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),
+)
+
+render_data = world.render()
+print(render_data.image_urls)
+print(world.result[render_data.task_id])
+print(camera.get_history_pose())
+print(world.scene.get_object(object_name=camera.name))
+
+simulation_app.close()
+```
+
+The default backend is in-process and deterministic. To swap it out, pass a backend object with `load_scene()` and `render()` methods:
+
+```python
+simulation_app = SimulationApp(config={"backend": custom_backend})
+```

qhsim-0.1.0/qhsim.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+qhsim/__init__.py
+qhsim.egg-info/PKG-INFO
+qhsim.egg-info/SOURCES.txt
+qhsim.egg-info/dependency_links.txt
+qhsim.egg-info/top_level.txt
+qhsim/backends/__init__.py
+qhsim/backends/mock.py
+qhsim/core/__init__.py
+qhsim/core/api.py
+qhsim/core/math.py
+qhsim/core/types.py
+qhsim/sensors/__init__.py
+qhsim/sensors/camera.py
+tests/test_qhsim.py

qhsim-0.1.0/qhsim.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qhsim-0.1.0/qhsim.egg-info/top_level.txt

@@ -0,0 +1 @@
+qhsim

qhsim-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qhsim-0.1.0/tests/test_qhsim.py

@@ -0,0 +1,137 @@
+import unittest
+
+from qhsim import SimulationApp
+from qhsim.core.api import ModelData, Scene, World
+from qhsim.core.math import BoundingBox, Position, Target
+from qhsim.core.types import RenderData
+from qhsim.sensors.camera import Camera
+
+
+class CustomBackend:
+    def __init__(self):
+        self.loaded_design_id = None
+        self.render_payload = None
+
+    def load_scene(self, design_id):
+        self.loaded_design_id = design_id
+        return {
+            "design_id": design_id,
+            "objects": {
+                "mock_object": {
+                    "id": "object-1",
+                    "name": "mock_object",
+                    "position": {"x": 1, "y": 2, "z": 3},
+                    "bbox": {"x": 4, "y": 5, "z": 6},
+                }
+            },
+        }
+
+    def render(self, design_id, camera_history, camera_name):
+        self.render_payload = {
+            "design_id": design_id,
+            "camera_history": camera_history,
+            "camera_name": camera_name,
+        }
+        return {
+            "task_id": "task-custom",
+            "status": "completed",
+            "image_urls": ["mock://custom/image-1.png"],
+        }
+
+
+class QhSimTest(unittest.TestCase):
+    def test_documented_imports(self):
+        self.assertIs(SimulationApp, SimulationApp)
+        self.assertIs(World, World)
+        self.assertIs(Scene, Scene)
+        self.assertIs(ModelData, ModelData)
+        self.assertIs(Position, Position)
+        self.assertIs(Target, Target)
+        self.assertIs(BoundingBox, BoundingBox)
+        self.assertIs(RenderData, RenderData)
+        self.assertIs(Camera, Camera)
+
+    def test_simulation_app_lifecycle(self):
+        app = SimulationApp(user_id="user-1")
+        self.assertTrue(app.is_running())
+        app.update()
+        app.close()
+        self.assertFalse(app.is_running())
+        with self.assertRaisesRegex(RuntimeError, "closed"):
+            app.update()
+
+    def test_load_scene_fills_objects(self):
+        backend = CustomBackend()
+        app = SimulationApp(config={"backend": backend})
+        world = World(app)
+
+        scene = world.load_scene("design-1")
+
+        self.assertEqual(backend.loaded_design_id, "design-1")
+        self.assertEqual(scene.design_id, "design-1")
+        obj = scene.get_object(object_name="mock_object")
+        self.assertIsInstance(obj, ModelData)
+        self.assertEqual(obj.id, "object-1")
+
+    def test_scene_get_object_by_id_and_name(self):
+        scene = Scene(
+            "design-1",
+            {
+                "box": ModelData(
+                    id="box-id",
+                    name="box",
+                    position=Position(1, 2, 3),
+                    bbox=BoundingBox(4, 5, 6),
+                )
+            },
+        )
+
+        self.assertEqual(scene.get_object(object_name="box").id, "box-id")
+        self.assertEqual(scene.get_object(object_id="box-id").name, "box")
+        with self.assertRaisesRegex(ValueError, "object_id or object_name"):
+            scene.get_object()
+
+    def test_camera_pose_history(self):
+        camera = Camera(Position(0, 0, 1), Target(0, 0, 0), name="camera")
+        camera.set_world_pose(Position(1, 2, 3), Target(4, 5, 6))
+
+        position, target = camera.get_world_pose()
+        self.assertEqual(position, Position(1, 2, 3))
+        self.assertEqual(target, Target(4, 5, 6))
+        self.assertEqual(len(camera.get_history_pose()), 2)
+
+    def test_render_uses_backend_and_stores_result(self):
+        backend = CustomBackend()
+        app = SimulationApp(config={"backend": backend})
+        world = World(app)
+        scene = world.load_scene("design-1")
+        camera = Camera(Position(0, 0, 1), Target(0, 0, 0), name="camera")
+        scene.add(camera)
+
+        render_data = world.render()
+
+        self.assertEqual(backend.render_payload["design_id"], "design-1")
+        self.assertEqual(backend.render_payload["camera_name"], "camera")
+        self.assertEqual(len(backend.render_payload["camera_history"]), 1)
+        self.assertEqual(render_data.task_id, "task-custom")
+        self.assertEqual(render_data.status, "completed")
+        self.assertEqual(render_data.image_urls, ["mock://custom/image-1.png"])
+        self.assertIs(world.result[render_data.task_id], render_data)
+
+    def test_render_requires_loaded_scene(self):
+        with self.assertRaisesRegex(RuntimeError, "load_scene"):
+            World().render(Camera(Position(0, 0, 1), Target(0, 0, 0)))
+
+    def test_render_requires_camera(self):
+        world = World()
+        world.load_scene("design-1")
+        with self.assertRaisesRegex(RuntimeError, "camera"):
+            world.render()
+
+    def test_empty_design_id_fails(self):
+        with self.assertRaisesRegex(ValueError, "design_id is empty"):
+            World().load_scene(" ")
+
+
+if __name__ == "__main__":
+    unittest.main()