4 Contents {#faqcontents}
7 * [General](@ref general)
9 * [Common Errors](@ref errors)
10 * [Performance](@ref performance)
11 * [Comparison with Other Packages](@ref comparison)
19 - A: Amino is a lightweight library for robot modeling, control, and
22 * Q: What platforms are supported?
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.
29 * Q: Can I try amino in a virtual machine (VM)?
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
40 * Q: Why dual quaternions?
42 - A: Dual quaternions are more compact and computational easier to
43 normalize and filter than matrices.
45 * [Contents](@ref faqcontents)
47 Scene Graphs {#scenegraphs}
50 * Q: How can I load a URDF file?
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.
56 * Q: How can I reload a modified scene graph file without restarting my
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.
63 * [Contents](@ref faqcontents)
65 Common Errors {#errors}
68 * Q: `./configure` fails with when checking for cffi-grovel.
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).
73 * Q: I get error messages about missing .obj files or Blender being
74 unable to convert a .dae to Wavefront OBJ.
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.
82 * Q: When I try to compile a URDF file, I receive the error "aarx.core:
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.
90 * Q: When building aarx.core, I get an enormous stack trace, starting
92 `Unable to load any of the alternatives:
93 ("libamino_planning.so" (:DEFAULT "libamino_planning"))`.
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.
99 Sometimes, you just need to run `ldconfig` or `sudo ldconfig` to
100 update the linker cache.
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):
108 `export LD_LIBRARY_PATH="/usr/local/lib/:$LD_LIBRARY_PATH"`
110 `export LD_LIBRARY_PATH="/usr/local/lib/x86_64-linux-gnu/:$LD_LIBRARY_PATH"`
112 * [Contents](@ref faqcontents)
114 Performance {#performance}
117 * Q: How do I make it faster?
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).
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.
130 * Q: Why is the scene graph (aarxc) compiler slow?
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
138 * Q: Ray Tracing is SLOOOWWW!
140 - A: Ray tracing is computationally expensive. Here are a few notes
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.
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
155 Optimize POV-Ray: Ray tracing is floating-point heavy. A few
156 compilation flags make a small but noticable (~10%) improvement in
159 * `-march=native`: optimize for the current CPU. This may take
160 advantage of FPU instructions available on newer CPUs, e.g.,
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.
168 * [Contents](@ref faqcontents)
170 Comparison with Other Packages {#comparison}
171 ==============================
173 * Q: How does Amino relate to MoveIt!?
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.
181 - A: MoveIt! is closely coupled with ROS. Amino can load ROS URDF
182 files and is also able to operate stand-alone.
184 * Q: How do the Scene Graphs in Amino compare to ROS URDF?
186 - A: URDF and Amino scene graphs contain similar information. Amino
187 can parse URDF files and referenced meshes into scene graphs.
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.
194 * Q: How do the Scene Graphs in Amino compare to the Trees in OROCOS
197 - A: Amino provides a more extensive set of kinematic operations
198 than KDL, e.g., logarithms, exponentials, derivatives, exact
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.
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.
211 - A: Amino scene graphs use quaternions which have better
212 computational properties that the matrices used in KDL.
214 * Q: How do the SE(3) functions in amino compare with the Eigen
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!
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
230 * [Contents](@ref faqcontents)