Documentation: RobotLocomotion/drake@688764d

Author: drake-jenkins-bot

doxygen_cxx/abstract__value__cloner_8h__incl_org.svg

@@ -171,28 +171,30 @@
 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
 <div class="textblock"><p>Class for configuring "collision filters"; collision filters limit the scope of various proximity queries. </p>
 <p>The sole source of CollisionFilterManager instances is <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a>. See <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html#scene_graph_collision_filter_manager" title="scene_graph_collision_filter_manager">SceneGraph's documentation</a> for details on acquiring an instance.</p>
-<p>A <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a> instance contains the set of geometry <span class="tt">G = D ⋃ A = {g₀, g₁, ..., gₙ}</span>, where D is the set of dynamic geometries and A is the set of anchored geometries (by definition <span class="tt">D ⋂ A = ∅</span>). <span class="tt">Gₚ ⊂ G</span> is the subset of geometries that have a proximity role (with an analogous interpretation of <span class="tt">Dₚ</span> and <span class="tt">Aₚ</span>). Many proximity queries operate on pairs of geometries (e.g., {gᵢ, gⱼ}). The set of proximity candidate pairs for such queries is initially defined as <span class="tt">C = (Gₚ × Gₚ) - (Aₚ × Aₚ) - Fₚ - Iₚ - Nₚ*</span>, where:</p>
+<p>A <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a> instance contains the set of geometries with assigned proximity properties <span class="tt">G = R ⋃ V ⋃ A = {g₀, g₁, ..., gₙ}</span>, where R is the set of dynamic rigid geometries, V is the set of deformable geometries, and A is the set of anchored rigid geometries. These three sets are pairwise disjoint. Many proximity queries operate on pairs of geometries (e.g., (gᵢ, gⱼ)). Those queries operate on a theoretical set of <em>candidate pairs</em>, <span class="tt">C ⊂ G × G</span>. C lacks many geometry pairs that have been excluded from consideration. CollisionFilterManager excludes many pairs intrinsically and provides mechanisms for the users to exclude even more pairs.</p>
+<p>Intrinsic Exclusions</p>
 <ul>
-<li><span class="tt">Gₚ × Gₚ = {{gᵢ, gⱼ}}, ∀ gᵢ, gⱼ ∈ Gₚ</span> is the Cartesian product of the set of <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a> proximity geometries.</li>
-<li><span class="tt">Aₚ × Aₚ</span> represents all pairs consisting only of anchored geometries; an anchored geometry is never tested against another anchored geometry.</li>
-<li><span class="tt">Fₚ = {{gᵢ, gⱼ}} ∀ i, j</span>, such that <span class="tt">gᵢ, gⱼ ∈ Dₚ</span> and <span class="tt">frame(gᵢ) == frame(gⱼ)</span>; the pairs where both geometries are rigidly affixed to the same frame.</li>
-<li><span class="tt">Iₚ = {{g, g}}, ∀ g ∈ Gₚ</span> is the set of all pairs consisting of a geometry with itself; there is no meaningful proximity query on a geometry with itself.</li>
-<li><span class="tt">Nₚ* = {{g, x}}, ∀ g ∈ Nₚ, x ∈ Gₚ, g ≠ x</span>, where <span class="tt">Nₚ ⊂ Gₚ</span> is the set of <em>inactive</em> geometries (see <a class="el" href="#a8ae1229956e8bf8c7808f19e1074ba38" title="Marks every geometry in geometry_set inactive.">Deactivate()</a>). An inactive geometry forms no candidate pair with any other geometry. Unlike the other terms, <span class="tt">Nₚ*</span> is evaluated against the <em>live</em> set <span class="tt">Gₚ</span>: a geometry registered after <span class="tt">g</span> was deactivated still forms no pair with <span class="tt">g</span>. Membership in <span class="tt">Nₚ</span> is edited directly by <a class="el" href="#a8ae1229956e8bf8c7808f19e1074ba38" title="Marks every geometry in geometry_set inactive.">Deactivate()</a> and <a class="el" href="#a5dee20d7593cfb4a52dcac48f4793cda" title="Marks every geometry in geometry_set active.">Activate()</a>; the declaration-based <a class="el" href="#a67386b6917b1243e34c6f092d4956386" title="Applies the given declaration to the geometry state managed by this instance.">Apply()</a> APIs edit pairs, not active status.</li>
+<li><span class="tt">I = {(g, g)}, ∀ g ∈ G</span> is the set of all pairs consisting of a geometry with itself; there is no meaningful proximity query on such a pair.</li>
+<li><span class="tt">A × A</span> represents all pairs consisting only of anchored geometries; an anchored geometry is never tested against another anchored geometry.</li>
+<li><span class="tt">F = {(gᵢ, gⱼ)} ∀ i, j</span>, such that <span class="tt">gᵢ, gⱼ ∈ R</span> and <span class="tt">frame(gᵢ) == frame(gⱼ)</span>; the pairs where both rigid geometries are affixed to the same frame. Pairs of deformable geometries are <em>not</em> included in this set. While deformable geometries are all registered on the world frame, they are not rigidly affixed to it.</li>
+<li>Intrinsic exclusions are immutable: they cannot be restored to the candidate set by the user.</li>
 </ul>
-<p>Only pairs contained in C will be included in pairwise proximity operations.</p>
-<p>The manager provides an interface to modify the set C. Pairwise changes are articulated with <a class="el" href="classdrake_1_1geometry_1_1_collision_filter_declaration.html" title="Class for articulating changes to the configuration of SceneGraph&#39;s &quot;collision filters&quot;; collision fi...">CollisionFilterDeclaration</a>; once a change has been <em>declared</em> it is applied via <a class="el" href="#a67386b6917b1243e34c6f092d4956386" title="Applies the given declaration to the geometry state managed by this instance.">Apply()</a> (or <a class="el" href="#a0685b9bd25f37bd2cf50694b5c909e69" title="Applies the declaration as the newest transient modification to the collision filter configuration.">ApplyTransient()</a>) to change the configuration of C. Active status (the set <span class="tt">Nₚ</span>) is changed directly via <a class="el" href="#a8ae1229956e8bf8c7808f19e1074ba38" title="Marks every geometry in geometry_set inactive.">Deactivate()</a> and <a class="el" href="#a5dee20d7593cfb4a52dcac48f4793cda" title="Marks every geometry in geometry_set active.">Activate()</a>.</p>
-<p>There are limits to how C can be modified.</p>
+<p>User-Defined Exclusions</p>
 <ul>
-<li><span class="tt">∀ {gᵢ, gⱼ} ∈ C</span>, both gᵢ and gⱼ must be registered with <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a>; you can't inject arbitrary ids. Attempting to do so will result in an error.</li>
-<li>No pairs in <span class="tt">Aₚ × Aₚ</span>, <span class="tt">Fₚ</span>, or <span class="tt">Iₚ</span> can ever be added to C. Excluding those pairs is a <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a> invariant. Attempts to do so will be ignored.</li>
+<li><span class="tt">U = {(gᵢ, gⱼ)}</span> is the set of geometry pairs which have been explicitly excluded via the appropriate <a class="el" href="classdrake_1_1geometry_1_1_collision_filter_declaration.html" title="Class for articulating changes to the configuration of SceneGraph&#39;s &quot;collision filters&quot;; collision fi...">CollisionFilterDeclaration</a>. Subsequent declarations can remove the pair from U (restoring them to the candidate set). Those APIs encompass geometry pairs including deformable geometries. See the <a class="el" href="classdrake_1_1geometry_1_1_collision_filter_declaration.html" title="Class for articulating changes to the configuration of SceneGraph&#39;s &quot;collision filters&quot;; collision fi...">CollisionFilterDeclaration</a> documentation for further details.</li>
 </ul>
-<p>The current configuration of C depends on the sequence of filter declarations that have been applied in the manager. Changing the order can change the end result.</p>
+<p>Geometry Active Status</p>
+<p>In addition to excluding specific geometry pairs, a geometry can be declared inactive* (see <a class="el" href="#a8ae1229956e8bf8c7808f19e1074ba38" title="Marks every geometry in geometry_set inactive.">Deactivate()</a> and <a class="el" href="#a5dee20d7593cfb4a52dcac48f4793cda" title="Marks every geometry in geometry_set active.">Activate()</a>). An inactive geometry is essentially excluded from G. It still exists as a known geometry. So, adding or removing filters on that geometry is still valid. However, those declarations will have no apparent effect until the geometry is reactivated. An inactive geometry will simply never appear in any pair in the candidate set C.</p>
+<p>We can define <span class="tt">N</span> as the set of inactive geometries and <span class="tt">Gₐ = G - N</span> as the set of active geometries.</p>
+<p>Candidate Geometry Pairs</p>
+<p>Therefore, the set of geometry pair candidates C for proximity queries is defined as:</p>
+<p><span class="tt">C = (Gₐ × Gₐ) - (A × A) - F - I - U</span>.</p>
 <p>A CollisionFilterManager is a view into geometry data (either that owned by a <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a> instance or a <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a> context). The manager instance can be copied or moved and the resulting instance is a view into the same data. For both the original and the copy (or just the target when moving the manager), the source data must stay alive for at least as long as the manager instance.</p>
-<dl class="section warning"><dt>Warning</dt><dd>The effect of applying a declaration is based on the state of <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a>'s geometry data at the time of application. More concretely:<ul>
+<dl class="section warning"><dt>Warning</dt><dd>Generally, the effect of applying a declaration is based on the state of <a class="el" href="classdrake_1_1geometry_1_1_scene_graph.html" title="SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram.">SceneGraph</a>'s geometry data at the time of application. The geometry's active status is the one exception (see below). More concretely:<ul>
 <li>For a particular <a class="el" href="namespacedrake_1_1geometry.html#a43b41363b37fadf8cce0977d500e13cb" title="Type used to identify geometry frames in SceneGraph.">FrameId</a> in a <a class="el" href="classdrake_1_1geometry_1_1_geometry_set.html" title="The GeometrySet, as its name implies, is a convenience class for defining a set of geometries.">GeometrySet</a> instance, only those geometries attached to the identified frame with the proximity role assigned at the time of the call will be included in the filter. If geometries are subsequently added or assigned the proximity role, they will not be retroactively added to the user-declared filter.</li>
-<li>If the geometry set in a declaration statement includes geometries which have <em>not</em> been assigned a proximity role, those geometries will be ignored. If a proximity role is subsequently assigned, those geometries will <em>still</em> not be part of any user-declared collision filters.</li>
-<li>In general, adding collisions and assigning proximity roles should happen prior to collision filter configuration.</li>
-<li>It's worth emphasizing that the inactive set <span class="tt">Nₚ</span> is unique. It is not affected by declarations and doesn't have the same limited scope that declarations have. No collision is allowed between an inactive geometry and any other geometry, regardless of whether the other geometry was added before or after the deactivation.</li>
+<li>In general, adding collision geometries and assigning proximity roles should happen prior to collision filter configuration.</li>
+<li>Declarations of user-defined exclusions and allowances can only be made on "known" geometries (geometries with assigned the proximity role). Declarations on unknown geometries will be rejected with an error.</li>
+<li>Declaring a set of geometries active/inactive is the exception. These add or remove the geometries from the set Gₐ. We are not adding/deleting filtered pairs at the time of declaration, but simply changing the active status of the geometries. A geometry's active status doesn't change just because other geometries get added/removed.</li>
 </ul>
 </dd></dl>
 <h3>Transient vs Persistent changes</h3>