Skip to content

Commit f3eab59

Browse files
authored
Update README to first public version
1 parent 001330e commit f3eab59

File tree

1 file changed

+41
-43
lines changed

1 file changed

+41
-43
lines changed

README.md

Lines changed: 41 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,45 @@
11
<img alt="SymForce" src="https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/images/symforce_horizontal_white.png" width="600px"/>
22

3-
[![Documentation](https://img.shields.io/badge/api-docs-blue)](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/index.html)
3+
[![Documentation](https://img.shields.io/badge/api-docs-blue)](https://symforce.org)
44
[![Source Code](https://img.shields.io/badge/source-code-blue)](https://github.com/symforce-org/symforce)
55
[![Issues](https://img.shields.io/badge/issue-tracker-blue)](https://github.com/symforce-org/symforce/issues)
66
![Python 3.8](https://img.shields.io/badge/python-3.8-blue)
77
![C++ 14](https://img.shields.io/badge/c++-14-blue)
88

99
---
10-
<span style="color:red"><b>WARNING: SymForce is strictly confidential until its public release.</b></span>
1110

12-
SymForce is a Python and C++ library for symbolic computation and code generation. It contains three independently useful systems:
11+
SymForce is a fast symbolic computation and code generation library for robotics applications like computer vision, state estimation, motion planning, and controls. It combines the development speed and flexibility of symbolic mathematics with the performance of autogenerated, highly optimized code in C++ or any target runtime language. SymForce contains three independently useful systems:
1312

14-
+ **Symbolic Toolkit** - builds on the SymPy API to provide rigorous geometric and camera types, lie group calculus, singularity handling, and tools to model large problems
13+
+ **Symbolic Toolkit** - builds on the SymPy API to provide rigorous geometric and camera types, lie group calculus, singularity handling, and tools to model complex problems
1514

1615
+ **Code Generator** - transforms symbolic expressions into blazing-fast, branchless code with clean APIs and minimal dependencies, with a template system to target any language
1716

18-
+ **Optimization Library** - performs on-manifold factor graph optimization with a highly optimized implementation for real-time robotics applications
17+
+ **Optimization Library** - a fast tangent-space optimization library based on factor graphs, with a highly optimized implementation for real-time robotics applications
1918

20-
SymForce accelerates robotics and computer vision tasks like visual odometry, bundle adjustment, calibration, sparse nonlinear MPC, and embedded motor control.
19+
SymForce automatically computes tangent space Jacobians, eliminating the need for any bug-prone handwritten derivatives. Generated functions can be directly used as factors in our nonlinear optimizer. This workflow enables faster runtime functions, faster development time, and fewer lines of handwritten code versus alternative methods.
20+
21+
SymForce was developed at [Skydio](https://skydio.com/). It is used in production to accelerate tasks like SLAM, bundle adjustment, calibration, and sparse nonlinear MPC for autonomous robots at scale.
2122

2223
<br/>
2324

2425
<img alt="SymForce" src="https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/images/symforce_diagram.png" width="700px"/>
2526

2627
<br/>
2728

28-
Features:
29-
30-
+ Rapidly prototype and analyze complex problems with symbolic math, with a seamless workflow into production use
31-
+ Compute fast and correct tangent-space jacobians for any expression
32-
+ Reduce duplication and minimize bugs by generating native runtime code in multiple languages from a canonical symbolic representation
33-
+ Generate embedded-friendly C++ functions that depend only on Eigen, are templated on the scalar type, and require no dynamic allocation
34-
+ Outperform automatic differentiation techniques, sometimes by 10x
35-
+ Leverage high quality, battle-hardened, and performant APIs at all levels
29+
#### Features:
3630

37-
# Note to early access participants
31+
+ Symbolic implementations of geometry and camera types with Lie group operations
32+
+ Code generation of fast native runtime code from symbolic expressions, reducing duplication and minimizing bugs
33+
+ Novel tools to compute fast and correct tangent-space jacobians for any expression, avoiding all handwritten derivatives
34+
+ Strategies for flattening computation and leveraging sparsity that can yield 10x speedups over standard autodiff
35+
+ A fast tangent-space optimization library in C++ and Python based on factor graphs
36+
+ Rapid prototyping and analysis of complex problems with symbolic math, with a seamless workflow into production use
37+
+ Embedded-friendly C++ generation of templated Eigen code with zero dynamic memory allocation
38+
+ Highly performant, modular, tested, and extensible code
3839

39-
Thank you for helping us develop SymForce! We value the time you're taking to provide feedback during this private beta program.
40+
# Early Access Notes
4041

41-
You will be invited to a private Slack channel with the authors. Please file specific issues on Github, and then use Slack for discussion. Do not share any links or code without express permission from the authors.
42+
Thank you for helping us develop SymForce! We value the time you're taking to provide feedback during this private beta program. We expect some rough edges and slow, missing, or confusing aspects of the library. Please file [issues](https://github.com/symforce-org/symforce/issues) on GitHub and we will work to address them.
4243

4344
Things to try:
4445

@@ -52,16 +53,10 @@ Things to try:
5253
* Use the C++ Factor and Optimizer to solve a problem
5354
* Read and understand the SymForce codebase
5455

55-
[**Read the docs!**](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/index.html)
56-
57-
We know that currently some things will be slow, missing, or confusing. We're working on it, but please let us know what you encounter.
58-
59-
In the future we will share a survey with specific questions, but more generally we are interested in all feedback you can provide about the value of the library, comparisons to alternatives, and any guidance to us.
56+
[**Read the docs!**](https://symforce.org)
6057

6158
# Build from source
6259

63-
<span style="color:blue">TODO: Create wheels for <code style="color:blue"><b>pip install symforce</b></code></span>
64-
6560
SymForce requires Python 3.8 or later. We suggest using conda or virtualenv:
6661

6762
```
@@ -114,6 +109,8 @@ Verify the installation in Python:
114109
>>> geo.Rot3()
115110
```
116111

112+
<span style="color:blue">TODO: Create wheels for <code style="color:blue"><b>pip install symforce</b></code></span>
113+
117114
# Tutorial
118115

119116
Let's walk through a simple example of modeling and solving an optimization problem with SymForce. In this example a robot moves through a 2D plane and the goal is to estimate its pose at multiple time steps given noisy measurements.
@@ -233,7 +230,7 @@ def odometry_residual(
233230
return geo.V1((pose_b.t - pose_a.t).norm(epsilon=epsilon) - dist)
234231
```
235232

236-
Now we can create [`Factor`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.opt.factor.html) objects from the residual functions and a set of keys. The keys are named strings for the function arguments, which will be accessed by name from a [`Values`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.values.values.html) class we later instantiate with numerical quantities.
233+
Now we can create [`Factor`](https://symforce.org/api/symforce.opt.factor.html?highlight=factor#module-symforce.opt.factor) objects from the residual functions and a set of keys. The keys are named strings for the function arguments, which will be accessed by name from a [`Values`](https://symforce.org/api/symforce.values.values.html) class we later instantiate with numerical quantities.
237234

238235
```python
239236
from symforce.opt.factor import Factor
@@ -267,7 +264,7 @@ Here is a visualization of the structure of this factor graph:
267264

268265
Our goal is to find poses of the robot that minimize the residual of this factor graph, assuming the
269266
landmark positions in the world are known. We create an
270-
[`Optimizer`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.opt.optimizer.html)
267+
[`Optimizer`](https://symforce.org/api/symforce.opt.optimizer.html?highlight=optimizer#module-symforce.opt.optimizer)
271268
with these factors and tell it to only optimize the pose keys (the rest are held constant):
272269
```python
273270
from symforce.opt.optimizer import Optimizer
@@ -280,7 +277,7 @@ optimizer = Optimizer(
280277
)
281278
```
282279

283-
Now we need to instantiate numerical [`Values`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.values.values.html) for the problem, including an initial guess for our unknown poses (just set them to identity).
280+
Now we need to instantiate numerical [`Values`](https://symforce.org/api/symforce.values.values.html?highlight=values#module-symforce.values.values) for the problem, including an initial guess for our unknown poses (just set them to identity).
284281

285282
```python
286283
import numpy as np
@@ -295,7 +292,7 @@ initial_values = Values(
295292
)
296293
```
297294

298-
Now run the optimization! This returns an [`Optimizer.Result`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.opt.optimizer.html#symforce.opt.optimizer.Optimizer.Result) object that contains the optimized values, error statistics, and per-iteration debug stats (if enabled).
295+
Now run the optimization! This returns an [`Optimizer.Result`](https://symforce.org/api/symforce.opt.optimizer.html?highlight=optimizer#symforce.opt.optimizer.Optimizer.Result) object that contains the optimized values, error statistics, and per-iteration debug stats (if enabled).
299296
```python
300297
result = optimizer.optimize(initial_values)
301298
```
@@ -315,24 +312,24 @@ All of the code for this example can also be found in `symforce/examples/robot_2
315312

316313
SymForce provides `sym` packages with runtime code for geometry and camera types that are generated from its symbolic `geo` and `cam` packages. As such, there are multiple versions of a class like `Pose3` and it can be a common source of confusion.
317314

318-
The canonical symbolic class [`geo.Pose3`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.geo.pose3.html) lives in the `symforce` package:
315+
The canonical symbolic class [`geo.Pose3`](https://symforce.org/api/symforce.geo.pose3.html) lives in the `symforce` package:
319316
```python
320317
from symforce import geo
321318
geo.Pose3.identity()
322319
```
323320

324-
The autogenerated Python runtime class [`sym.Pose3`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api-gen-py/sym.pose3.html) lives in the `sym` package:
321+
The autogenerated Python runtime class [`sym.Pose3`](https://symforce.org/api-gen-py/sym.pose3.html?highlight=pose3#module-sym.pose3) lives in the `sym` package:
325322
```python
326323
import sym
327324
sym.Pose3.identity()
328325
```
329326

330-
The autogenerated C++ runtime class [`sym::Pose3`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api-gen-cpp/class/classsym_1_1Pose3.html) lives in the `sym::` namespace:
327+
The autogenerated C++ runtime class [`sym::Pose3`](https://symforce.org/api-gen-cpp/class/classsym_1_1Pose3.html) lives in the `sym::` namespace:
331328
```C++
332329
sym::Pose3<double>::Identity()
333330
```
334331

335-
The matrix type for symbolic code is [`geo.Matrix`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.geo.matrix.html), for generated Python is [`numpy.ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html), and for C++ is [`Eigen::Matrix`](https://eigen.tuxfamily.org/dox/group__TutorialMatrixClass.html).
332+
The matrix type for symbolic code is [`geo.Matrix`](https://symforce.org/api/symforce.geo.matrix.html?highlight=matrix#module-symforce.geo.matrix), for generated Python is [`numpy.ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html), and for C++ is [`Eigen::Matrix`](https://eigen.tuxfamily.org/dox/group__TutorialMatrixClass.html).
336333

337334
The symbolic classes can also handle numerical values, but will be dramatically slower than the generated classes. The symbolic classes must be used when defining functions for codegen and optimization. Generated functions always accept the runtime types.
338335

@@ -344,7 +341,7 @@ As a convenience, the Python `Optimizer` class can accept symbolic types in its
344341

345342
Let's look under the hood to understand how that optimization worked. For each factor, SymForce introspects the form of the symbolic function, passes through symbolic inputs to build an output expression, automatically computes tangent-space jacobians of those output expressions wrt the optimized variables, and generates fast runtime code for them.
346343

347-
The [`Codegen`](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/api/symforce.codegen.codegen.html) class is the central tool for generating runtime code from symbolic expressions. In this case, we pass it the bearing residual function and configure it to generate C++ code:
344+
The [`Codegen`](https://symforce.org/api/symforce.codegen.codegen.html?highlight=codegen#module-symforce.codegen.codegen) class is the central tool for generating runtime code from symbolic expressions. In this case, we pass it the bearing residual function and configure it to generate C++ code:
348345
```python
349346
from symforce.codegen import Codegen, CppConfig
350347

@@ -540,17 +537,25 @@ $ -->
540537

541538
# Learn More
542539

543-
You can find more SymForce tutorials [here](https://symforce-6d87c842-22de-4727-863b-e556dcc9093b.vercel.app/docs/index.html#guides).
540+
You can find more SymForce tutorials [here](https://symforce.org/#guides).
544541

545542
# License
546543

547-
SymForce is released under the [BSD-3](https://opensource.org/licenses/BSD-3-Clause) license.
544+
SymForce is released under the [Apache 2.0](https://spdx.org/licenses/Apache-2.0.html) license.
548545

549546
See the LICENSE file for more information.
550547

548+
# Sponsors
549+
550+
SymForce is developed and maintained by [Skydio](https://skydio.com/). It is released as a free and open-source library for the robotics community. Contributors to the project are welcome!
551+
552+
<a href="http://skydio.com">
553+
<img alt="Skydio Logo" src="https://logovectordl.com/wp-content/uploads/2021/03/skydio-inc-logo-vector.png" width="300px" />
554+
</a>
555+
551556
# Future Ideas
552557

553-
There are lots of features we'd like to add, or would be happy to see added by contributors from the
558+
There are several features we'd like to add, or would be happy to see added by contributors from the
554559
community. Some of these are outlined in
555560
[the current Issues](https://github.com/symforce-org/symforce/issues), but some other major possible
556561
additions are:
@@ -559,10 +564,3 @@ additions are:
559564
functions, such as trig functions
560565
- Add more backend languages, such as CUDA, GLSL/HLSL, and TypeScript
561566
- More Lie group types, in particular Sim(3)
562-
563-
<style>
564-
img.latex-eqn {
565-
background-color:white;
566-
padding: 20px;
567-
}
568-
</style>

0 commit comments

Comments
 (0)