[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-naver--roma":3,"tool-naver--roma":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160784,2,"2026-04-19T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":78,"owner_twitter":77,"owner_website":79,"owner_url":80,"languages":81,"stars":98,"forks":99,"last_commit_at":100,"license":101,"difficulty_score":102,"env_os":76,"env_gpu":103,"env_ram":104,"env_deps":105,"category_tags":109,"github_topics":111,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":116,"updated_at":117,"faqs":118,"releases":154},9832,"naver\u002Froma","roma","RoMa: A lightweight library to deal with 3D rotations in PyTorch.","RoMa 是一个专为 PyTorch 打造的轻量级库，旨在简化 3D 旋转数据的处理流程。在机器学习与计算机视觉研究中，3D 旋转的数学表示多样且复杂（如旋转矩阵、四元数、欧拉角等），不同格式间的转换及保持几何约束往往容易出错且难以实现自动微分。RoMa 正是为了解决这一痛点而生，它提供了一套高效、可微分的工具集，支持多种旋转表示形式的无缝转换、从任意输入回归旋转参数、以及计算旋转空间中的测地线距离等核心操作。\n\n该工具特别适合从事 3D 深度学习、机器人学、SLAM 或图形学的研究人员与开发者使用。无论是需要构建涉及姿态估计的神经网络，还是进行基于梯度的优化任务，RoMa 都能让复杂的旋转运算变得像普通张量操作一样简单直观。其技术亮点在于全面支持任意维度的批量处理（Batch Dimensions），并内置了特殊的正交化算法（如 Special Procrustes）以确保输出严格符合旋转群约束。此外，RoMa 还封装了刚体变换的组合与求逆功能，能够直接输出齐次坐标矩阵。通过 pip 即可轻松安装，RoMa 以其简洁的 API 设计和可靠的数值稳定性，成为处理 3D 旋转问题时值得信","RoMa 是一个专为 PyTorch 打造的轻量级库，旨在简化 3D 旋转数据的处理流程。在机器学习与计算机视觉研究中，3D 旋转的数学表示多样且复杂（如旋转矩阵、四元数、欧拉角等），不同格式间的转换及保持几何约束往往容易出错且难以实现自动微分。RoMa 正是为了解决这一痛点而生，它提供了一套高效、可微分的工具集，支持多种旋转表示形式的无缝转换、从任意输入回归旋转参数、以及计算旋转空间中的测地线距离等核心操作。\n\n该工具特别适合从事 3D 深度学习、机器人学、SLAM 或图形学的研究人员与开发者使用。无论是需要构建涉及姿态估计的神经网络，还是进行基于梯度的优化任务，RoMa 都能让复杂的旋转运算变得像普通张量操作一样简单直观。其技术亮点在于全面支持任意维度的批量处理（Batch Dimensions），并内置了特殊的正交化算法（如 Special Procrustes）以确保输出严格符合旋转群约束。此外，RoMa 还封装了刚体变换的组合与求逆功能，能够直接输出齐次坐标矩阵。通过 pip 即可轻松安装，RoMa 以其简洁的 API 设计和可靠的数值稳定性，成为处理 3D 旋转问题时值得信赖的得力助手。","\n\n# *RoMa*: A lightweight library to deal with 3D rotations in PyTorch.\n[![Documentation](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDocumentation--33cb56)](https:\u002F\u002Fnaver.github.io\u002Froma\u002F)\n[![PyPI version](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Froma.svg)](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Froma)\n[![ArXiv](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FarXiv-2103.16317-33cb56)](https:\u002F\u002Farxiv.org\u002Fabs\u002F2103.16317)\n[![Unit tests](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Factions\u002Fworkflows\u002Fmain.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Factions\u002Fworkflows\u002Fmain.yml)\n[![Downloads](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnaver_roma_readme_150dfe653354.png)](https:\u002F\u002Fpepy.tech\u002Fproject\u002Froma)\n\n*RoMa* (which stands for Rotation Manipulation) provides differentiable mappings between 3D rotation representations, mappings from Euclidean to rotation space, and various utilities related to rotations.\n\nIt is implemented in PyTorch and aims to be an easy-to-use and reasonably efficient toolbox for Machine Learning and gradient-based optimization.\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnaver_roma_readme_c15b1f4830dc.png\" alt=\"Logo\" width=\"120\"\u002F>\n\n## Documentation\nLatest documentation is available here: https:\u002F\u002Fnaver.github.io\u002Froma\u002F.\n\nBelow are some examples of use of *RoMa*:\n```python\nimport torch\nimport roma\n\n# Arbitrary numbers of batch dimensions are supported, for convenience.\nbatch_shape = (2, 3)\n\n# Conversion between rotation representations\nrotvec = torch.randn(batch_shape + (3,))\nq = roma.rotvec_to_unitquat(rotvec)\nR = roma.unitquat_to_rotmat(q)\nRbis = roma.rotvec_to_rotmat(rotvec)\neuler_angles = roma.unitquat_to_euler('xyz', q, degrees=True)\n\n# Regression of a rotation from an arbitrary input:\n# Special Procrustes orthonormalization of a 3x3 matrix\nR1 = roma.special_procrustes(torch.randn(batch_shape + (3, 3)))\n# Conversion from a 6D representation\nR2 = roma.special_gramschmidt(torch.randn(batch_shape + (3, 2)))\n# From the 10 coefficients of a 4x4 symmetric matrix\nq = roma.symmatrixvec_to_unitquat(torch.randn(batch_shape + (10,)))\n\n# Metrics on the rotation space\nR1, R2 = roma.random_rotmat(size=5), roma.random_rotmat(size=5)\ntheta = roma.utils.rotmat_geodesic_distance(R1, R2)\ncos_theta = roma.utils.rotmat_cosine_angle(R1.transpose(-2, -1) @ R2)\n\n# Operations on quaternions\nq_identity = roma.quat_product(roma.quat_conjugation(q), q)\n\n# Spherical interpolation between rotation vectors (shortest path)\nrotvec0, rotvec1 = torch.randn(batch_shape + (3,)), torch.randn(batch_shape + (3,))\nrotvec_interpolated = roma.rotvec_slerp(rotvec0, rotvec1, steps)\n\n# Rigid transformation T composed of a rotation part R and a translation part t\nt = torch.randn(batch_shape + (3,))\nT = roma.Rigid(R, t)\n# Composing and inverting transformations\nidentity = T @ T.inverse()\n# Casting the result to a batch of 4x4 homogeneous matrices\nM = identity.to_homogeneous()\n```\n\n## Installation\nThe easiest way to install *RoMa* is to use pip:\n```\npip install roma\n```\n\nAlternatively one can install the latest version of *RoMa* directly from the source repository:\n```\npip install git+https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\n```\n\n**With old pytorch versions (torch\u003C1.8)**, we recommend installing [torch-batch-svd](https:\u002F\u002Fgithub.com\u002FKinglittleQ\u002Ftorch-batch-svd)\nto achieve a significant speed-up with `special_procrustes` on CUDA GPUs.\nYou can check that this module is properly loaded using the function `roma.utils.is_torch_batch_svd_available()`.\n**With recent pytorch installations (torch>=1.8), `torch-batch-svd` is no longer needed or used.**\n\n\n## License\n*RoMa*, Copyright (c) 2020 NAVER Corp., is licensed under the 3-Clause BSD License (see [license](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fblob\u002Fmaster\u002FLICENSE)).\n\nBits of code were adapted from SciPy. Documentation is generated, distributed and displayed with the support of Sphinx and other materials (see [notice](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fblob\u002Fmaster\u002FNOTICE)).\n\n## Contributing\nPlease open an issue on GitHub if you have any suggestions.\nPull requests are also welcome.\nWe aim at keeping RoMa reliable and maintainable, and may accept contribution (whether submitted as suggestions or pull requests) at our discretion to that aim.\n\nBy contributing to RoMa, you are agreeing that your contributions (whether suggestions or pull requests) for which you have the right or authority to submit are licensed under its [LICENSE](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fblob\u002Fmaster\u002FLICENSE).\n\n## References\nFor a more in-depth discussion regarding differentiable mappings on the rotation space, please refer to:\n- [__Romain Brégier, Deep Regression on Manifolds: a 3D Rotation Case Study.__ in _2021 International Conference on 3D Vision (3DV)_, 2021.](https:\u002F\u002Farxiv.org\u002Fabs\u002F2103.16317)\n\nPlease cite this work in your publications:\n```\n@inproceedings{bregier2021deepregression,\n\ttitle={Deep Regression on Manifolds: a {3D} Rotation Case Study},\n\tauthor={Br{\\'e}gier, Romain},\n\tjournal={2021 International Conference on 3D Vision (3DV)},\n\tyear={2021}\n}\n```\n\n","# *RoMa*: 一个用于在 PyTorch 中处理 3D 旋转的轻量级库。\n[![文档](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDocumentation--33cb56)](https:\u002F\u002Fnaver.github.io\u002Froma\u002F)\n[![PyPI 版本](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Froma.svg)](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Froma)\n[![ArXiv](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FarXiv-2103.16317-33cb56)](https:\u002F\u002Farxiv.org\u002Fabs\u002F2103.16317)\n[![单元测试](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Factions\u002Fworkflows\u002Fmain.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Factions\u002Fworkflows\u002Fmain.yml)\n[![下载量](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnaver_roma_readme_150dfe653354.png)](https:\u002F\u002Fpepy.tech\u002Fproject\u002Froma)\n\n*RoMa*（代表“Rotation Manipulation”）提供了 3D 旋转表示之间的可微映射、从欧几里得空间到旋转空间的映射，以及与旋转相关的各种实用工具。\n\n它基于 PyTorch 实现，旨在为机器学习和基于梯度的优化提供一个易于使用且效率合理的工具箱。\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnaver_roma_readme_c15b1f4830dc.png\" alt=\"Logo\" width=\"120\"\u002F>\n\n## 文档\n最新文档请访问：https:\u002F\u002Fnaver.github.io\u002Froma\u002F。\n\n以下是 *RoMa* 的一些使用示例：\n```python\nimport torch\nimport roma\n\n# 为了方便起见，支持任意数量的批量维度。\nbatch_shape = (2, 3)\n\n# 旋转表示之间的转换\nrotvec = torch.randn(batch_shape + (3,))\nq = roma.rotvec_to_unitquat(rotvec)\nR = roma.unitquat_to_rotmat(q)\nRbis = roma.rotvec_to_rotmat(rotvec)\neuler_angles = roma.unitquat_to_euler('xyz', q, degrees=True)\n\n# 从任意输入回归旋转：\n# 对 3x3 矩阵进行特殊 Procrustes 正交化\nR1 = roma.special_procrustes(torch.randn(batch_shape + (3, 3)))\n# 从 6D 表示转换\nR2 = roma.special_gramschmidt(torch.randn(batch_shape + (3, 2)))\n# 从 4x4 对称矩阵的 10 个系数\nq = roma.symmatrixvec_to_unitquat(torch.randn(batch_shape + (10,)))\n\n# 旋转空间上的度量\nR1, R2 = roma.random_rotmat(size=5), roma.random_rotmat(size=5)\ntheta = roma.utils.rotmat_geodesic_distance(R1, R2)\ncos_theta = roma.utils.rotmat_cosine_angle(R1.transpose(-2, -1) @ R2)\n\n# 四元数操作\nq_identity = roma.quat_product(roma.quat_conjugation(q), q)\n\n# 旋转向量之间的球面插值（最短路径）\nrotvec0, rotvec1 = torch.randn(batch_shape + (3,)), torch.randn(batch_shape + (3,))\nrotvec_interpolated = roma.rotvec_slerp(rotvec0, rotvec1, steps)\n\n# 由旋转部分 R 和平移部分 t 组成的刚性变换 T\nt = torch.randn(batch_shape + (3,))\nT = roma.Rigid(R, t)\n# 变换的组合与逆运算\nidentity = T @ T.inverse()\n# 将结果转换为一批 4x4 齐次矩阵\nM = identity.to_homogeneous()\n```\n\n## 安装\n安装 *RoMa* 最简单的方式是使用 pip：\n```\npip install roma\n```\n\n或者，也可以直接从源代码仓库安装最新版本的 *RoMa*：\n```\npip install git+https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\n```\n\n**对于旧版 PyTorch（torch\u003C1.8）**，我们建议安装 [torch-batch-svd](https:\u002F\u002Fgithub.com\u002FKinglittleQ\u002Ftorch-batch-svd)，以便在 CUDA GPU 上显著加速 `special_procrustes` 操作。您可以使用函数 `roma.utils.is_torch_batch_svd_available()` 来检查该模块是否已正确加载。**对于较新的 PyTorch 版本（torch>=1.8），则不再需要或使用 `torch-batch-svd`。**\n\n## 许可证\n*RoMa*，版权所有 © 2020 NAVER Corp.，采用 3-Clause BSD 许可证（详见 [license](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fblob\u002Fmaster\u002FLICENSE)）。\n\n部分代码改编自 SciPy。文档由 Sphinx 支持生成、分发并展示，其他材料也一并包含在内（详见 [notice](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fblob\u002Fmaster\u002FNOTICE)）。\n\n## 贡献\n如果您有任何建议，请在 GitHub 上提交问题。我们也欢迎 Pull 请求。我们的目标是保持 RoMa 的可靠性和可维护性，并可能根据具体情况接受您的贡献（无论是建议还是 Pull 请求），以实现这一目标。\n\n通过为 RoMa 做出贡献，您即表示同意将您有权提交的贡献（无论是建议还是 Pull 请求）按照其 [LICENSE](https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fblob\u002Fmaster\u002FLICENSE) 进行许可。\n\n## 参考文献\n如需深入了解旋转空间上的可微映射，请参阅：\n- [__Romain Brégier，《流形上的深度回归：3D 旋转案例研究》。2021 年国际 3D 视觉会议 (3DV)，2021 年。](https:\u002F\u002Farxiv.org\u002Fabs\u002F2103.16317)\n\n请在您的出版物中引用此工作：\n```\n@inproceedings{bregier2021deepregression,\n\ttitle={Deep Regression on Manifolds: a {3D} Rotation Case Study},\n\tauthor={Br{\\'e}gier, Romain},\n\tjournal={2021 International Conference on 3D Vision (3DV)},\n\tyear={2021}\n}\n```","# RoMa 快速上手指南\n\nRoMa (Rotation Manipulation) 是一个轻量级的 PyTorch 库，专为处理 3D 旋转设计。它提供了不同 3D 旋转表示法之间的可微分映射、从欧几里得空间到旋转空间的映射以及各种旋转相关工具，非常适合机器学习和基于梯度的优化任务。\n\n## 环境准备\n\n*   **操作系统**: Linux, macOS, Windows\n*   **Python**: 建议 Python 3.6+\n*   **核心依赖**:\n    *   `torch` (PyTorch): 版本 >= 1.8 (推荐)。\n    *   *注*: 若使用旧版 PyTorch (`torch \u003C 1.8`) 且在 CUDA GPU 上运行，建议额外安装 `torch-batch-svd` 以显著提升 `special_procrustes` 的速度。新版 PyTorch 无需此依赖。\n\n## 安装步骤\n\n推荐使用 pip 进行安装：\n\n```bash\npip install roma\n```\n\n如果需要安装最新的开发版本，可以直接从源码仓库安装：\n\n```bash\npip install git+https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\n```\n\n*(国内用户若下载缓慢，可尝试添加 `-i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple` 参数使用清华镜像源)*\n\n## 基本使用\n\nRoMa 支持任意数量的批次维度（batch dimensions），以下是核心功能的最简示例：\n\n```python\nimport torch\nimport roma\n\n# 定义批次形状 (例如: 2x3 的批次)\nbatch_shape = (2, 3)\n\n# 1. 旋转表示法转换\n# 生成随机旋转向量 (rotvec)\nrotvec = torch.randn(batch_shape + (3,))\n# 转换为四元数 (unitquat)\nq = roma.rotvec_to_unitquat(rotvec)\n# 转换为旋转矩阵 (rotmat)\nR = roma.unitquat_to_rotmat(q)\n# 或者直接由旋转向量转为旋转矩阵\nRbis = roma.rotvec_to_rotmat(rotvec)\n# 转换为欧拉角 (xyz 顺序，角度制)\neuler_angles = roma.unitquat_to_euler('xyz', q, degrees=True)\n\n# 2. 从任意输入回归旋转\n# 对 3x3 矩阵进行特殊 Procrustes 正交化\nR1 = roma.special_procrustes(torch.randn(batch_shape + (3, 3)))\n# 从 6D 表示转换 (Gram-Schmidt 正交化)\nR2 = roma.special_gramschmidt(torch.randn(batch_shape + (3, 2)))\n\n# 3. 旋转空间度量\nR_rand1, R_rand2 = roma.random_rotmat(size=5), roma.random_rotmat(size=5)\n# 计算测地线距离\ntheta = roma.utils.rotmat_geodesic_distance(R_rand1, R_rand2)\n# 计算余弦角度\ncos_theta = roma.utils.rotmat_cosine_angle(R_rand1.transpose(-2, -1) @ R_rand2)\n\n# 4. 刚体变换 (旋转 + 平移)\nt = torch.randn(batch_shape + (3,))\nT = roma.Rigid(R, t)\n# 组合与逆变换: T * T_inv = 单位变换\nidentity = T @ T.inverse()\n# 转换为 4x4 齐次矩阵批次\nM = identity.to_homogeneous()\n```","某机器人研发团队正在训练一个基于深度学习的机械臂姿态估计模型，需要频繁处理三维旋转数据的转换、插值与优化。\n\n### 没有 roma 时\n- 开发者需手动编写旋转矩阵、四元数、欧拉角之间的转换公式，代码冗长且极易因符号错误或维度不匹配导致 Bug。\n- 在进行梯度下降优化时，直接回归旋转矩阵往往破坏正交性约束，导致预测结果出现“畸形”姿态，需额外编写复杂的投影层修正。\n- 计算两个旋转间的测地线距离或进行球面线性插值（SLERP）时，缺乏现成的高效算子，只能依赖缓慢的 CPU 循环或非可微的 NumPy 实现。\n- 处理批量数据（Batch）时，需反复调整张量维度以适配广播机制，调试过程耗时且容易引发内存溢出。\n\n### 使用 roma 后\n- 调用 `roma.rotvec_to_rotmat` 等一行代码即可实现任意旋转表示间的高精度可微转换，彻底消除手动推导公式的错误风险。\n- 利用 `roma.special_procrustes` 直接将网络输出的任意矩阵投影为合法的正交旋转矩阵，确保模型输出始终符合物理约束。\n- 内置 `roma.utils.rotmat_geodesic_distance` 和 `roma.rotvec_slerp` 提供原生 GPU 加速的可微操作，显著加快损失计算与数据增强流程。\n- 自动支持任意数量的批次维度（Batch Dimensions），无需关心张量形状细节，让开发者专注于模型架构设计而非底层数学实现。\n\nroma 将繁琐且易错的三维旋转数学运算封装为简洁、可微且高效的 PyTorch 原语，让研究人员能专注于算法创新而非底层公式调试。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnaver_roma_c15b1f48.png","naver","NAVER","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fnaver_b4681208.png","",null,"opensource@navercorp.com","http:\u002F\u002Fdevelopers.naver.com","https:\u002F\u002Fgithub.com\u002Fnaver",[82,86,90,94],{"name":83,"color":84,"percentage":85},"Python","#3572A5",98.6,{"name":87,"color":88,"percentage":89},"Batchfile","#C1F12E",0.6,{"name":91,"color":92,"percentage":93},"Makefile","#427819",0.5,{"name":95,"color":96,"percentage":97},"Shell","#89e051",0.4,631,23,"2026-04-08T21:59:35","NOASSERTION",1,"非必需。若使用旧版 PyTorch (\u003C1.8) 并在 CUDA GPU 上运行，推荐安装 torch-batch-svd 以加速；新版 PyTorch (>=1.8) 无需额外组件即可在 CUDA 上运行。未指定具体显卡型号、显存大小或 CUDA 版本。","未说明",{"notes":106,"python":104,"dependencies":107},"该库是一个轻量级工具，主要通过 pip 安装。若使用 PyTorch 版本低于 1.8，建议额外安装 'torch-batch-svd' 库以获得显著的 CUDA 加速效果；PyTorch 1.8 及以上版本内置了相关功能，无需额外安装。代码支持任意数量的批次维度。",[108],"torch",[14,110],"其他",[112,113,114,115],"3d","geometry","pytorch","rotation","2026-03-27T02:49:30.150509","2026-04-20T07:18:26.616800",[119,124,129,134,139,144,149],{"id":120,"question_zh":121,"answer_zh":122,"source_url":123},44152,"如何正确采样均匀分布的单位四元数（Unit Quaternions）？","库的早期版本使用的采样算法不正确。正确的做法是参考 Kuffner 等人的算法（Algorithm 2），或者采用从多维正态分布中采样然后归一化的方法。具体来说，生成一个服从标准正态分布的四元数 $q = (x, y, z, w)$，由于多维正态分布具有球对称性，将其归一化后即可得到球面上均匀分布的点。维护者已在 v1.3.0 版本中更新了生成算法以修复此问题。","https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fissues\u002F4",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},44153,"RoMa 库是否支持欧拉角（Euler Angles）的转换？","是的，库已支持欧拉角。提供了 `euler_to_unitquat` 和 `unitquat_to_euler` 等函数。使用时需注意：1. 输入可以是原始浮点数列表或张量列表，例如 `euler_to_unitquat('xyz', [0.3, 0.4, 5.0])`；2. 关于逆运算，'xyz' 欧拉角 $(\\alpha, \\beta, \\gamma)$ 的逆实际上是 'zyx' 顺序的 $(-\\gamma, -\\beta, -\\alpha)$，而非简单的符号取反；3. 组合操作可以通过拼接约定字符串和角度列表来实现，例如 `euler_to_unitquat(convention1 + convention2, angles1 + angles2)`。","https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fissues\u002F16",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},44154,"在使用 `torch.vmap` 进行批处理或雅可比计算时遇到错误怎么办？","该问题通常是由库内部使用了原地操作（in-place operations，如 `matrix[..., i, j] = ...`）导致的，这与 `torch.vmap` 不兼容。解决方案是将这些原地赋值操作替换为函数式操作，例如使用 `torch.stack` 来构建矩阵，而不是先创建空张量再逐个填充元素。维护者已意识到此问题并计划重构代码以移除原地操作，从而完全兼容 `torch.vmap`。","https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fissues\u002F23",{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},44155,"使用旋转矩阵计算测地线距离损失时出现 NaN，但使用四元数正常，原因是什么？","这通常不是库本身的错误，而是数值稳定性或具体实现的问题。虽然理论上旋转矩阵和单位四元数计算的测地线距离应一致，但在反向传播中，旋转矩阵到旋转向量的转换如果中间经过四元数步骤可能会引入不稳定性。建议优先使用单位四元数（`unitquat_geodesic_distance`）进行损失计算，因为其数值表现通常更稳定。如果必须使用矩阵，请检查输入是否正交以及是否有非法的梯度截断。若无法提供复现代码，通常意味着问题出在用户特定的模型配置而非库本身。","https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fissues\u002F9",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},44156,"在 GPU (CUDA) 上运行时出现 \"misaligned address\" 错误，但在 CPU 上正常，如何解决？","如果代码在 CPU 上运行完美但在 GPU 上报错 \"CUDA error: misaligned address\"，这通常与 RoMa 库无关，而是用户的 GPU 配置、显存状态或其他 CUDA 内核异步执行导致的问题。建议尝试设置环境变量 `CUDA_LAUNCH_BLOCKING=1` 来获取更准确的堆栈跟踪信息。此外，检查神经网络训练过程中是否出现梯度爆炸导致输出变为 NaN，这也可能间接引发 CUDA 错误。","https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fissues\u002F7",{"id":145,"question_zh":146,"answer_zh":147,"source_url":148},44157,"`unitquat_to_rotvec` 中的 `shortest_path` 参数是否有用，是否存在 Bug？","在旧版本中，`shortest_path` 标志的实现存在逻辑冗余，因为底层的 `unitquat_to_rotvec` 总是返回角度在 $[0, \\pi]$ 范围内的旋转向量。此外，关于四元数符号翻转的代码曾存在潜在的原地操作风险。维护者已在 v1.3.0 版本中修复了相关问题，优化了四元数到旋转向量的映射逻辑，确保了最短路径处理的正确性和安全性。建议升级到最新版本以获得修复。","https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fissues\u002F3",{"id":150,"question_zh":151,"answer_zh":152,"source_url":153},44158,"是否可以直接将旋转矩阵转换为旋转向量而不经过四元数中间步骤？","目前库的实现通常会将旋转矩阵先转换为四元数，再转换为旋转向量。用户曾询问是否有直接转换的方法以避免反向传播中的潜在问题。经过测试，现有的 `rotvec_to_rotmat` 及其逆运算在常规训练代码中工作正常，未发现普遍的反向传播错误。如果用户在特定案例中遇到梯度问题，通常源于其特定的网络结构或数据分布，而非转换路径本身。目前没有直接的矩阵到向量公式被集成以替代现有流程，因为现有流程在数值上是稳定的。","https:\u002F\u002Fgithub.com\u002Fnaver\u002Froma\u002Fissues\u002F8",[]]