amino
Lightweight Robot Utility Library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
faq.md
1 FAQ {#FAQ}
2 ===
3 
4 Contents {#faqcontents}
5 =======
6 
7 * [General](@ref general)
8 * [SE(3)](@ref se3)
9 * [Common Errors](@ref errors)
10 * [Performance](@ref performance)
11 * [Comparison with Other Packages](@ref comparison)
12 
13 
14 General {#general}
15 ====
16 
17 * Q: What is Amino?
18 
19  - A: Amino is a lightweight library for robot modeling, control, and
20  visualization.
21 
22 * Q: What platforms are supported?
23 
24  - A: Amino is developed on Debian and Ubuntu Linux. It should run
25  on other Linux distributions and POSIX-y systems with minimal
26  effort. Currently, non-POSIX platforms are not targeted.
27 
28 SE(3) {#se3}
29 ====
30 
31 * Q: Why dual quaternions?
32 
33  - A: Dual quaternions are more compact and computational easier to
34  normalize and filter than matrices.
35 
36 * [Contents](@ref faqcontents)
37 
38 Scene Graphs {#scenegraphs}
39 ============
40 
41 * Q: How can I load a URDF file?
42 
43  - A: Use the scene graph compiler, `aarxc`, to generate code from the
44  URDF file. Note that URDF support has additional dependencies;
45  see `./INSTALL` for details.
46 
47 * Q: How can I reload a modified scene graph file without restarting my
48  program?
49 
50  - A: Compile the scene graph to a shared library and load the library
51  with dlopen(). To reload the scene graph, recompile the scene
52  graph and dlopen() the library again.
53 
54 * [Contents](@ref faqcontents)
55 
56 Common Errors {#errors}
57 =============
58 
59 * Q: `./configure` fails with when checking for cffi-grovel.
60 
61  - A: Older versions of SBCL (around 1.2.4) have issues with current
62  versions of CFFI. Please try installing a recent SBCL (>1.3.4).
63 
64 * Q: I get error messages about missing .obj files or Blender being
65  unable to convert a .dae to Wavefront OBJ.
66 
67  - A: We use Blender to convert various mesh formats to Wavefront OBJ,
68  then import the OBJ file. The Blender binaries in the Debian and
69  Ubuntu repositories (as of Jessie and Trusty) are not built with
70  COLLADA (.dae) support. You can download the prebuilt binaries
71  from http://www.blender.org/ which do support COLLADA.
72 
73 * Q: When I try to compile a URDF file, I receive the error "aarx.core:
74  not found".
75 
76  - A: URDF support in amino is only built if the necessary dependencies
77  are installed. Please ensure that you have SBCL, Quicklisp, and
78  Sycamore installed and rebuild amino if necessary. See
79  `./INSTALL` for details.
80 
81 * Q: When building aarx.core, I get an enormous stack trace, starting
82  with:
83  `Unable to load any of the alternatives:
84  ("libamino_planning.so" (:DEFAULT "libamino_planning"))`.
85 
86  - A: This means that SBCL is unable to load the planning library or one
87  of its dependecies, such as OMPL. Typically, this means your
88  linker is not configured properly.
89 
90  Sometimes, you just need to run `ldconfig` or `sudo ldconfig` to
91  update the linker cache.
92 
93  If this doesn't work, you can set the LD_LIBRARY_PATH variable.
94  First, find the location of libompl.so, e.g., by calling `locate
95  libompl.so`. Then, add the directory to your LD_LIBRARY_PATH
96  variable. Most commonly, this will mean adding one of the
97  following lines to your shell startup files (e.g., .bashrc):
98 
99  `export LD_LIBRARY_PATH="/usr/local/lib/:$LD_LIBRARY_PATH"`
100 
101  `export LD_LIBRARY_PATH="/usr/local/lib/x86_64-linux-gnu/:$LD_LIBRARY_PATH"`
102 
103 * [Contents](@ref faqcontents)
104 
105 Performance {#performance}
106 ===========
107 
108 * Q: How do I make it faster?
109 
110  - A: Numerical code often benefits from newer CPU instructions. Try
111  compiling amino with -march=native either via CFLAGS="-O2
112  -march=native ./configure or adding the equivalent to your
113  Autoconf site defaults file (config.site).
114 
115  - A: An optimized BLAS library will also help some
116  operations. OpenBLAS is among the fastest
117  (http://www.openblas.net/). If installed, configure amino to use
118  it with ./configure --with-blas=openblas.
119 
120 
121 * Q: Why is the scene graph (aarxc) compiler slow?
122 
123  - A: The scene graph compiler prepossesses meshes to reduce load
124  time. Mesh data is arranged in the compiled scene graph according
125  to its in-memory layout, eliminating the need to parse or copy
126  meshes at load time. However, the processing itself is somewhat
127  expensive.
128 
129 * Q: Ray Tracing is SLOOOWWW!
130 
131  - A: Ray tracing is computationally expensive. Here are a few notes
132  to help performance.
133 
134  Distribute: Ray tracing is embarassingly parallel, both across
135  multiple frames and across pixels within a frame. The easiest way
136  to render faster is to throw more cores at the problem.
137 
138  Parsing: While POV-Ray can use multiple threads to render a frame,
139  parsing the input file uses only a single core. If large meshes
140  are used, this can take a noticeable amount of time, and must be
141  repeated for each frame. Consequently, rather than using multiple
142  threads per frame, it may often be better to render multiple
143  frames in parallel so that parsing is parallelized across the
144  different frames.
145 
146  Optimize POV-Ray: Ray tracing is floating-point heavy. A few
147  compilation flags make a small but noticable (~10%) improvement in
148  performance.
149 
150  * `-march=native`: optimize for the current CPU. This may take
151  advantage of FPU instructions available on newer CPUs, e.g.,
152  AVX.
153  * `-ffast-math`: optimize floating-point computation in ways that
154  my violate IEEE semantics. Note that this could flag may
155  slightly change the resulting image.
156  * `-flto`: enable link-time optimization. This optimizes across
157  multiple translation units.
158 
159 * [Contents](@ref faqcontents)
160 
161 Comparison with Other Packages {#comparison}
162 ==============================
163 
164 * Q: How does Amino relate to MoveIt!?
165 
166  - A: MoveIt uses separate data structures for the robot the
167  environment. Amino uses a single data structure (the scene graph)
168  for both the robot and environment. Using a single data structure
169  greatly simplifies interactions with multiple objects, e.g.,
170  carrying a tray of objects or pushing a loaded cart.
171 
172  - A: MoveIt! is closely coupled with ROS. Amino can load ROS URDF
173  files and is also able to operate stand-alone.
174 
175 * Q: How do the Scene Graphs in Amino compare to ROS URDF?
176 
177  - A: URDF and Amino scene graphs contain similar information. Amino
178  can parse URDF files and referenced meshes into scene graphs.
179 
180  - A: Amino scene graphs use a streamlined parent-child
181  representation of kinematic topology which simplifies modifying
182  the kinematic structure, for example, if a robot picks up an
183  object or pushes a tray.
184 
185 * Q: How do the Scene Graphs in Amino compare to the Trees in OROCOS
186  KDL?
187 
188  - A: Amino provides a more extensive set of kinematic operations
189  than KDL, e.g., logarithms, exponentials, derivatives, exact
190  integration.
191 
192  - A: Amino scene graphs include support for geometry (i.e., meshes,
193  primitive shapes) attached to frames and provide visualization
194  (via OpenGL and POV-ray) and collision checking (via FCL).
195  Geometry is out of scope for KDL.
196 
197  - A: Amino scene graphs use a streamlined parent-child
198  representation of kinematic topology which simplifies modifying
199  the kinematic structure, for example, if a robot picks up an
200  object or pushes a tray.
201 
202  - A: Amino scene graphs use quaternions which have better
203  computational properties that the matrices used in KDL.
204 
205 * Q: How do the SE(3) functions in amino compare with the Eigen
206  Geometry module?
207 
208  - A: Aside from the superficial differences in API style, Amino
209  provides support for velocities, derivatives, logarithms, and
210  exponentials while Eigen does not. In fact, Eigen quaternions are
211  strictly unit quaternions, making it impossible to use them to
212  represent derivatives!
213 
214  - A: The Eigen Geometry module is composed of C++ templates,
215  allowing easy operations on other types (such as single or long
216  double floats) but complicating interfacing with languages besides
217  C++. Amino's SE(3) functions are written in C and operate on
218  double floats. These functions are easily called from other
219  languages.
220 
221 * [Contents](@ref faqcontents)