playbooks

home / skills / bdambrosio / cognitive_workbench / debug-coord-transform

debug-coord-transform skill

/src/world-tools/minecraft/debug-coord-transform

This skill helps you validate and convert coordinates between agent-relative and world-relative frames for debugging and testing transformations.

npx playbooks add skill bdambrosio/cognitive_workbench --skill debug-coord-transform

Review the files below or copy the command above to add this skill to your agents.

Files (2)
Skill.md
955 B
---
name: debug-coord-transform
type: python
hidden: true
description: "Debug tool: Transform coordinates between agent-relative and world-relative"
---

# debug-coord-transform

Debug tool for testing coordinate transformations. Converts between agent-relative and world-relative coordinates.

## Input

- `dx`: float - X coordinate
- `dy`: float - Y coordinate (unchanged, always vertical)
- `dz`: float - Z coordinate
- `yaw`: float - Agent yaw in degrees (default: from current status)
- `direction`: string - "agent-to-world" or "world-to-agent" (default: "agent-to-world")

## Output

Returns uniform return format with:
- `value`: Summary text
- `data`: Dict with:
  - `input`: `{dx, dy, dz, yaw, direction}`
  - `output`: `{dx, dy, dz}` (transformed coordinates)

## Notes

- Hidden from planner catalog (debug/testing only)
- Useful for validating coordinate transformations
- Accessible via direct `{"type": "debug-coord-transform"}` invocation

Overview

This skill is a debug tool that converts coordinates between agent-relative and world-relative frames. It helps validate and inspect coordinate transforms by applying a yaw rotation and returning both the original inputs and transformed values. Designed for quick, programmatic checks during development and testing.

How this skill works

Provide a 3D offset (dx, dy, dz) and an agent yaw in degrees. The skill rotates the X/Z pair around the vertical Y axis according to the specified direction: agent-to-world applies the agent yaw to local coordinates, world-to-agent applies the inverse rotation. The output includes a text summary and a data object showing the original input and the transformed coordinates.

When to use it

  • Verifying that agent-relative offsets map correctly into global/world coordinates.
  • Converting world coordinates into an agent's local frame for sensor or control testing.
  • Testing or debugging navigation, motion planning, or coordinate math.
  • Unit tests for transformation logic in simulation or robotics code.
  • Quickly checking yaw sign conventions and rotation direction.

Best practices

  • Pass yaw in degrees and confirm the yaw convention (clockwise vs counterclockwise) used by your system.
  • Keep dy unchanged; transforms only rotate the horizontal X/Z plane.
  • Use small, known offsets first (e.g., unit vectors) to verify expected rotation behavior.
  • Compare skill output against a trusted math library or analytic examples during validation.
  • Include both directions (agent-to-world and world-to-agent) in tests to ensure invertibility.

Example use cases

  • Transforming a forward offset (dx=1, dz=0) by yaw=90 to confirm it maps to the world right direction.
  • Converting a sensed world coordinate into agent-local coordinates for local obstacle avoidance.
  • Automated unit tests that assert world-to-agent(agent-to-world(p)) == p within tolerance.
  • Debugging mismatched coordinate frames between simulation and real robot telemetry.

FAQ

What inputs are required?

Provide dx, dy, dz and optionally yaw and direction. dy is unchanged; yaw defaults to the current agent status if not supplied.

What does direction mean?

"agent-to-world" rotates local coordinates by the agent yaw into world frame. "world-to-agent" applies the inverse rotation to convert world coordinates into the agent frame.