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