sdf
SDFormat/SDF 模型和世界创作、验证和模拟器切换。用于“.sdf”文件、SDFormat XML、模型、世界、链接、关节、姿势、框架、惯性、视觉/碰撞几何、网格 URI、传感器、灯光、物理、插件、包括、Gazebo、静态 SDF 审查或模拟器特定的元数据。请勿用于有符号距离场几何。
- License 许可
- MIT
- 最近更新
- 2026-09-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sdf
- description
- SDFormat/SDF 模型和世界创作、验证和模拟器切换。用于“.sdf”文件、SDFormat XML、模型、世界、链接、关节、姿势、框架、惯性、视觉/碰撞几何、网格 URI、传感器、灯光、物理、插件、包括、Gazebo、静态 SDF 审查或模拟器特定的元数据。请勿用于有符号距离场几何。
02 资源文件 102
- 参考文档agents/openai.yaml273 B
- 许可证LICENSE1.0 KB
- 参考文档references/design-ledger.md4.1 KB
- 参考文档references/examples.md4.3 KB
- 参考文档references/frame-semantics.md3.6 KB
- 参考文档references/interoperability.md3.5 KB
- 参考文档references/llm-guardrails.md4.4 KB
- 参考文档references/sdf-workflow.md4.1 KB
- 参考文档references/smoke-tests.md3.1 KB
- 参考文档references/validation.md7.1 KB
- 参考文档requirements.txt26 B
- 许可证scripts/packages/cadgen/LICENSE1.0 KB
- 脚本scripts/packages/cadgen/pyproject.toml1.5 KB
- 脚本scripts/packages/cadgen/src/cadgen/__init__.py2.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/__init__.py235 B
- 脚本scripts/packages/cadgen/src/cadgen/_internal/assembly_spec.py1.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/atomic_replace.py7.0 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/cli_errors.py4.1 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/cli_locking.py3.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/component_package.py37.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/drawing_package.py27.4 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/file_metadata.py1.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/font_scan.py9.6 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/generation_runner.py25.5 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/generation_spec.py20.7 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/generation.py59.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/glb_mesh_payload.py25.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/glb_topology.py21.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/glb.py45.2 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/implicit_package.py15.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/legacy_artifacts.py6.4 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/node_resolve_hooks.mjs2.4 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/node_resolve_register.mjs367 B
- 脚本scripts/packages/cadgen/src/cadgen/_internal/node_runtime.py19.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/package_freshness.py4.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/source_hash.py22.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_hash.py345 B
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_metadata.py12.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_scene_cache.py14.4 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_scene_geometry.py24.1 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_scene_loader.py18.0 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_scene_mesh.py17.0 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_scene_selectors.py44.7 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_scene_types.py4.5 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/step_scene.py5.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/stl.py926 B
- 脚本scripts/packages/cadgen/src/cadgen/_internal/threemf.py19.6 KB
- 脚本scripts/packages/cadgen/src/cadgen/_internal/validators.py3.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/analysis.py24.4 KB
- 脚本scripts/packages/cadgen/src/cadgen/api.py292 B
- 脚本scripts/packages/cadgen/src/cadgen/assembly_lookup.py25.2 KB
- 脚本scripts/packages/cadgen/src/cadgen/assembly.py14.6 KB
- 脚本scripts/packages/cadgen/src/cadgen/cad_ref_syntax.py11.7 KB
- 脚本scripts/packages/cadgen/src/cadgen/catalog.py19.6 KB
- 脚本scripts/packages/cadgen/src/cadgen/check_fonts.py3.7 KB
- 脚本scripts/packages/cadgen/src/cadgen/cli_logging.py1.6 KB
- 脚本scripts/packages/cadgen/src/cadgen/cli_progress.py6.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/color.py2.2 KB
- 脚本scripts/packages/cadgen/src/cadgen/coordination/__init__.py20.7 KB
- 脚本scripts/packages/cadgen/src/cadgen/coordination/kinds.py4.5 KB
- 脚本scripts/packages/cadgen/src/cadgen/coordination/lock.py20.2 KB
- 脚本scripts/packages/cadgen/src/cadgen/coordination/paths.py5.0 KB
- 脚本scripts/packages/cadgen/src/cadgen/coordination/phases.py11.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/coordination/record.py6.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/drawing_checks.py16.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/drawing_render.py16.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/dxf_artifact.py8.4 KB
- 脚本scripts/packages/cadgen/src/cadgen/flatten.py11.0 KB
- 脚本scripts/packages/cadgen/src/cadgen/generation.py496 B
- 脚本scripts/packages/cadgen/src/cadgen/implicit_artifact.py8.6 KB
- 脚本scripts/packages/cadgen/src/cadgen/implicit_export.py9.5 KB
- 脚本scripts/packages/cadgen/src/cadgen/instances.py3.6 KB
- 脚本scripts/packages/cadgen/src/cadgen/interference.py11.1 KB
- 脚本scripts/packages/cadgen/src/cadgen/label_refs.py8.5 KB
- 脚本scripts/packages/cadgen/src/cadgen/lookup.py10.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/metadata.py13.2 KB
- 脚本scripts/packages/cadgen/src/cadgen/progress.py3.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/py.typed1 B
- 脚本scripts/packages/cadgen/src/cadgen/render.py1.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/reporting.py4.0 KB
- 脚本scripts/packages/cadgen/src/cadgen/selector_types.py374 B
- 脚本scripts/packages/cadgen/src/cadgen/snapshot_cli.py63.0 KB
- 脚本scripts/packages/cadgen/src/cadgen/snapshot_core.py46.1 KB
- 脚本scripts/packages/cadgen/src/cadgen/sources.py1.2 KB
- 脚本scripts/packages/cadgen/src/cadgen/step_artifact_cli.py21.3 KB
- 脚本scripts/packages/cadgen/src/cadgen/step_artifacts.py21.7 KB
- 脚本scripts/packages/cadgen/src/cadgen/step_export_target.py17.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/step_export.py14.9 KB
- 脚本scripts/packages/cadgen/src/cadgen/step_scene.py629 B
- 脚本scripts/packages/cadgen/src/cadgen/step_targets.py19.8 KB
- 脚本scripts/packages/cadgen/src/cadgen/validity.py7.7 KB
- 脚本scripts/sdf/__init__.py54 B
- 脚本scripts/sdf/cli.py5.7 KB
- 脚本scripts/sdf/external.py1.9 KB
- 脚本scripts/sdf/findings.py2.5 KB
- 脚本scripts/sdf/source.py10.4 KB
- 脚本scripts/sdf/validation.py42.8 KB
- 脚本scripts/snapshot/__init__.py30 B
- 脚本scripts/snapshot/__main__.py1.6 KB
- 脚本scripts/snapshot/runtime/render.html386 B
- 脚本scripts/snapshot/runtime/snapshot-render.js1.2 MB
- 脚本scripts/validate/__main__.py284 B
03 SKILL.md 正文
SDF
Provenance: maintained in earthtojake/text-to-cad. Use the installed local skill files as the runtime source of truth; the repository link is only for provenance and release review.
Use this skill when the deliverable is an SDFormat document. SDFormat describes simulator and world behavior: models, worlds, frames, poses, links, joints, inertials, visuals, collisions, sensors, lights, physics, plugins, includes, and simulator metadata.
This skill is for SDFormat, not signed-distance-field geometry.
The .sdf file is the source of truth: author and edit the XML directly. There is no gen_sdf() contract.
Core rules
- Author
.sdfXML directly and validate every created or modified file withscripts/validatebefore reporting completion. - Identify the target consumer before editing: Gazebo/libsdformat version, another simulator, visualization-only tooling, model package, or world handoff.
- Decide document kind: model-level SDF, world-level SDF, or model-in-world. Prefer model-level SDF for reusable robot/object exports.
- Use SI units unless the target explicitly requires otherwise: meters, kilograms, seconds, radians.
- Prefer
version="1.12"for new outputs unless the target consumer constrains the version. - Establish the design ledger before writing poses, frames, joint axes, mesh scales, inertials, sensors, or plugins, and keep it as a comment block at the top of the
.sdf. Usereferences/design-ledger.mdandreferences/llm-guardrails.md. - Write
relative_to/expressed_inexplicitly on every nontrivial pose and axis. Implicit frame defaults are the top SDF failure mode. Seereferences/frame-semantics.md. - Do not infer spatial transforms from visual impression alone. Derive poses, axes, scale, mass, inertia, and frame names from upstream source data, drawings, simulator documentation, measured values, or explicit assumptions. Never freehand computed numbers — use formulas or a throwaway helper script (inertia tensors, unit conversions).
- When the robot already has a URDF, derive the SDF from it instead of re-authoring geometry; see
references/interoperability.md. - Regenerate upstream geometry, mesh, robot-description, render, topology, or package assets with their owning workflows before editing SDF that references them.
- After authoring, run available checks: bundled validation, optional
gz sdf --check, simulator load, joint motion, and plugin/sensor startup. - Report assumptions, skipped checks, unresolved resource paths, and target-specific compatibility risks.
Scope
Use this skill for SDFormat outputs. Do not use it for signed-distance-field modeling, raw geometry generation, planning semantics, or to paper over incorrect upstream robot/source data unless the task is explicitly simulator-only.
CAD Viewer Handoff
After completing SDF work that creates or modifies a .sdf, you must ALWAYS hand the explicit file path to $cad-viewer when that skill is installed. $cad-viewer must start CAD Viewer if it is not already running and return link(s) to the relevant created or updated file(s); if $cad-viewer is unavailable or startup fails, report that instead of silently omitting the handoff.
Workflow
- Locate the target
.sdfand its consumers. - Read or create the design ledger comment block.
- Read
references/frame-semantics.mdbefore editing any<pose>,<frame>, joint axis,relative_to,expressed_in, nested scope, sensor frame, or plugin frame. - Author the XML directly, following the worked examples in
references/examples.md. - Validate the explicit target with
scripts/validate; treat bundled validation as a guardrail, not simulator proof. - Run target-consumer smoke tests when available (
references/smoke-tests.md). - Hand the file to
$cad-viewer. Static rendering does not execute SDF plugins or read file-authored motion metadata. - Report checks run, checks skipped, and assumptions.
Commands
Run with the project or workspace Python environment. Treat python in examples as an interpreter placeholder; if bare python is unavailable, substitute python3, a project virtualenv interpreter, or the configured interpreter path. The validator uses only the Python standard library.
python scripts/validate path/to/model.sdf
python scripts/validate path/to/a.sdf path/to/b.sdf
python scripts/validate path/to/model.sdf --strict
The validator checks document shape, name scopes, pose/frame graphs, joints, geometry, mesh URIs, inertials, sensors, and plugins, and prints per-file findings plus a summary. --strict treats warnings as failures. It exits nonzero if any target fails.
Optional external checking:
python scripts/validate path/to/model.sdf --gz-check auto
python scripts/validate path/to/model.sdf --gz-check required
python scripts/validate path/to/model.sdf --gz-check never
gz sdf --check is optional target-consumer validation. It should be reported as skipped when unavailable unless explicitly required.
Required report shape
When finishing an SDF task, include a compact report:
Validated: path/to/model.sdf
Checks run:
- bundled SDF validation: passed
- gz sdf --check: skipped, gz not installed
- simulator load: skipped, target simulator unavailable
- viewer handoff: `$cad-viewer` link returned
Assumptions:
- Assumed mesh units are meters.
- Assumed lidar frame is coincident with lidar_link.
Risks:
- Camera plugin filename was not verified in the target simulator environment.
Snapshot Tool
scripts/snapshot renders the robot to a PNG still or an orbit GIF, using the same shared
CLI and headless browser runtime every rendering skill uses — so a snapshot matches what
the CAD Viewer shows.
python scripts/snapshot --input path/to/robot.sdf --output review.png
python scripts/snapshot --input path/to/robot.sdf --output turntable.gif --mode orbit
It accepts .sdf only. Pose the robot with the job field "jointValues" (joint name to
degrees, defaulting to the rest pose) rather than --params, which is STEP-only; robots
are authored in metres and are framed on the robot scene scale automatically.
Theme settings live under one --theme, mirroring the viewer's Theme tab. The default
theme is snapshot — Workbench Light with the ground grid, origin axis and shadows
removed, because in a still image those read as geometry. There is no --display: display
settings (mode, clip, exploded, edges) are CAD topology settings, and a robot carries none.
Link meshes are resolved relative to the description, so they must be present: an
unhydrated Git LFS pointer fails as "No link mesh loaded for robot". Run
git lfs checkout <mesh dir> first.
Use python scripts/snapshot --help for the complete current command interface.
References
- SDF workflow:
references/sdf-workflow.md - Worked examples (golden skeletons):
references/examples.md - LLM guardrails:
references/llm-guardrails.md - Design ledger:
references/design-ledger.md - Frame semantics:
references/frame-semantics.md - Validation scope:
references/validation.md - Smoke tests:
references/smoke-tests.md - Interoperability notes (URDF-derived SDF, meshes, Gazebo):
references/interoperability.md
04 同仓库更多 Skills
vercel-react-view-transitions
使用 React 的视图转换 API(`<ViewTransition>` 组件、`addTransitionType` 和 CSS 视图转换伪元素)实现流畅、原生感觉的动画的指南。每当用户想要添加页面转换、为路线更改设置动画、创建共享元素动画、为组件的进入/退出设置动画、为列表重新排序设置动画、实现定向(向前/向后)导航动画或在 Next.js 中集成视图转换时,请使用此技能。当用户提及视图转换、startViewTransition、ViewTransition、转换类型或询问有关在 React 中的 UI 状态之间设置动画而无需第三方动画库时也可使用。
vercel-react-native-skills
React Native和Expo构建高性能移动应用程序的最佳实践。在构建React Native组件、优化列表性能、实现动画或使用本机模块时使用。涉及React Native、Expo、移动性能或本机平台API的任务的触发器。
vercel-react-best-practices
Vercel Engineering的React和Next.js性能优化指南。在编写、审查或重构React/Next.js代码时,应使用此技能,以确保最佳性能模式。涉及React组件、Next.js页面、数据获取、捆绑优化或性能改进的任务的触发器。
vercel-composition-patterns
可扩展的React组合模式。在重构具有布尔属性增殖的组件、构建灵活的组件库或设计可重用的API时使用。涉及复合组件、渲染道具、上下文提供者或组件架构的任务的触发器。包括React 19 API变更。
ui-styling
使用 shadcn/ui 组件(基于 Radix UI + Tailwind 构建)、Tailwind CSS 实用优先样式和基于画布的视觉设计创建美观、可访问的用户界面。在构建用户界面、实现设计系统、创建响应式布局、添加可访问组件(对话框、下拉菜单、表单、表格)、自定义主题和颜色、实现深色模式、生成视觉设计和海报或跨应用程序建立一致的样式模式时使用。
design
“综合设计技能:品牌标识、设计标记、UI 样式、徽标生成(55 种样式、Gemini 或 Atlas Cloud AI)、企业形象程序(50 个可交付成果、CIP 模型)、HTML 演示文稿(Chart.js)、横幅设计(22 种样式、社交/广告/网页/打印)、图标设计(15 种样式、SVG、Gemini 3.1 Pro)、社交照片(HTML→屏幕截图、多平台)。操作:设计徽标、创建 CIP、生成模型、构建幻灯片、设计横幅、生成图标、创建社交照片、社交媒体图像、品牌标识、设计系统:Facebook、Twitter、LinkedIn、YouTube、Instagram、Pinterest、TikTok、Threads、Google Ads。”