pinocchio  2.6.3
A fast and flexible implementation of Rigid Body Dynamics algorithms and their analytical derivatives
doc/_porting.md
1 # Porting from Pinocchio 1.3.3 to 2.0.0
2 
3 \section PortingIntro What is included
4 
5 This section describes how to port your code from the latest Pinocchio 1 release (1.3.3) to 2.0.
6 
7 Note that this section does not cover API changes that were made *before* Pinocchio 1.3.3.
8 Therefore, if you are still using an older version of Pinocchio 1,
9 it is recommended that before you switch to 2.0 you should upgrade to 1.3.3 and make sure everything still works.
10 In particular, remove all calls to deprecated methods and replace them appropriately.
11 
12 The vast majority of the changes took place in C++.
13 
14 \section PortingC Changes in C++
15 Although the class system was heavily re-worked, it should not make a lot of difference from the user's point of view.
16 Relevant changes are listed below.
17 
18 \subsection PortingCHeaderonly Header-only
19 Pinocchio is now fully header-only. This means you do not have to link to the Pinocchio library when compiling your code.
20 On the other hand, you might need to link to additional system libraries.
21 
22 \subsection PortingCNamespace Namespace
23 The most important change is the namespace.
24 Now, the top-level Pinocchio namespace is not `se3` anymore, but `pinocchio`.
25 
26 Therefore, all occurrences of `se3` in your code should be replaced by `pinocchio`.
27 
28 If you feel like "pinocchio" is too long to type but you do not want to employ `using namespace pinocchio`,
29 you can use
30 ```
31 namespace pin = pinocchio;
32 ```
33 
34 Your code will not compile if you try to use namespace `se3`.
35 In order to make it work, you need to compile it with the following flag
36 ```
37 -DPINOCCHIO_ENABLE_COMPATIBILITY_WITH_VERSION_1
38 ```
39 
40 \subsection PortingCMacros Deprecated macros
41 
42 The following marcos are not employed anymore
43 ```
44 WITH_HPP_FCL
45 WITH_URDFDOM
46 WITH_LUA5
47 ```
48 in favor of
49 ```
50 PINOCCHIO_WITH_HPP_FCL
51 PINOCCHIO_WITH_URDFDOM
52 PINOCCHIO_WITH_LUA5
53 ```
54 Therefore, you now need to issue the new macros in your compilation commands.
55 
56 If you are using them in your code, in order to make them work, you can do
57 ```
58 -DPINOCCHIO_ENABLE_COMPATIBILITY_WITH_VERSION_1
59 ```
60 
61 \subsection PortingCSignature Method signatures
62 Many methods which were taking a `ReferenceFrame = {WORLD/LOCAL}` enum as template parameter, such as `getJointJacobian`,
63 are now deprecated. The reference frame is now passed as an input.
64 For instance, you should switch from
65 ```
66 getJointJacobian<LOCAL>(model,data,jointId,J);
67 ```
68 to
69 ```
70 getJointJacobian(model,data,jointId,LOCAL,J);
71 ```
72 
73 Notice that in principle your old code will still work, but you will get deprecation warnings.
74 
75 \section PortingPython Changes in Python
76 Changes in Python are relatively minor.
77 
78 \subsection PortingPythonNamespace Namespace
79 
80 No real changes took place, but you are encouraged to stop using the idiom `import pinocchio as se3`.
81 
82 From now on, the recommended practice is `import pinocchio as pin`.
83 
84 \subsection PortingPythonRobotWrapper RobotWrapper
85 
86 The constructor signature has changed from
87 ```
88 __init__(self, filename, package_dirs=None, root_joint=None, verbose=False)
89 ```
90 to
91 ```
92 __init__(self, model = pin.Model(), collision_model = None, visual_model = None, verbose=False)
93 ```
94 so that a model can be directly provided without the need of resorting to URDF.
95 To recover the previous construction technique, you can use the static method
96 ```
97 RobotWrapper.BuildFromURDF(filename, package_dirs=None, root_joint=None, verbose=False)
98 ```
99 
100 Also, the signature
101 ```
102 jointJacobian(self, q, index, update_kinematics=True, local_frame=True)
103 ```
104 was changed to
105 ```
106 jointJacobian(self, q, index, rf_frame=pin.ReferenceFrame.LOCAL, update_kinematics=True)
107 ```
108 which should not change anything if you were only ever calling it with two arguments.
109 
110