DART  6.7.3
Linkage.hpp
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2011-2019, The DART development contributors
3  * All rights reserved.
4  *
5  * The list of contributors can be found at:
6  * https://github.com/dartsim/dart/blob/master/LICENSE
7  *
8  * This file is provided under the following "BSD-style" License:
9  * Redistribution and use in source and binary forms, with or
10  * without modification, are permitted provided that the following
11  * conditions are met:
12  * * Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  * * Redistributions in binary form must reproduce the above
15  * copyright notice, this list of conditions and the following
16  * disclaimer in the documentation and/or other materials provided
17  * with the distribution.
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
19  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
20  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
26  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
29  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 #ifndef DART_DYNAMICS_LINKAGE_HPP_
34 #define DART_DYNAMICS_LINKAGE_HPP_
35 
37 #include <unordered_set>
38 
39 namespace dart {
40 namespace dynamics {
41 
54 {
55 public:
56 
58  struct Criteria
59  {
63  {
64  INCLUDE = 0,
67  UPSTREAM
68  };
69 
71  std::vector<BodyNode*> satisfy() const;
72 
75  struct Target
76  {
78  Target(BodyNode* _target = nullptr,
79  ExpansionPolicy _policy = INCLUDE,
80  bool _chain = false);
81 
84 
88 
92  bool mChain;
93  };
94 
98 
106  std::vector<Target> mTargets;
107 
113  struct Terminal
114  {
116  Terminal(BodyNode* _terminal = nullptr, bool _inclusive = true);
117 
120 
124  };
125 
128  std::vector<Terminal> mTerminals;
129 
130  protected:
131 
133  void refreshTerminalMap() const;
134 
136  void expansionPolicy(BodyNode* _start, ExpansionPolicy _policy,
137  std::vector<BodyNode*>& _bns) const;
138 
140  void expandDownstream(BodyNode* _start, std::vector<BodyNode*>& _bns,
141  bool _includeStart) const;
142 
144  void expandUpstream(BodyNode* _start, std::vector<BodyNode*>& _bns,
145  bool _includeStart) const;
146 
148  void expandToTarget(const Target& _start, const Target& _target,
149  std::vector<BodyNode*>& _bns) const;
150 
152  std::vector<BodyNode*> climbToTarget(BodyNode* _start, BodyNode* _target) const;
153 
155  std::vector<BodyNode*> climbToCommonRoot(
156  const Target& _start, const Target& _target, bool _chain) const;
157 
160  void trimBodyNodes(std::vector<BodyNode*>& _bns, bool _chain,
161  bool _movingUpstream) const;
162 
164  mutable std::unordered_map<BodyNode*, bool> mMapOfTerminals;
165  };
166 
168  static LinkagePtr create(const Criteria& _criteria,
169  const std::string& _name = "Linkage");
170 
172  LinkagePtr cloneLinkage() const;
173 
175  LinkagePtr cloneLinkage(const std::string& cloneName) const;
176 
177  // To expose MetaSkeleton::cloneMetaSkeleton(), which takes no cloneName.
179 
180  // Documentation inherited
181  MetaSkeletonPtr cloneMetaSkeleton(const std::string& cloneName) const override;
182 
185  bool isAssembled() const;
186 
188  void reassemble();
189 
191  void satisfyCriteria();
192 
193 protected:
194 
197  Linkage(const Criteria& _criteria, const std::string& _name = "Linkage");
198 
200  virtual void update();
201 
204 
207  std::vector<WeakBodyNodePtr> mParentBodyNodes;
208 };
209 
210 } // namespace dynamics
211 } // namespace dart
212 
213 #endif // DART_DYNAMICS_LINKAGE_HPP_
BodyNode class represents a single node of the skeleton.
Definition: BodyNode.hpp:78
A Linkage is a ReferentialSkeleton with the special property that all the BodyNodes included in it fo...
Definition: Linkage.hpp:54
LinkagePtr cloneLinkage() const
Creates and returns a clone of this Linkage.
Definition: Linkage.cpp:518
Linkage(const Criteria &_criteria, const std::string &_name="Linkage")
Constructor for the Linkage class.
Definition: Linkage.cpp:605
void reassemble()
Revert the assembly of this Linkage to its original structure.
Definition: Linkage.cpp:580
virtual void update()
Update any metadata needed by the Linkage or its derived classes.
Definition: Linkage.cpp:613
virtual MetaSkeletonPtr cloneMetaSkeleton(const std::string &cloneName) const=0
Creates an identical clone of this MetaSkeleton.
void satisfyCriteria()
Redefine this Linkage so that its Criteria is satisfied.
Definition: Linkage.cpp:590
std::vector< WeakBodyNodePtr > mParentBodyNodes
Recording of the parent BodyNodes that were held by each of the BodyNodes when the Linkage was constr...
Definition: Linkage.hpp:207
bool isAssembled() const
Returns false if the original assembly of this Linkage has been broken in some way.
Definition: Linkage.cpp:567
static LinkagePtr create(const Criteria &_criteria, const std::string &_name="Linkage")
Create a Linkage with the given Criteria.
Definition: Linkage.cpp:481
Criteria mCriteria
Criteria that defines the structure of this Linkage.
Definition: Linkage.hpp:203
MetaSkeletonPtr cloneMetaSkeleton() const
Creates an identical clone of this MetaSkeleton.
Definition: MetaSkeleton.cpp:318
ReferentialSkeleton is a base class used to implement Linkage, Group, and other classes that are used...
Definition: ReferentialSkeleton.hpp:48
std::shared_ptr< Linkage > LinkagePtr
Definition: SmartPointer.hpp:74
std::shared_ptr< MetaSkeleton > MetaSkeletonPtr
Definition: SmartPointer.hpp:68
Definition: BulletCollisionDetector.cpp:63
This structure defines targets for the expansion criteria and the desired behavior for those targets.
Definition: Linkage.hpp:76
bool mChain
If this is set to true, the expansion towards this target will terminate if (1) a fork/split in the k...
Definition: Linkage.hpp:92
WeakBodyNodePtr mNode
The Linkage will expand from the starting BodyNode up to this node.
Definition: Linkage.hpp:83
ExpansionPolicy mPolicy
After the target has been reached (if it is reached), the Linkage will start to follow this expansion...
Definition: Linkage.hpp:87
Target(BodyNode *_target=nullptr, ExpansionPolicy _policy=INCLUDE, bool _chain=false)
Default constructor for Target.
Definition: Linkage.cpp:109
Any expansion performed by the criteria will be halted if mTerminal is reached.
Definition: Linkage.hpp:114
bool mInclusive
Whether or not the BodyNode should be included after expansion has halted.
Definition: Linkage.hpp:123
WeakBodyNodePtr mTerminal
BodyNode that should halt any expansion.
Definition: Linkage.hpp:119
Terminal(BodyNode *_terminal=nullptr, bool _inclusive=true)
Default constructor for Terminal.
Definition: Linkage.cpp:120
The Criteria class is used to specify how a Linkage should be constructed.
Definition: Linkage.hpp:59
Target mStart
This Target will serve as the starting point for the criteria satisfaction.
Definition: Linkage.hpp:97
void expansionPolicy(BodyNode *_start, ExpansionPolicy _policy, std::vector< BodyNode * > &_bns) const
Satisfy the expansion policy of a target.
Definition: Linkage.cpp:138
std::vector< BodyNode * > climbToTarget(BodyNode *_start, BodyNode *_target) const
Expand upwards from the _start BodyNode to the _target BodyNode.
Definition: Linkage.cpp:368
std::vector< Target > mTargets
The Linkage will extend from mStart to each of these targets.
Definition: Linkage.hpp:106
void expandToTarget(const Target &_start, const Target &_target, std::vector< BodyNode * > &_bns) const
Construct a path from start to target.
Definition: Linkage.cpp:320
void refreshTerminalMap() const
Refresh the content of mMapOfTerminals.
Definition: Linkage.cpp:128
std::vector< Terminal > mTerminals
Any expansion (whether from an ExpansionPolicy or an attempt to reach an entry in mTargets) will be h...
Definition: Linkage.hpp:128
ExpansionPolicy
The ExpansionPolicy indicates how the collection of BodyNodes should expand from the starting BodyNod...
Definition: Linkage.hpp:63
@ UPSTREAM
Include the target, and then expand upstream, toward the root of the tree.
Definition: Linkage.hpp:67
@ EXCLUDE
Do not expand from the target. Include everything up to the target, but NOT the target,...
Definition: Linkage.hpp:65
@ INCLUDE
Do not expand from the target. Include everything up to the target and then stop.
Definition: Linkage.hpp:64
@ DOWNSTREAM
Include the target, and then expand downstream, toward the leaves of the tree.
Definition: Linkage.hpp:66
std::vector< BodyNode * > satisfy() const
Return a vector of BodyNodes that satisfy the parameters of the Criteria.
Definition: Linkage.cpp:43
std::unordered_map< BodyNode *, bool > mMapOfTerminals
Hashed set for terminals to allow quick lookup.
Definition: Linkage.hpp:164
std::vector< BodyNode * > climbToCommonRoot(const Target &_start, const Target &_target, bool _chain) const
Expand upwards from both BodyNodes to a common root.
Definition: Linkage.cpp:388
void trimBodyNodes(std::vector< BodyNode * > &_bns, bool _chain, bool _movingUpstream) const
Crawl through the list and cut it off anywhere that the criteria is violated.
Definition: Linkage.cpp:425
void expandDownstream(BodyNode *_start, std::vector< BodyNode * > &_bns, bool _includeStart) const
Expand downstream.
Definition: Linkage.cpp:223
void expandUpstream(BodyNode *_start, std::vector< BodyNode * > &_bns, bool _includeStart) const
Expand upstream.
Definition: Linkage.cpp:250