{"id":15038989,"url":"https://github.com/artivis/manif","last_synced_at":"2025-05-14T09:06:32.947Z","repository":{"id":37819475,"uuid":"129808016","full_name":"artivis/manif","owner":"artivis","description":"A small C++11 header-only library for Lie theory.","archived":false,"fork":false,"pushed_at":"2025-03-26T21:59:56.000Z","size":9347,"stargazers_count":1603,"open_issues_count":28,"forks_count":259,"subscribers_count":43,"default_branch":"devel","last_synced_at":"2025-05-14T09:05:10.480Z","etag":null,"topics":["2d","3d","c-plus-plus","computer-vision","cpp11","geometry","header-only","lie-groups","lie-theory","python3","robotics","slam","state-estimation"],"latest_commit_sha":null,"homepage":"https://artivis.github.io/manif","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artivis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-04-16T21:28:32.000Z","updated_at":"2025-05-13T07:19:07.000Z","dependencies_parsed_at":"2023-01-24T01:31:07.269Z","dependency_job_id":"ad952a73-a9c0-46a9-bfdf-3bcc043226ac","html_url":"https://github.com/artivis/manif","commit_stats":{"total_commits":653,"total_committers":13,"mean_commits":50.23076923076923,"dds":0.4532924961715161,"last_synced_commit":"805a0b2adf9435dd658fdad5606c342db4d889e8"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artivis%2Fmanif","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artivis%2Fmanif/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artivis%2Fmanif/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artivis%2Fmanif/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artivis","download_url":"https://codeload.github.com/artivis/manif/tar.gz/refs/heads/devel","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110374,"owners_count":22016391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d","3d","c-plus-plus","computer-vision","cpp11","geometry","header-only","lie-groups","lie-theory","python3","robotics","slam","state-estimation"],"created_at":"2024-09-24T20:41:07.134Z","updated_at":"2025-05-14T09:06:32.912Z","avatar_url":"https://github.com/artivis.png","language":"C++","funding_links":[],"categories":["8. Tutorials","[Libraries](#awesome-robotics-libraries)","Robotics","C++"],"sub_categories":["8.3 Lie Algebra and Lie Groups","[Math](#awesome-robotics-libraries)"],"readme":"# manif\n\n## A small header-only library for Lie theory\n\n[![GHA][badge-ci-img]][badge-ci]\n[![appveyor][badge-ci-win-img]][badge-ci-win]\n[![Documentation][badge-doc-img]][manif-doc]\n[![codecov][badge-cov-img]][badge-cov]\n![GitHub][badge-license]\n[![JOSS][badge-joss-img]][deray20]\n\n## Package Summary\n\n\u003c!-- Include start manif intro --\u003e\n\n**manif** is a Lie theory library for state-estimation\ntargeted at robotics applications.\nIt is developed as a header-only C++11 library with Python 3 wrappers.\n\nAt the moment, it provides the groups:\n\n- ℝ(n): Euclidean space with addition.\n- SO(2): rotations in the plane.\n- SE(2): rigid motion (rotation and translation) in the plane.\n- SO(3): rotations in 3D space.\n- SE(3): rigid motion (rotation and translation) in 3D space.\n- SE_2(3): extended pose (rotation, translation and velocity) in 3D space,\n  introduced (to the best of knowledge) in this [paper][barrau15].\n  NOTE: The implementation here differs slightly from\n  the developments in the [paper][barrau15].\n- SGal(3): The Special Galilean group (rotation, translation, velocity and time) in 3D space,\n  described in these papers [[1][fourmy19]] \u0026 [[2][kelly24]].\n- Bundle\u003c\u003e: allows manipulating a manifold bundle as a single Lie group.\n  Referred to as a *composite manifold* in Section IV of the\n  [reference paper](http://arxiv.org/abs/1812.01537).\n\nOther Lie groups can and will be added, contributions are welcome.\n\n**manif** is based on the mathematical presentation of the Lie theory available in [this paper][jsola18].\nWe recommend every user of **manif** to read the paper (17 pages) before starting to use the library.\nThe paper offers a comprehensive yet accessible introduction to Lie theory, tailored specifically for roboticists.\nBy presenting the material in a simplified manner,\nit lowers the barrier to entry for those interested in developing rigorous and elegant algorithms for state estimation,\ncontrol, learning, and possibly more.\nThis approach ensures that even readers without an advanced mathematical background can grasp the\nfoundational concepts and apply them effectively in robotics.\n\n\u003c!-- Include stop manif intro --\u003e\n\nYou may also find the following video online,\n['Lie theory for the roboticist'][jsola-iri-lecture],\na lecture given at [IRI-UPC][IRI-UPC].\n\n\u003e In a rush? Check out our [Lie group cheat sheet][cheat_sheet].\n\n**manif** provides analytic computation of Jacobians for all the operations listed [below](#features).\n\n### Details\n\n- Maintainer status: maintained\n- Maintainer: Jeremie Deray\n- Authors:\n  - Jeremie Deray [deray.jeremie@gmail.com](mailto:deray.jeremie@gmail.com)\n  - Joan Sola [jsola@iri.upc.edu](mailto:jsola@iri.upc.edu)\n- License: [MIT](LICENSE)\n- Bug / feature tracker: [github.com/artivis/manif/issues][manif-issue]\n- Source: [github.com/artivis/manif.git][manif-repo] (branch: devel)\n\n## Quick Start\n\nGet quickly started with **manif** following our 'quick start' guides for both\n[C++](docs/pages/cpp/Quick-start.md) and [Python](docs/pages/python/Quick-start.md).\n\n## Features\n\n### Available Operations\n\n\u003c!-- Include start manif operation --\u003e\n\n| Operation  |       | Code |\n| :---       |   :---:   | :---: |\n|       |   Base Operation   |  |\n| Inverse | $\\bf\\mathcal{X}^{-1}$ | `X.inverse()` |\n| Composition | $\\bf\\mathcal{X}\\circ\\bf\\mathcal{Y}$ | `X * Y`\u003cbr/\u003e`X.compose(Y)` |\n| Hat | $\\boldsymbol\\varphi^\\wedge$ | `w.hat()` |\n| Act on vector | $\\bf\\mathcal{X}\\circ{\\bf v}$ | `X.act(v)` |\n| Retract to group element | $\\exp(\\boldsymbol\\varphi^\\wedge)$ | `w.exp()` |\n| Lift to tangent space | $\\log(\\bf\\mathcal{X})^\\vee$ | `X.log()` |\n| Manifold Adjoint | $\\mathrm{Adj}(\\bf\\mathcal{X})$ | `X.adj()` |\n| Tangent adjoint | $\\mathrm{adj}(\\boldsymbol\\varphi^\\wedge)$ | `w.smallAdj()` |\n|       |   Composed Operation   |  |\n| Manifold right plus | ${\\bf\\mathcal{X}}\\circ\\exp(\\boldsymbol\\varphi^\\wedge)$ | `X + w`\u003cbr/\u003e`X.plus(w)`\u003cbr/\u003e`X.rplus(w)` |\n| Manifold left plus | $\\exp(\\boldsymbol\\varphi^\\wedge)\\circ\\bf\\mathcal{X}$ | `w + X`\u003cbr/\u003e`w.plus(X)`\u003cbr/\u003e`w.lplus(X)` |\n| Manifold right minus | $\\log(\\bf\\mathcal{Y}^{-1}\\circ\\bf\\mathcal{X})^\\vee$ | `X - Y`\u003cbr/\u003e`X.minus(Y)`\u003cbr/\u003e`X.rminus(Y)` |\n| Manifold left minus | $\\log(\\bf\\mathcal{X}\\circ\\bf\\mathcal{Y}^{-1})^\\vee$ | `X.lminus(Y)` |\n| Between | ${\\bf\\mathcal{X}^{-1}}\\circ{\\bf\\mathcal{Y}}$ | `X.between(Y)` |\n| Inner Product | $\\langle\\boldsymbol\\varphi,\\boldsymbol\\tau\\rangle$ | `w.inner(t)` |\n| Norm | $\\left\\lVert\\boldsymbol\\varphi\\right\\rVert$ | `w.weightedNorm()`\u003cbr/\u003e`w.squaredWeightedNorm()` |\n\nAbove, ${\\bf\\mathcal{X}}$ \u0026 ${\\bf\\mathcal{Y}}$ (`X` \u0026 `Y`) represent group elements,\n${\\boldsymbol\\varphi^\\wedge}$ \u0026 ${\\boldsymbol\\tau^\\wedge}$ represent elements in the Lie algebra of the Lie group,\n${\\boldsymbol\\varphi}$ \u0026 ${\\boldsymbol\\tau}$ (`w` \u0026 `t`) represent the same elements of the tangent space\nbut expressed in Cartesian coordinates in $\\mathbb{R}^n$,\nand $\\mathbf{v}$ (`v`) represents any element of $\\mathbb{R}^n$.\n\n\u003c!-- Include stop manif operation --\u003e\n\n### Tangent spaces\n\n\u003c!-- Include start manif tangent --\u003e\n\n**manif** favors Cartesian representations of the tangent spaces.\nThis means that the tangent elements are regular vectors in $\\mathbb{R}^n$,\n'n' being the dimension of the Lie group.\n\nThe ordering of the elements in such vectors matters to correctly interpret them.\nIt impacts the form of all Jacobian matrices and covariances matrices that will be defined on those tangent spaces.\n\nAs a reference, this is the way tangent spaces are defined in **manif**\n\n| group | dimension | group elements | tangent elements (in order) | relation to velocity |\n| ---- | ---- | ---- | ---- | ---- |\n| Rn | n | $\\bf p$ | $\\bf p$ | ${\\bf p} = {\\bf v}\\cdot dt$ |\n| SO(2) | 1 | $\\bf R$ | $\\theta$ | $\\theta = \\omega\\cdot dt$ |\n| SO(3) | 3 | $\\bf R$ | $\\boldsymbol\\theta$ | $\\boldsymbol\\theta = \\boldsymbol\\omega\\cdot dt$ |\n| SE(2) | 3 | $\\bf p$, $\\bf R$ | $\\boldsymbol\\rho$, $\\theta$ | $\\boldsymbol\\rho = {\\bf v}\\cdot dt$\u003cbr/\u003e$\\theta = \\omega\\cdot dt$ |\n| SE(3) | 6 | $\\bf p$, $\\bf R$ | $\\boldsymbol\\rho$, $\\boldsymbol\\theta$ | $\\boldsymbol\\rho = {\\bf v}\\cdot dt$\u003cbr/\u003e$\\boldsymbol\\theta = \\boldsymbol\\omega\\cdot dt$ |\n| SE_2(3) | 9 | $\\bf p$, $\\bf R$, $\\bf v$ | $\\boldsymbol\\rho$, $\\boldsymbol\\theta$, $\\boldsymbol\\nu$ | $\\boldsymbol\\rho = {\\bf v}\\cdot dt$\u003cbr/\u003e$\\boldsymbol\\nu = {\\bf a}\\cdot dt$\u003cbr/\u003e$\\boldsymbol\\theta = {\\boldsymbol\\omega}\\cdot dt$ |\n| SGal(3) | 10 | $\\bf p$, $\\bf R$, $\\bf v$, $t$ | $\\boldsymbol\\rho$, $\\boldsymbol\\nu$, $\\boldsymbol\\theta$, $s$ | $\\boldsymbol\\rho = {\\bf v}\\cdot dt$\u003cbr/\u003e$\\boldsymbol\\nu = {\\bf a}\\cdot dt$\u003cbr/\u003e$\\boldsymbol\\theta = {\\boldsymbol\\omega}\\cdot dt$\u003cbr/\u003e$s = dt$ |\n\nAs an example, in SE_2(3) the tangent vector ${\\boldsymbol\\tau}$ is defined by\n\n$$\n{\\boldsymbol\\tau} =\n\\begin{bmatrix}\n{\\boldsymbol\\rho} \\\\\n{\\boldsymbol\\theta} \\\\\n{\\boldsymbol\\nu}\n\\end{bmatrix} \\in \\mathbb{R}^9\n$$\n\nwhere $\\boldsymbol\\rho$, $\\boldsymbol\\theta$ and $\\boldsymbol\\nu$ are $\\in \\mathbb{R}^3$ and\ntypically correspond respectively to changes in position, orientation and velocity.\n\nA covariances matrix $\\bf Q$ of an element of SE_2(3) can be block-partitioned as follows\n\n$$\n{\\bf Q} = \\begin{bmatrix}\n  {\\bf Q}_ {\\boldsymbol\\rho\\boldsymbol\\rho} \u0026 {\\bf Q}_ {\\boldsymbol\\rho\\boldsymbol\\theta} \u0026 {\\bf Q}_ {\\boldsymbol\\rho\\boldsymbol\\nu} \\\\\n  {\\bf Q}_ {\\boldsymbol\\theta\\boldsymbol\\rho} \u0026 {\\bf Q}_ {\\boldsymbol\\theta\\boldsymbol\\theta} \u0026 {\\bf Q}_ {\\boldsymbol\\theta\\boldsymbol\\nu} \\\\\n  {\\bf Q}_ {\\boldsymbol\\nu\\boldsymbol\\rho} \u0026 {\\bf Q}_ {\\boldsymbol\\nu\\boldsymbol\\theta} \u0026 {\\bf Q}_ {\\boldsymbol\\nu\\boldsymbol\\nu}\n  \\end{bmatrix} \\in \\mathbb{R}^{9\\times 9}\n$$\n\nAll blocks ${\\bf Q}_{\\bf ij}$ are $3\\times3$ and ${\\bf Q}$ is $9\\times9$.\n\n\u003c!-- Include stop manif tangent --\u003e\n\n### Jacobians\n\nAll operations come with their respective analytical Jacobian matrices.\nThroughout **manif**, **Jacobians are differentiated with respect to a perturbation on the local tangent space**.\nThese Jacobians map tangent spaces, as described in [this paper][jsola18].\nPlease consider [the order of elements in the tangent spaces](#tangent-spaces) when manipulating Jacobians.\n\nCurrently, **manif** implements the **right Jacobian**, whose definition reads:\n\n$$\n\\frac{\\delta f(\\bf\\mathcal{X})}{\\delta\\bf\\mathcal{X}}\\triangleq\n\\lim_{\\boldsymbol\\varphi\\to\\bf0}\\frac{f(\\bf\\mathcal{X}\\oplus\\boldsymbol\\varphi)\\ominus f(\\bf\\mathcal{X})}{\\boldsymbol\\varphi}\\triangleq\n\\lim_{\\boldsymbol\\varphi\\to\\bf0}\\frac{\\log(f({\\bf\\mathcal{X}})^{-1} f({\\bf\\mathcal{X}}\\exp(\\boldsymbol\\varphi^\\wedge)))^\\vee}{\\boldsymbol\\varphi}\n$$\n\nThe Jacobians of any of the aforementioned operations can then be evaluated:\n\nin C++,\n\n```cpp\nSE3d X = SE3d::Random();\nSE3Tangentd w = SE3Tangentd::Random();\n\nSE3d::Jacobian J_o_x, J_o_w;\n\nauto X_plus_w = X.plus(w, J_o_x, J_o_w);\n```\n\nin Python,\n\n```python\nX = SE3.Random()\nw = SE3Tangentd.Random()\n\nJ_o_x = np.zeros((SE3.DoF, SE3.DoF))\nJ_o_w = np.zeros((SE3.DoF, SE3.DoF))\n\nX_plus_w = X.plus(w, J_o_x, J_o_w)\n```\n\n#### Note\n\nWhile Jacobians in **manif** are differentiated with respect to a\nlocal perturbation on the tangent space, many non-linear solvers\n(e.g. [Ceres][ceres]) expect functions to be differentiated with respect to\nthe underlying representation vector of the group element\n(e.g. with respect to quaternion vector for `SO3`).\n\nFor this reason, **manif** is compliant with the auto-differentiation libraries\n[`ceres::Jet`][ceres-jet], [`autodiff::Dual`][autodiff] \u0026 [`autodiff::Real`][autodiff].\n\n## Documentation\n\nThe documentation is available online at the accompanying [website][manif-doc].\nBoth the [C++][manif-doc-cpp] and the [Python][manif-doc-python] APIs are documented.\n\nDo you want to build it locally?\nFind out how on the [dedicated page](docs/pages/documentation.md).\n\nNote: throughout the code documentation we refer to 'the paper' which you can\nfind on [the dedicated page](docs/pages/publication.md).\n\n## Tutorials and application demos\n\nWe provide some self-contained and self-explained\n[C++ examples](docs/pages/cpp/Quick-start.md#tutorials-and-application-demos) to help you get started.\n\nYou prefer Python? The same examples are also\n[available in Python](docs/pages/python/Quick-start.md#tutorials-and-application-demos).\n\n## Publications\n\nCheck out our related [publications](docs/pages/publication.md) and how to cite them.\n\n## They use manif\n\nFind out [who's already using manif](docs/pages/projects.md).\n\n## Contributing\n\nWant to contribute? Great! Check out our [contribution guidelines](CONTRIBUTING.md).\n\n[//]: # (URLs)\n\n[jsola18]: http://arxiv.org/abs/1812.01537\n[barrau15]: https://arxiv.org/pdf/1410.1465.pdf\n[fourmy19]: https://hal.science/hal-02183498/document\n[kelly24]: https://arxiv.org/abs/2312.07555\n[deray20]: https://joss.theoj.org/papers/10.21105/joss.01371\n\n[jsola-iri-lecture]: https://www.youtube.com/watch?v=nHOcoIyJj2o\n[IRI-UPC]: https://www.iri.upc.edu/\n\n[ceres]: http://ceres-solver.org/\n[ceres-jet]: http://ceres-solver.org/automatic_derivatives.html#dual-numbers-jets\n[autodiff]: https://autodiff.github.io/\n\n[manif-repo]: https://github.com/artivis/manif.git\n[manif-issue]: https://github.com/artivis/manif/issues\n[manif-doc]: https://artivis.github.io/manif/\n[manif-doc-cpp]: https://artivis.github.io/manif/cpp/index.html\n[manif-doc-python]: https://artivis.github.io/manif/python/index.html\n[cheat_sheet]: paper/Lie_theory_cheat_sheet.pdf\n\n[badge-ci]: https://github.com/artivis/manif/workflows/build-and-test/badge.svg?branch=devel\n[badge-ci-img]: https://github.com/artivis/manif/workflows/build-and-test/badge.svg?branch=devel\n[badge-ci-win]: https://ci.appveyor.com/project/artivis/manif\n[badge-ci-win-img]: https://ci.appveyor.com/api/projects/status/l0q7b0shhonvejrd?svg=true\n[badge-doc-img]: https://codedocs.xyz/artivis/manif.svg\n[badge-cov]: https://codecov.io/gh/artivis/manif\n[badge-cov-img]: https://codecov.io/gh/artivis/manif/branch/devel/graph/badge.svg\n[badge-license]: https://img.shields.io/github/license/mashape/apistatus.svg\n[badge-joss-img]: https://joss.theoj.org/papers/10.21105/joss.01371/status.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartivis%2Fmanif","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartivis%2Fmanif","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartivis%2Fmanif/lists"}