feat: integrate public rich ray perception queries

docs/sphinx/source/changelog.md

@@ -15,6 +15,48 @@ PyPI 版本变更与未发布变更；发布日期采用 PyPI 上传日期。完
 
 ## Unreleased / 未发布
 
+### Added / 新增
+
+- The Manager tensor ray observation now consumes UniSim's full-scene public
+  `RayCollisionDescription`, so mesh/hfield materialization no longer requires
+  a backend-specific `uni_ray` builder, and entity-local packed pose reads are
+  aggregated onto the public full-scene body axis. `RayPatternCfg` supports a
+  body-only attachment transform with a local sensor offset, `min_distance`,
+  public geom/tag/body/ancestor filters, a yaw ring with configurable pitch,
+  and optional distance+normal output
+  (`[distance, normal_x, normal_y, normal_z]`, flattened to the observation
+  width). The branch-local `ray-local`
+  dependency profile resolves sibling `unisim-core` and `uni-ray` through
+  relative editable paths in both CUDA and ROCm lockfiles; no PyPI publication
+  is involved
+  ([UniSim #472](https://github.com/unilabsim/unisim/issues/472)).
+  Manager tensor ray observation 现在消费 UniSim 公开 full-scene
+  `RayCollisionDescription`，mesh/hfield materialization 不再要求 backend-specific
+  `uni_ray` builder，并将 entity-local packed pose read 聚合到公开 full-scene body
+  轴。`RayPatternCfg` 支持 body-only attachment 变换与本地 sensor
+  offset、`min_distance`、公开 geom/tag/body/ancestor filter，以及可选
+  distance+normal 输出（`[distance, normal_x, normal_y, normal_z]`）。branch-local
+  `ray-local` 依赖 profile 在 CUDA 与 ROCm lockfile 中均通过相对 editable path
+  解析 sibling `unisim-core` 与 `uni-ray`；不涉及 PyPI 发布
+  （[UniSim #472](https://github.com/unilabsim/unisim/issues/472)）。
+  The first facade is a minimal grouped ray sensor, not a camera: intrinsics,
+  image projection, noise, history, and scheduling remain application logic.
+  Full-scene pose aggregation covers entity-owned bodies plus the identity
+  world root; uncovered non-root bodies fail closed. MuJoCo and MJWarp
+  fixed-variant collision scenes and Motrix source mesh/hfield scenes follow
+  the UniSim fail-closed boundaries. The real end-to-end fixture covers
+  primitive geometry, static filtering, minimum distance, attachment
+  transformation, and normals; mesh/hfield numerical parity is owned by the
+  UniSim and `uni_ray` contract suites.
+  首个 facade 是最小 grouped ray sensor，不是 camera：intrinsics、图像投影、
+  noise、history 与 scheduling 仍属于应用逻辑。full-scene pose 聚合覆盖
+  entity-owned body 与 identity world root；未覆盖的非 root body fail closed。
+  MuJoCo 与 MJWarp fixed-variant collision scene 以及 Motrix source
+  mesh/hfield scene 遵循 UniSim fail-closed 边界。真实端到端 fixture 覆盖
+  primitive geometry、static filtering、minimum distance、attachment
+  transformation 与 normal；mesh/hfield 数值 parity 由 UniSim 与 `uni_ray`
+  contract suite 负责。
+
 ### Changed / 变更
 
 - Genesis runtime domain randomization now follows the unified device-resident

pyproject.rocm.toml

@@ -23,7 +23,7 @@ classifiers = [
 requires-python = ">=3.10,<3.14"
 dependencies = [
     "numpy",
-    "unisim-core==2.1.1",
+    "unisim-core>=2.1.1",
     "prettytable>=3.10",
     "torch==2.14.0",
     "triton-rocm==3.8.0 ; sys_platform == 'linux' and platform_machine == 'x86_64'",
@@ -72,7 +72,13 @@ mujoco = [
     "mujoco~=3.11.0",
     "mjbatch-uni~=0.2.5",
 ]
-motrix = ["unisim-core[motrix]==2.1.1"]
+motrix = ["unisim-core[motrix]>=2.1.1"]
+# Branch-local ROCm integration against sibling ray-contract checkouts. Keep
+# this extra aligned with pyproject.toml; the default runtime still resolves the
+# published unisim-core pin. uni-ray never becomes a runtime dependency.
+# On this issue branch the generated lock intentionally resolves sibling editable
+# checkouts; a standard checkout must provide ../unisim and ../uni_ray.
+ray-local = ["uni-ray[warp]"]
 
 [dependency-groups]
 # The RL stack (APPO/off-policy/multi-GPU) is merged into unilab itself
@@ -91,6 +97,12 @@ torch = [
 triton-rocm = [
     { index = "pytorch-rocm72", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
 ]
+unisim-core = [
+    { path = "../unisim", editable = true, marker = "extra == 'ray-local'" },
+]
+uni-ray = [
+    { path = "../uni_ray", editable = true, marker = "extra == 'ray-local'" },
+]
 
 [tool.uv]
 exclude-dependencies = [

pyproject.toml

@@ -33,7 +33,7 @@ classifiers = [
 requires-python = ">=3.10,<3.14"
 dependencies = [
     "numpy",
-    "unisim-core==2.1.1",
+    "unisim-core>=2.1.1",
     "prettytable>=3.10",
     # A range (not an exact pin) lets ROCm users substitute a ROCm torch
     # build; uv.lock pins the tested CUDA builds via tool.uv.sources.
@@ -106,13 +106,20 @@ newton = [
     "pyglet>=2.1.6,<3",
     "imgui-bundle>=1.92.0",
 ]
-motrix = ["unisim-core[motrix]==2.1.1"]
+motrix = ["unisim-core[motrix]>=2.1.1"]
 genesis = ["genesis-world==1.3.3"]
 # Wheels are CPython 3.12/3.13 Linux x86_64 only; the marker keeps uv lock
 # resolvable for the other required-environments.
 superdex = [
-    "unisim-core[superdex]==2.1.1 ; python_version >= '3.12' and sys_platform == 'linux' and platform_machine == 'x86_64'",
+    "unisim-core[superdex]>=2.1.1 ; python_version >= '3.12' and sys_platform == 'linux' and platform_machine == 'x86_64'",
 ]
+# Branch-local integration against sibling ray-contract checkouts. The exact
+# published UniSim pin remains the default; the local path source overrides it
+# only when this optional extra is selected. uni-ray never becomes a runtime
+# dependency and is imported only by UniSim's public caster factory.
+# On this issue branch the generated lock intentionally resolves sibling editable
+# checkouts; a standard checkout must provide ../unisim and ../uni_ray.
+ray-local = ["uni-ray[warp]"]
 
 [dependency-groups]
 # The RL stack (APPO/off-policy/multi-GPU) is merged into unilab itself
@@ -129,6 +136,12 @@ explicit = true
 torch = [
     { index = "r2-cu130", marker = "sys_platform=='linux' or sys_platform=='win32'" },
 ]
+unisim-core = [
+    { path = "../unisim", editable = true, marker = "extra == 'ray-local'" },
+]
+uni-ray = [
+    { path = "../uni_ray", editable = true, marker = "extra == 'ray-local'" },
+]
 [tool.uv]
 exclude-dependencies = ["torchvision"]
 required-environments = [