|
8 | 8 | <a href="https://symforce.org"><img alt="Documentation" src="https://img.shields.io/badge/api-docs-blue" /></a> |
9 | 9 | <a href="https://github.com/symforce-org/symforce"><img alt="Source Code" src="https://img.shields.io/badge/source-code-blue" /></a> |
10 | 10 | <a href="https://github.com/symforce-org/symforce/issues"><img alt="Issues" src="https://img.shields.io/badge/issue-tracker-blue" /></a> |
11 | | -<img alt="Python 3.8" src="https://img.shields.io/badge/python-3.8-blue" /> |
| 11 | +<img alt="Python 3.8 | 3.9 | 3.10" src="https://img.shields.io/pypi/pyversions/symforce" /> |
12 | 12 | <img alt="C++14" src="https://img.shields.io/badge/c++-14-blue" /> |
| 13 | +<a href="https://pypi.org/project/symforce/"><img alt="PyPI" src="https://img.shields.io/pypi/v/symforce" /></a> |
| 14 | +<a href="https://github.com/symforce-org/symforce/tree/main/LICENSE"><img alt="Apache License" src="https://img.shields.io/pypi/l/symforce" /></a> |
13 | 15 | </p> |
14 | 16 |
|
15 | 17 | --- |
@@ -48,88 +50,30 @@ SymForce is developed and maintained by [Skydio](https://skydio.com/). It is use |
48 | 50 | SymForce was published to [RSS 2022](https://roboticsconference.org/). Please cite it as follows: |
49 | 51 |
|
50 | 52 | ``` |
51 | | -@inproceedings{Martiros-RSS-22, |
52 | | - author = {Hayk Martiros AND Aaron Miller AND Nathan Bucki AND Bradley Solliday AND Ryan Kennedy AND Jack Zhu AND Tung Dang AND Dominic Pattison AND Harrison Zheng AND Teo Tomic AND Peter Henry AND Gareth Cross AND Josiah VanderMey AND Alvin Sun AND Samuel Wang AND Kristen Holtz}, |
53 | | - title = {{SymForce: Symbolic Computation and Code Generation for Robotics}}, |
54 | | - booktitle = {Proceedings of Robotics: Science and Systems}, |
55 | | - year = {2022}, |
56 | | - doi = {10.15607/RSS.2022.XVIII.041} |
57 | | -} |
| 53 | +@inproceedings{Martiros-RSS-22, |
| 54 | + author = {Hayk Martiros AND Aaron Miller AND Nathan Bucki AND Bradley Solliday AND Ryan Kennedy AND Jack Zhu AND Tung Dang AND Dominic Pattison AND Harrison Zheng AND Teo Tomic AND Peter Henry AND Gareth Cross AND Josiah VanderMey AND Alvin Sun AND Samuel Wang AND Kristen Holtz}, |
| 55 | + title = {{SymForce: Symbolic Computation and Code Generation for Robotics}}, |
| 56 | + booktitle = {Proceedings of Robotics: Science and Systems}, |
| 57 | + year = {2022}, |
| 58 | + doi = {10.15607/RSS.2022.XVIII.041} |
| 59 | +} |
58 | 60 | ``` |
59 | 61 |
|
60 | | -# Build from pip |
| 62 | +# Install |
61 | 63 |
|
62 | | -SymForce requires Python 3.8 or later. We suggest creating a virtual python environment. |
| 64 | +Install with pip: |
63 | 65 |
|
64 | | -Install the `gmp` package with one of: |
65 | | -``` |
66 | | -apt install libgmp-dev # Linux |
67 | | -brew install gmp # Mac |
68 | | -conda install -c conda-forge gmp # Conda |
69 | | -``` |
70 | | - |
71 | | -Install SymForce |
72 | | -``` |
73 | | -pip install -e . |
| 66 | +```bash |
| 67 | +pip install symforce |
74 | 68 | ``` |
75 | 69 |
|
76 | 70 | Verify the installation in Python: |
77 | 71 | ```python |
78 | 72 | >>> from symforce import geo |
79 | 73 | >>> geo.Rot3() |
80 | 74 | ``` |
81 | | -<span style="color:blue">TODO: Create wheels for <code style="color:blue"><b>pip install symforce</b></code></span> |
82 | | - |
83 | | -# Build CMake yourself (TODO deconflict) |
84 | | - |
85 | | -SymForce requires Python 3.8 or later. We suggest creating a virtual python environment. |
86 | | - |
87 | | -Install packages: |
88 | | -``` |
89 | | -# Linux |
90 | | -apt install doxygen libgmp-dev pandoc |
91 | | -
|
92 | | -# Mac |
93 | | -brew install doxygen gmp pandoc |
94 | | -
|
95 | | -# Conda |
96 | | -conda install -c conda-forge doxygen gmp pandoc |
97 | | -``` |
98 | | - |
99 | | -Install python requirements: |
100 | | -``` |
101 | | -pip install -r requirements.txt |
102 | | -``` |
103 | 75 |
|
104 | | -Install CMake if you don't already have a recent version: |
105 | | -``` |
106 | | -pip install "cmake>=3.19" |
107 | | -``` |
108 | | - |
109 | | -Build SymForce (requires C++14 or later): |
110 | | -``` |
111 | | -mkdir build |
112 | | -cd build |
113 | | -cmake .. |
114 | | -make -j 7 |
115 | | -``` |
116 | | -If you have build errors, try updating CMake. |
117 | | - |
118 | | -Install built Python packages: |
119 | | -``` |
120 | | -cd .. |
121 | | -pip install -e build/lcmtypes/python2.7 |
122 | | -pip install -e gen/python |
123 | | -pip install -e . |
124 | | -``` |
125 | | - |
126 | | -Verify the installation in Python: |
127 | | -```python |
128 | | ->>> from symforce import geo |
129 | | ->>> geo.Rot3() |
130 | | -``` |
131 | | - |
132 | | -<span style="color:blue">TODO: Create wheels for <code style="color:blue"><b>pip install symforce</b></code></span> |
| 76 | +This installs pre-compiled C++ components of SymForce on Linux and Mac using pip wheels, but does not include C++ headers. If you want to compile against C++ SymForce types (like `sym::Optimizer`), you currently need to [build from source](#build-from-source). |
133 | 77 |
|
134 | 78 | # Tutorial |
135 | 79 |
|
@@ -226,7 +170,7 @@ geo.V3.symbolic("x").norm(epsilon=sm.epsilon) |
226 | 170 |
|
227 | 171 | <!-- $\sqrt{x_0^2 + x_1^2 + x_2^2 + \epsilon}$ --> |
228 | 172 |
|
229 | | -<span style="color:blue">TODO: Link to a detailed epsilon tutorial once created.</span> |
| 173 | +See the [Epsilon Tutorial](https://symforce.org/notebooks/epsilon_tutorial.html) in the SymForce Docs for more information. |
230 | 174 |
|
231 | 175 | ## Build an optimization problem |
232 | 176 |
|
@@ -574,6 +518,52 @@ $ --> |
574 | 518 |
|
575 | 519 | To learn more, visit the SymForce tutorials [here](https://symforce.org/#guides). |
576 | 520 |
|
| 521 | +# Build from Source |
| 522 | + |
| 523 | +SymForce requires Python 3.8 or later. We strongly suggest creating a virtual python environment. |
| 524 | + |
| 525 | +Install the `gmp` package with one of: |
| 526 | +```bash |
| 527 | +apt install libgmp-dev # Ubuntu |
| 528 | +brew install gmp # Mac |
| 529 | +conda install -c conda-forge gmp # Conda |
| 530 | +``` |
| 531 | + |
| 532 | +SymForce contains both C++ and Python code. The C++ code is built using CMake. You can build the package either by calling pip, or by calling CMake directly. If building with `pip`, this will call CMake under the hood, and run the same CMake build for the C++ components. |
| 533 | + |
| 534 | +If you encounter build issues, please file an [issue](https://github.com/symforce-org/symforce/issues). |
| 535 | + |
| 536 | +## Build with pip |
| 537 | + |
| 538 | +The recommended way to build and install SymForce if you only plan on making Python changes is with pip. From the symforce directory: |
| 539 | +```bash |
| 540 | +pip install -e . |
| 541 | +``` |
| 542 | + |
| 543 | +This will build the C++ components of SymForce, but you won't be able to run `pip install -e .` repeatedly if you need to rebuild C++ code. If you're changing C++ code and rebuilding, you should build with CMake directly as described [below](#build-with-cmake). |
| 544 | + |
| 545 | +`pip install .` will not install pinned versions of SymForce's dependencies, it'll install any compatible versions. It also won't install all packages required to run all of the SymForce tests and build all of the targets (e.g. building the docs or running the linters). If you want all packages required for that, you should `pip install .[dev]` instead (or one of the other groups of extra requirements in our `setup.py`). If you additionally want pinned versions of our dependencies, which are the exact versions guaranteed by CI to pass all of our tests, you can install them from `pip install -r dev_requirements.txt`. |
| 546 | + |
| 547 | +## Build with CMake |
| 548 | + |
| 549 | +If you'll be modifying the C++ parts of SymForce, you should build with CMake directly instead - this method will not install |
| 550 | +SymForce into your Python environment, so you'll need to add it to your PYTHONPATH separately. |
| 551 | + |
| 552 | +Install python requirements: |
| 553 | +```bash |
| 554 | +pip install -r dev_requirements.txt |
| 555 | +``` |
| 556 | + |
| 557 | +Build SymForce (requires C++14 or later): |
| 558 | +```bash |
| 559 | +mkdir build |
| 560 | +cd build |
| 561 | +cmake .. |
| 562 | +make -j $(nproc) |
| 563 | +``` |
| 564 | + |
| 565 | +You'll then need to add SymForce (along with `gen/python` and `third_party/skymarshal` within symforce) to your PYTHONPATH in order to use them. |
| 566 | + |
577 | 567 | # License |
578 | 568 |
|
579 | 569 | SymForce is released under the [Apache 2.0](https://spdx.org/licenses/Apache-2.0.html) license. |
|
0 commit comments