Ray intersection in headless procedural simulation

Ray intersection in headless procedural simulation. Parameterized bounded JSON adapter; synthetic DIRECT simulation, no physical robot.

pybullet-raycast-skill | Record version: 1.0.0

Record JSON | Markdown recipe | Complete search index

Fetch and prepare

curl -fsSL https://hub.superfastrobotics.com/skills/pybullet-raycast-skill/skill.json
curl -fsSL https://hub.superfastrobotics.com/skills/pybullet-raycast-skill/README.md
python /PATH_TO_SKILL/scripts/rsh.py inspect pybullet-raycast-skill --json
python /PATH_TO_SKILL/scripts/rsh.py prepare pybullet-raycast-skill --project ./experiment --expected-source-commit 2c204c49e56ed15ec5fcfa71d199ab6d6570b3f5 --expected-record-version 1.0.0 --plan --json

Inspect the requirements, then remove --plan to prepare a project. Preparation verifies the archive SHA256 and preserves exact source pins. --install-deps explicitly installs dependencies. Run the returned simulation command separately.

Environment

Runtime: pybullet 3.2.7
Robot: synthetic-seven-axis-or-procedural-scene
Controller: json-contract-v1
Observation: explicit-json-input
OS / architecture: linux / x86_64
Python: >=3.10,<3.11

Compatibility status: hub_verified

All inputs and outputs follow interface v1. Simulation adapters query exact synthetic simulator state; no perception or physical sensor compatibility.

Requirements

x86_64 CPU; no GPU or robot required

No display. Matplotlib Agg for numerical imports; PyBullet DIRECT for simulation.

Packages: numpy==1.26.4, pybullet==3.2.7

Runtime dependency versions are pinned for the supported Python 3.10 x86_64 CPU environments and checked against execution receipts. Platform-specific wheel hashes are not represented as a universal artifact lock; prepare captures pip freeze.

External API keys: none.

Invocation

Executable interface

{
  "version": "1",
  "kind": "sensing",
  "abstraction_level": 0,
  "execution_domain": "simulation",
  "language": "python",
  "input_transport": "json_file_or_inline",
  "output_transport": "json_stdout",
  "conventions": {
    "linear_unit": "m",
    "angular_unit": "rad",
    "time_unit": "s",
    "coordinate_frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
    "joint_order": "not_used",
    "quaternion_order": "not_used"
  },
  "input_schema": {
    "type": "object",
    "required": [
      "box_center",
      "ray_from",
      "ray_to"
    ],
    "additionalProperties": false,
    "properties": {
      "box_center": {
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number",
          "minimum": -10,
          "maximum": 10
        },
        "x-unit": "m",
        "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
        "x-order": [
          "x",
          "y",
          "z"
        ],
        "description": "box_center; units=m; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin; component order=x,y,z"
      },
      "ray_from": {
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number",
          "minimum": -10,
          "maximum": 10
        },
        "x-unit": "m",
        "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
        "x-order": [
          "x",
          "y",
          "z"
        ],
        "description": "ray_from; units=m; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin; component order=x,y,z"
      },
      "ray_to": {
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number",
          "minimum": -10,
          "maximum": 10
        },
        "x-unit": "m",
        "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
        "x-order": [
          "x",
          "y",
          "z"
        ],
        "description": "ray_to; units=m; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin; component order=x,y,z"
      }
    }
  },
  "output_schema": {
    "type": "object",
    "required": [
      "hit",
      "hit_fraction",
      "hit_xyz_m",
      "normal_xyz"
    ],
    "additionalProperties": false,
    "properties": {
      "hit": {
        "type": "boolean",
        "x-unit": "dimensionless",
        "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
        "description": "hit; units=dimensionless; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin"
      },
      "hit_fraction": {
        "type": "number",
        "minimum": 0,
        "maximum": 1,
        "x-unit": "dimensionless",
        "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
        "description": "hit_fraction; units=dimensionless; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin"
      },
      "hit_xyz_m": {
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number",
          "minimum": -10,
          "maximum": 10
        },
        "x-unit": "m",
        "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
        "x-order": [
          "x",
          "y",
          "z"
        ],
        "description": "hit_xyz_m; units=m; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin; component order=x,y,z"
      },
      "normal_xyz": {
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number",
          "minimum": -1,
          "maximum": 1
        },
        "x-unit": "dimensionless",
        "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
        "x-order": [
          "x",
          "y",
          "z"
        ],
        "description": "normal_xyz; units=dimensionless; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin; component order=x,y,z"
      }
    }
  },
  "preconditions": [
    "PyBullet DIRECT CPU simulation with procedural shapes and a synthetic seven-axis arm where applicable; no downloaded models.",
    "This is an adaptation of the referenced API example, not verification of its original robot model or hardware.",
    "Simulation steps are fixed and bounded; force/torque order is Fx,Fy,Fz,Mx,My,Mz in the joint sensor frame."
  ],
  "postconditions": [
    "All declared checks must pass and all outputs must be finite.",
    "Success applies only to this operation and model, not higher-level task completion."
  ],
  "failure_codes": [
    "invalid_input_or_environment",
    "execution_failed",
    "task_failed"
  ],
  "composition": {
    "depends_on": [],
    "automatic_frame_conversion": false,
    "automatic_hardware_execution": false
  },
  "output_selector": "outputs",
  "origin_reference_ids": [
    "pybullet-batchraycast"
  ],
  "origin_relationship": "adapted_from; inspect declared model and inputs, not original robot compatibility"
}

Entrypoint: python run.py

{
  "argv": [
    "{python}",
    "{recipe_dir}/run.py",
    "--source-dir",
    "{source_dir}",
    "--example"
  ],
  "inputs": {
    "box_center": [
      0,
      0,
      1
    ],
    "ray_from": [
      0,
      0,
      2
    ],
    "ray_to": [
      0,
      0,
      0
    ]
  },
  "outputs": {
    "format": "single JSON object on stdout",
    "payload_selector": "outputs",
    "schema": {
      "type": "object",
      "required": [
        "hit",
        "hit_fraction",
        "hit_xyz_m",
        "normal_xyz"
      ],
      "additionalProperties": false,
      "properties": {
        "hit": {
          "type": "boolean",
          "x-unit": "dimensionless",
          "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
          "description": "hit; units=dimensionless; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin"
        },
        "hit_fraction": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "x-unit": "dimensionless",
          "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
          "description": "hit_fraction; units=dimensionless; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin"
        },
        "hit_xyz_m": {
          "type": "array",
          "minItems": 3,
          "maxItems": 3,
          "items": {
            "type": "number",
            "minimum": -10,
            "maximum": 10
          },
          "x-unit": "m",
          "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
          "x-order": [
            "x",
            "y",
            "z"
          ],
          "description": "hit_xyz_m; units=m; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin; component order=x,y,z"
        },
        "normal_xyz": {
          "type": "array",
          "minItems": 3,
          "maxItems": 3,
          "items": {
            "type": "number",
            "minimum": -1,
            "maximum": 1
          },
          "x-unit": "dimensionless",
          "x-frame": "right_handed_world_xyz; +z_up; procedural_arm_base=world_origin",
          "x-order": [
            "x",
            "y",
            "z"
          ],
          "description": "normal_xyz; units=dimensionless; frame=right_handed_world_xyz; +z_up; procedural_arm_base=world_origin; component order=x,y,z"
        }
      }
    }
  }
}

Success: Exit 0, status=task_complete, success=true, finite outputs satisfying interface.output_schema and all declared numerical/model checks. This is not a physical robot or general task-success claim.

Timeout: 30 seconds. Caller must terminate the separate adapter process after 30 seconds; adapters bound iterations/scene steps and close simulation clients.

Failure modes

Invalid or oversized JSON
Source checksum mismatch
Unavailable pinned dependency
No valid path or postcondition failure
Execution exceeding the declared bounded algorithm budget

Source and license

Repository: https://github.com/bulletphysics/bullet3
Authors: Erwin Coumans and Bullet Physics contributors
Commit: 2c204c49e56ed15ec5fcfa71d199ab6d6570b3f5
Archive SHA256: f7c486f10b9f645d0577249d02855e076e8368babaa3d31ced6095e7162baee9
License: Zlib
Hub commit: 39b06d7a6016edcea27e348e49ffd86f29ec1811

Evidence

Runtime: task_complete / task_complete

Three frozen positive cases passed against this exact adapter; see per-case receipts. This does not estimate general accuracy.

Reviewer: Hub maintainer runtime harness | 2026-10-19

python tools/verify_executable_recipes.py --source-cache SOURCE_CACHE --output OUTPUT --backend pybullet

Submitter reports and hub verification remain separate. Source review does not establish task success.