pydrake.geometry
Local bindings for render artifacts found in drake::geometry and drake::geometry::render
- pydrake.geometry.AddCompliantHydroelasticProperties(resolution_hint: float, hydroelastic_modulus: float, properties: pydrake.geometry.ProximityProperties) None
Adds properties to the given set of proximity properties sufficient to cause the associated geometry to generate a compliant hydroelastic representation. The geometry’s pressure field will be the function p(e) = Ee, where E is the hydroelastic modulus stored in the given
properties
.- Parameter
resolution_hint
: If the geometry is to be tessellated, it is the parameter that guides the level of mesh refinement. It has length units (in meters) and roughly corresponds to a typical edge length in the resulting mesh. See hug_properties. This will be ignored for geometry types that don’t require tessellation.
- Parameter
hydroelastic_modulus
: A multiplier that maps penetration to pressure. See hug_properties.
- Parameter
properties
: The properties will be added to this property set.
- Raises
RuntimeError If properties already has properties with the –
names that this function would need to add. –
- Precondition:
0 <
resolution_hint
< ∞, 0 <hydroelastic_modulus
, andproperties
is not nullptr.
- Parameter
- pydrake.geometry.AddCompliantHydroelasticPropertiesForHalfSpace(slab_thickness: float, hydroelastic_modulus: float, properties: pydrake.geometry.ProximityProperties) None
Compliant half spaces are handled as a special case; they do not get tessellated. Instead, they are treated as infinite slabs with a finite thickness. This variant is required for hydroelastic half spaces.
- Parameter
slab_thickness
: The distance from the half space boundary to its rigid core (this helps define the extent field of the half space).
- Parameter
hydroelastic_modulus
: A multiplier that maps penetration to pressure. See hug_properties.
- Parameter
properties
: The properties will be added to this property set.
- Raises
RuntimeError If properties already has properties with the –
names that this function would need to add. –
- Precondition:
0 <
slab_thickness
< ∞, 0 <hydroelastic_modulus
, andproperties
is not nullptr.
- Parameter
- pydrake.geometry.AddContactMaterial(*args, **kwargs)
Overloaded function.
AddContactMaterial(dissipation: Optional[float], point_stiffness: Optional[float], friction: Optional[drake::multibody::CoulombFriction<double>], properties: pydrake.geometry.ProximityProperties) -> None
AddContactMaterial() adds general contact material properties to the given set of proximity
properties
. These are the properties required by the default point contact model. However, other contact models can opt to use these properties as well. Only the parameters that carry values will be added to the given set ofproperties
; no default values will be provided. Downstream consumers of the contact materials can optionally provide defaults for missing properties.- Raises
RuntimeError if dissipation is negative, point_stiffness –
is not positive, of any of the contact material properties have –
already been defined in ``properties`. –
- Precondition:
properties
is not nullptr.
AddContactMaterial(properties: pydrake.geometry.ProximityProperties, dissipation: Optional[float] = None, point_stiffness: Optional[float] = None, friction: Optional[drake::multibody::CoulombFriction<double>] = None) -> None
AddContactMaterial() adds general contact material properties to the given set of proximity
properties
. These are the properties required by the default point contact model. However, other contact models can opt to use these properties as well. Only the parameters that carry values will be added to the given set ofproperties
; no default values will be provided. Downstream consumers of the contact materials can optionally provide defaults for missing properties.- Raises
RuntimeError if dissipation is negative, point_stiffness –
is not positive, of any of the contact material properties have –
already been defined in ``properties`. –
- Precondition:
properties
is not nullptr.
- pydrake.geometry.AddRigidHydroelasticProperties(*args, **kwargs)
Overloaded function.
AddRigidHydroelasticProperties(resolution_hint: float, properties: pydrake.geometry.ProximityProperties) -> None
Adds properties to the given set of proximity properties sufficient to cause the associated geometry to generate a rigid hydroelastic representation.
- Parameter
resolution_hint
: If the geometry is to be tessellated, it is the parameter that guides the level of mesh refinement. It has length units (in meters) and roughly corresponds to a typical edge length in the resulting mesh. See hug_properties. This will be ignored for geometry types that don’t require tessellation.
- Parameter
properties
: The properties will be added to this property set.
- Raises
RuntimeError If properties already has properties with the –
names that this function would need to add. –
- Precondition:
0 <
resolution_hint
< ∞ andproperties
is not nullptr.
AddRigidHydroelasticProperties(properties: pydrake.geometry.ProximityProperties) -> None
Overload, intended for shapes that don’t get tessellated in their hydroelastic representation (e.g., HalfSpace and Mesh). See hug_properties.
- class pydrake.geometry.Box
Bases:
pydrake.geometry.Shape
Definition of a box. The box is centered on the origin of its canonical frame with its dimensions aligned with the frame’s axes. The size of the box is given by three sizes.
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.Box, width: float, depth: float, height: float) -> None
Constructs a box with the given
width
, depth, andheight
, which specify the box’s dimension along the canonical x-, y-, and z-axes, respectively.- Raises
RuntimeError if width, depth or height are not strictly –
positive. –
__init__(self: pydrake.geometry.Box, measures: numpy.ndarray[numpy.float64[3, 1]]) -> None
Constructs a box with a vector of measures: width, depth, and height – the box’s dimensions along the canonical x-, y-, and z-axes, respectively.
- Raises
RuntimeError if the measures are not strictly positive. –
- depth(self: pydrake.geometry.Box) float
Returns the box’s dimension along the y axis.
- height(self: pydrake.geometry.Box) float
Returns the box’s dimension along the z axis.
- size(self: pydrake.geometry.Box) numpy.ndarray[numpy.float64[3, 1]]
Returns the box’s dimensions.
- width(self: pydrake.geometry.Box) float
Returns the box’s dimension along the x axis.
- pydrake.geometry.CalcVolume(shape: pydrake.geometry.Shape) float
Calculates the volume (in meters^3) for the Shape. For convex and mesh geometries, the algorithm only supports “.obj” files and only produces meaningful results for “closed” shapes.
- Raises
RuntimeError if the derived type hasn't overloaded this –
implementation (yet), if a filetype is unsupported, or if a –
referenced file cannot be opened. –
- class pydrake.geometry.Capsule
Bases:
pydrake.geometry.Shape
Definition of a capsule. The capsule can be thought of as a cylinder with spherical caps attached. The capsule’s length refers to the length of the cylindrical region, and the radius applies to both the cylinder and spherical caps. A capsule with zero length is a sphere of the given radius. And a capsule with zero radius is a line segment with the given length. The capsule is defined in its canonical frame C, centered on the frame origin and with the length of the capsule parallel with the frame’s z-axis.
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.Capsule, radius: float, length: float) -> None
Constructs a capsule with the given
radius
andlength
.- Raises
RuntimeError if radius or length are not strictly –
positive. –
__init__(self: pydrake.geometry.Capsule, measures: numpy.ndarray[numpy.float64[2, 1]]) -> None
Constructs a capsule with a vector of measures: radius and length.
- Raises
RuntimeError if the measures are not strictly positive. –
- length(self: pydrake.geometry.Capsule) float
- radius(self: pydrake.geometry.Capsule) float
- class pydrake.geometry.ClippingRange
Defines the near and far clipping planes for frustum-based (OpenGL) RenderEngine cameras.
Guidance on selecting clipping plane values
This documentation is targeted toward those who are unfamiliar with the OpenGL rasterization pipeline. For in-depth explanations about how the clipping range defines the viewing volume, see ` the discussion on projective transforms <https://www.glprogramming.com/red/chapter03.html#name3>`_. For more detail on its effect on determining occlusion (which geometries are in front), try ` “A Hidden-Surface Removal Survival Kit” <https://www.glprogramming.com/red/chapter05.html#name1>`_.
The short summary
The clipping range defines the distance of the closest and farthest
things that can appear in the rendering. - Objects that cross the planes placed at those distances get clipped. - Make the range as small as reasonably possible to get the best occlusion (a.k.a. z-buffer) results. - For depth cameras, make sure your clipping range always includes your valid depth range.
The longer discussion
Given that the clipping range defines what you can/can’t see in the camera, it might be tempting to just put an arbitrarily large range in (e.g., starting 1 micrometer away and going up to 1 million kilometers away). By doing so, you know everything you put into your scene will appear. If making sure things are visible were the only factor, this would be fine.
Rasterization pipelines render objects in arbitrary order but have to be able to determine which objects are in front of other objects as they go. They achieve this by creating a “z-buffer”. It is a measure of the depth of the triangle that rendered to a particular “pixel”. When two triangles both want to color the same pixel, the triangle with the smallest z-value is typically selected.
The z-buffer has fixed precision. That fixed precision is spread over the entire available depth range (as defined by the clipping range). The greater the range, the less precision the z-buffer has per meter of depth. A small range may have the ability to distinguish objects separated by 1 mm. But a large range may only be able to distinuish objects separated by 1 m. Two objects with measurably different depths relative to the camera, can become indistinguishable in the z-buffer due to these precision issues; the object that ends up in front is due to random chance. This will lead to artifacts where two objects near the same depth will flicker back and forth in front of each other (sometimes called “z fighting”).
So, it is best to define the smallest clipping range that will include the objects of the scene that you care about most.
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.ClippingRange, other: pydrake.geometry.ClippingRange) -> None
Copy constructor
__init__(self: pydrake.geometry.ClippingRange, near: float, far: float) -> None
Constructs the ClippingRange.
- Raises
RuntimeError if either value isn't finite and positive, or if –
near >= far` –
- far(self: pydrake.geometry.ClippingRange) float
- near(self: pydrake.geometry.ClippingRange) float
- class pydrake.geometry.CollisionFilterDeclaration
Class for articulating changes to the configuration of SceneGraph’s “collision filters”; collision filters limit the scope of various proximity queries.
This class provides the basis for declaring what pairs should or should not be included in the set of proximity query candidates C (see documentation for CollisionFilterManager for details on the set C).
A declaration consists of zero or more statements. Each statement can declare, for example, that the pair (g₁, g₂) should be excluded from C (also known as “filtering the pair”). That statement is added to the declaration by invoking the corresponding statement method (see below), and the result of the invocation, is that the statement is appended to the declaration.
Each statement method returns a reference to the declaration instance, so a number of statements can be chained together, i.e.,
Click to expand C++ code...
collision_filter_manager.Apply( CollisionFilterDeclaration() .ExcludeWithin(some_geometry_set) .ExcludeBetween(set_A, set_B));
It’s worth noting, that the statements are evaluated in invocation order such that a later statement can partially or completely undo the effect of an earlier statement. The full declaration is evaluated by CollisionFilterManager::Apply().
- __init__(self: pydrake.geometry.CollisionFilterDeclaration) None
- AllowBetween(self: pydrake.geometry.CollisionFilterDeclaration, set_A: drake::geometry::GeometrySet, set_B: drake::geometry::GeometrySet) pydrake.geometry.CollisionFilterDeclaration
Allows geometry pairs in proximity evaluation by updating the candidate pair set
C ← C ⋃ P*
, whereP = {(a, b)}, ∀ a ∈ A, b ∈ B, a ≠ b
andA = {a₀, a₁, ..., aₘ}
andB = {b₀, b₁, ..., bₙ}
are the input sets of geometriesset_A
andset_B
, respectively. WhereP* = P - (Aₚ × Aₚ) - Fₚ - Iₚ
, the set of pairs after we remove the SceneGraph-mandated invariants (see CollisionFilterManager for details on those invariants).To be explicit, in contrast to AllowWithin, this does not clear filters between members of the same set (e.g.,
(aᵢ, aⱼ)
or(bᵢ, bⱼ)
).
- AllowWithin(self: pydrake.geometry.CollisionFilterDeclaration, geometry_set: drake::geometry::GeometrySet) pydrake.geometry.CollisionFilterDeclaration
Allows geometry pairs in proximity evaluation by updating the candidate pair set
C ← C ⋃ P*
, whereP = {(gᵢ, gⱼ)}, ∀ gᵢ, gⱼ ∈ G, i ≠ j
andG = {g₀, g₁, ..., gₘ}
is the inputgeometry_set
of geometries. WhereP* = P - (Aₚ × Aₚ) - Fₚ - Iₚ
, the set of pairs after we remove the SceneGraph-mandated invariants (see CollisionFilterManager for details on those invariants).
- ExcludeBetween(self: pydrake.geometry.CollisionFilterDeclaration, set_A: drake::geometry::GeometrySet, set_B: drake::geometry::GeometrySet) pydrake.geometry.CollisionFilterDeclaration
Excludes geometry pairs from proximity evaluation by updating the candidate pair set
C ← C - P
, whereP = {(a, b)}, ∀ a ∈ A, b ∈ B
andA = {a₀, a₁, ..., aₘ}
andB = {b₀, b₁, ..., bₙ}
are the input sets of geometriesset_A
andset_B
, respectively.
- ExcludeWithin(self: pydrake.geometry.CollisionFilterDeclaration, geometry_set: drake::geometry::GeometrySet) pydrake.geometry.CollisionFilterDeclaration
Excludes geometry pairs from proximity evaluation by updating the candidate pair set
C ← C - P
, whereP = {(gᵢ, gⱼ)}, ∀ gᵢ, gⱼ ∈ G
andG = {g₀, g₁, ..., gₘ}
is the inputgeometry_set
of geometries.
- class pydrake.geometry.CollisionFilterManager
Class for configuring “collision filters”; collision filters limit the scope of various proximity queries.
The sole source of CollisionFilterManager instances is SceneGraph. See scene_graph_collision_filter_manager “SceneGraph’s documentation” for details on acquiring an instance.
A SceneGraph instance contains the set of geometry
G = D ⋃ A = {g₀, g₁, ..., gₙ}
, where D is the set of dynamic geometries and A is the set of anchored geometries (by definitionD ⋂ A = ∅
). Gₚ ⊂ G is the subset of geometries that have a proximity role (with an analogous interpretation ofDₚ
andAₚ
). Many proximity queries operate on pairs of geometries (e.g., (gᵢ, gⱼ)). The set of proximity candidate pairs for such queries is initially defined asC = (Gₚ × Gₚ) - (Aₚ × Aₚ) - Fₚ - Iₚ
, where:Gₚ × Gₚ = {(gᵢ, gⱼ)}, ∀ gᵢ, gⱼ ∈ Gₚ
is the Cartesian product of the set
of SceneGraph proximity geometries. -
Aₚ × Aₚ
represents all pairs consisting only of anchored geometries; an anchored geometry is never tested against another anchored geometry. -Fₚ = {(gᵢ, gⱼ)} ∀ i, j
, such thatgᵢ, gⱼ ∈ Dₚ
andframe(gᵢ) == frame(gⱼ)
; the pairs where both geometries are rigidly affixed to the same frame. -Iₚ = {(g, g)}, ∀ g ∈ Gₚ
is the set of all pairs consisting of a geometry with itself; there is no meaningful proximity query on a geometry with itself.Only pairs contained in C will be included in pairwise proximity operations.
The manager provides an interface to modify the set C. Changes to C are articulated with CollisionFilterDeclaration. Once a change has been declared it is applied via the manager’s API to change the configuration of C.
There are limits to how C can be modified.
∀ (gᵢ, gⱼ) ∈ C
, both gᵢ and gⱼ must be registered with SceneGraph; you
can’t inject arbitrary ids. Attempting to do so will result in an error. - No pairs in
Aₚ × Aₚ
, Fₚ, orIₚ
can ever be added to C. Excluding those pairs is a SceneGraph invariant. Attempts to do so will be ignored.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.
A CollisionFilterManager is a view into geometry data (either that owned by a SceneGraph instance or a SceneGraph 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.
Warning
The effect of applying a declaration is based on the state of SceneGraph’s geometry data at the time of application. More concretely: - For a particular FrameId in a GeometrySet 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. - If the geometry set in a declaration statement includes geometries which have not been assigned a proximity role, those geometries will be ignored. If a proximity role is subsequently assigned, those geometries will still not be part of any user-declared collision filters. - In general, adding collisions and assigning proximity roles should happen prior to collision filter configuration.
Transient vs Persistent changes
Collision filtering is all about defining which geometry pairs are in the set C. The simplest way to modify the set C is through persistent modifications to a “base configuration” (via calls to Apply()). However, declarations can also be applied in a transient manner. Transient declarations form a history. The current definition of the set C is the result of applying the history of collision filter declarations to the persistent base configuration in order. That history can be modified:
New transient declarations can be appended.
Arbitrary transient declarations can be removed from the sequence.
The current configuration (based on a history with an arbitrary number
of transient declarations) can be “flattened” into the persistent base (with no history).
The table below illustrates a sequence of operations and their effect on C. We define C’s initial configuration as
C = {P₁, P₂, ..., Pₙ}
(forn
geometry pairs). Each action is described as either persistent or transient.Line | C | Action | | :–: | :—————— |:————————————————– | | 1 |
{P₁, P₂, ..., Pₙ}
| Initial condition of the persistent base | | 2 |{P₂, ..., Pₙ}
| Remove P₁ from the persistent base | | 3 |{P₂, ..., Pₙ₋₁}
| Remove Pₙ from the persistent base | | 4 |{P₂}
| Remove all pairs except P₂ from the persistent base | | 5 |{P₂, P₄, P₅}
| Transient declaration #1 puts P₄ and P₅ into C | | 6 |{P₂, P₃, P₄, P₅}
| Transient declaration #2 puts P₃ and P₄ into C | | 7 |{P₂, P₃, P₄}
| Remove declaration #1. | | 8 |{P₂, P₃, P₄}
| Configuration flattened; #2 no longer exists | Table 1: An example sequence of operations on collision filters.Notes: - lines 2 - 4 represent a series of persistent operations, filtering pairs of geometry (aka removing them from C by calling Apply()). - line 5: the first transient filter declaration which is assigned the id value #1 (via a call to ApplyTransient()). - line 6: Adds a new transient filter declaration to the sequence (assigned id #2). Note, that it redundantly declares that P₄ is a member of C just as declaration #1 did. This redundancy is fine. In fact, it may be very important (see below). - line 7: We remove declaration #1. Although #1 added both P₄ and P₅ to C, the result of removing this declaration from the sequence is that P₅ is no longer a member of C but P₄ is. This is because #2’s declaration that P₄ is* in C preserves its membership. - line 8: the current configuration is “flattened” into the persistent base. All history is thrown out and any filter identifiers are rendered invalid.
This example workflow above illustrates some key ideas in using transient declarations.
**The persistent configuration can only be modified when there is no
transient history.** Applying a filter declaration should have the effect of realizing that declaration. If a pair is declared to be in C, the result of the declaration is that the pair is in C (assuming that the pair can* be in C). If we allowed modifying the persistent configuration with an active transient history, there might be no discernible change in the resultant configuration state because a subsequent transient declaration may supplant it. This would lead to inscrutable bugs. Therefore, it’s simply not allowed. - When defining a transient declaration, the declaration should include all critical pairs *explicitly*. This includes those pairs that should and should not be in C. Any pair not explicitly accounted for should be one whose filter status is immaterial. It might seems desirable (from an optimization perspective) to examine the current configuration of C and apply the minimum change to put it into a desired state (i.e., if a pair I need filtered is already filtered, I would omit it from the declaration). This approach is fraught with peril. If the current configuration is the result of previous transient declarations, the removal of any of those declarations could invalidate the attempted difference calculation and my declaration would no longer be sufficient to guarantee the set C required. - Anyone at any time can add to the history. Some code can modify C to suit its needs. However, it can also make subsequent calls into code that also modifies C with no guarantees that the called code will undo those changes. Code that modifies collision filters configuration should document that it does so. It should also have a clear protocol for cleaning up its own changes. Finally, code that applies declarations should not take for granted that its transient declarations are necessarily the last declarations in the history.
Making transient filter declarations
There is a custom API for applying a filter declaration as a transient declaration. It returns the id for the transient API (used to remove the declaration from the history sequence).
Attempting to change the persistent configuration when there are active transient declarations in the history will throw an exception.
- __init__(*args, **kwargs)
- Apply(self: pydrake.geometry.CollisionFilterManager, declaration: pydrake.geometry.CollisionFilterDeclaration) None
Applies the given
declaration
to the geometry state managed bythis
instance.The process of applying the collision filter data also validates it. The following polices are implemented during application:
Referencing an invalid id (FrameId or GeometryId): throws.
Declaring a filtered pair that is already filtered: no discernible
change. - Attempts to “allow” collision between a pair that is strictly excluded (e.g., between two anchored geometries) will be ignored.
- Raises
RuntimeError if the declaration references invalid ids or –
there is an active history. –
- ApplyTransient(self: pydrake.geometry.CollisionFilterManager, declaration: pydrake.geometry.CollisionFilterDeclaration) drake::Identifier<drake::geometry::FilterTag>
Applies the declaration as the newest transient modification to the collision filter configuration. The declaration must be considered “valid”, as defined for Apply().
- has_transient_history(self: pydrake.geometry.CollisionFilterManager) bool
Reports if there are any active transient filter declarations.
- IsActive(self: pydrake.geometry.CollisionFilterManager, filter_id: drake::Identifier<drake::geometry::FilterTag>) bool
Reports if the transient collision filter declaration indicated by the given
filter_id
is part of the history.
- RemoveDeclaration(self: pydrake.geometry.CollisionFilterManager, filter_id: drake::Identifier<drake::geometry::FilterTag>) bool
Attempts to remove the transient declaration from the history for the declaration associated with the given
filter_id
.- Parameter
filter_id
: The id of the filter declaration to remove.
- Returns
True
iffis_active(filter_id)
returnsTrue
before calling this method (i.e.,filter_id
refers to an existent filter that has successfully been removed).
- Parameter
- class pydrake.geometry.ColorRenderCamera
Collection of camera properties for cameras to be used with color/label images.
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.ColorRenderCamera, other: pydrake.geometry.ColorRenderCamera) -> None
Copy constructor
__init__(self: pydrake.geometry.ColorRenderCamera, core: drake::geometry::render::RenderCameraCore, show_window: bool = False) -> None
Fully-specified constructor. See the documentation on the member getter methods for documentation of parameters.
- core(self: pydrake.geometry.ColorRenderCamera) drake::geometry::render::RenderCameraCore
This camera’s core render properties.
- show_window(self: pydrake.geometry.ColorRenderCamera) bool
If true, requests that the RenderEngine display the rendered image.
- class pydrake.geometry.ContactSurface
The ContactSurface characterizes the intersection of two geometries M and N as a contact surface with a scalar field and a vector field, whose purpose is to support the hydroelastic pressure field contact model as described in:
R. Elandt, E. Drumwright, M. Sherman, and A. Ruina. A pressure field model for fast, robust approximation of net contact force and moment between nominally rigid objects. IROS 2019: 8238-8245.
Mathematical Concepts ———————–
In this section, we give motivation for the concept of contact surface from the hydroelastic pressure field contact model. Here the mathematical discussion is coordinate-free (treatment of the topic without reference to any particular coordinate system); however, our implementation heavily relies on coordinate frames. We borrow terminology from differential geometry.
In this section, the mathematical term compact set (a subset of Euclidean space that is closed and bounded) corresponds to the term geometry (or the space occupied by the geometry) in SceneGraph.
We describe the contact surface 𝕊ₘₙ between two intersecting compact subsets 𝕄 and ℕ of ℝ³ with the scalar fields eₘ and eₙ defined on 𝕄 ⊂ ℝ³ and ℕ ⊂ ℝ³ respectively:
eₘ : 𝕄 → ℝ, eₙ : ℕ → ℝ.
The contact surface 𝕊ₘₙ is the surface of equilibrium eₘ = eₙ. It is the locus of points Q where eₘ(Q) equals eₙ(Q):
𝕊ₘₙ = { Q ∈ 𝕄 ∩ ℕ : eₘ(Q) = eₙ(Q) }.
We can define the scalar field eₘₙ on the surface 𝕊ₘₙ as a scalar function that assigns Q ∈ 𝕊ₘₙ the value of eₘ(Q), which is the same as eₙ(Q):
eₘₙ : 𝕊ₘₙ → ℝ, eₘₙ(Q) = eₘ(Q) = eₙ(Q).
We can also define the scalar field hₘₙ on 𝕄 ∩ ℕ as the difference between eₘ and eₙ:
hₘₙ : 𝕄 ∩ ℕ → ℝ, hₘₙ(Q) = eₘ(Q) - eₙ(Q).
It follows that the gradient vector field ∇hₘₙ on 𝕄 ∩ ℕ equals the difference between the gradient vector fields ∇eₘ and ∇eₙ:
∇hₘₙ : 𝕄 ∩ ℕ → ℝ³, ∇hₘₙ(Q) = ∇eₘ(Q) - ∇eₙ(Q).
By construction, Q ∈ 𝕊ₘₙ if and only if hₘₙ(Q) = 0. In other words, 𝕊ₘₙ is the zero level set of hₘₙ. It follows that, for Q ∈ 𝕊ₘₙ, ∇hₘₙ(Q) is orthogonal to the surface 𝕊ₘₙ at Q in the direction of increasing eₘ - eₙ.
Notice that the domain of eₘₙ is the two-dimensional surface 𝕊ₘₙ, while the domain of ∇hₘₙ is the three-dimensional compact set 𝕄 ∩ ℕ. Even though eₘₙ and ∇hₘₙ are defined on different domains (𝕊ₘₙ and 𝕄 ∩ ℕ), our implementation only represents them on their common domain, i.e., 𝕊ₘₙ.
Discrete Representation ————————-
In practice, hydroelastic geometries themselves have a discrete representation: either a triangular surface mesh for rigid geometries or a tetrahedral volume mesh for compliant geometry. This discretization leads to contact surfaces that are likewise discrete.
Intersection between triangles and tetrahedra (or tetrahedra and tetrahedra) can produce polygons with up to eight sides. A ContactSurface can represent the resulting surface as a mesh of such polygons, or as a mesh of tessellated triangles. The domains of the two representations are identical. The triangular version admits for simple, high-order integration over the domain. Every element is a triangle, and triangles will only disappear and reappear as their areas go to zero. However, this increases the total number of faces in the mesh by more than a factor of three over the polygonal mesh. The polygonal representation produces fewer faces, but high order integration over polygons is problematic. We recommend choosing the cheapest representation that nevertheless supports your required fidelity (see QueryObject::ComputeContactSurfaces()).
The representation of any ContactSurface instance can be reported by calling representation(). If it returns HydroelasticContactRepresentation::kTriangle, then the mesh and pressure field can be accessed via tri_mesh_W() and tri_e_MN(), respectively. If it returns HydroelasticContactRepresentation::kPolygon, then use poly_mesh_W() and poly_e_MN().
Regardless of representation (polygon or triangle), the normal for each mesh face is guaranteed to point “out of” N and “into” M. They can be accessed via the mesh, e.g.,
tri_mesh_W().face_normal(face_index)
. By definition, the normals of the mesh are discontinuous at triangle boundaries.The pressure values on the contact surface are represented as a continuous, piecewise-linear function, accessed via tri_e_MN() or poly_e_MN().
When available, the values of ∇eₘ and ∇eₙ are represented as a discontinuous, piecewise-constant function over the faces – one gradient vector per face. These quantities are accessed via EvaluateGradE_M_W() and EvaluateGradE_N_W(), respectively.
Barycentric Coordinates ————————-
For Point Q on the surface mesh of the contact surface between Geometry M and Geometry N, r_WQ = (x,y,z) is the displacement vector from the origin of the world frame to Q expressed in the coordinate frame of W. We also have the barycentric coordinates (b0, b1, b2) on a triangle of the surface mesh that contains Q. With vertices of the triangle labeled as v₀, v₁, v₂, we can map (b0, b1, b2) to r_WQ by:
r_WQ = b0 * r_Wv₀ + b1 * r_Wv₁ + b2 * r_Wv₂, b0 + b1 + b2 = 1, bᵢ ∈ [0,1],
where r_Wvᵢ is the displacement vector of the vertex labeled as vᵢ from the origin of the world frame, expressed in the world frame.
We use the barycentric coordinates to evaluate the field values.
Note
This class is templated; see
ContactSurface_
for the list of instantiations.- __init__(*args, **kwargs)
- area(self: pydrake.geometry.ContactSurface, face_index: int) float
- centroid(*args, **kwargs)
Overloaded function.
centroid(self: pydrake.geometry.ContactSurface, face_index: int) -> numpy.ndarray[numpy.float64[3, 1]]
centroid(self: pydrake.geometry.ContactSurface) -> numpy.ndarray[numpy.float64[3, 1]]
- Equal(self: pydrake.geometry.ContactSurface, surface: pydrake.geometry.ContactSurface) bool
Checks to see whether the given ContactSurface object is equal via deep exact comparison. NaNs are treated as not equal as per the IEEE standard.
- Parameter
surface
: The contact surface for comparison.
- Returns
True
if the given contact surface is equal.
- Parameter
- EvaluateGradE_M_W(self: pydrake.geometry.ContactSurface, index: int) numpy.ndarray[numpy.float64[3, 1]]
Returns the value of ∇eₘ for the face with index
index
.- Raises
RuntimeError if HasGradE_M() returns false. –
- Precondition:
index ∈ [0, mesh().num_faces())
.
- EvaluateGradE_N_W(self: pydrake.geometry.ContactSurface, index: int) numpy.ndarray[numpy.float64[3, 1]]
Returns the value of ∇eₙ for the face with index
index
.- Raises
RuntimeError if HasGradE_N() returns false. –
- Precondition:
index ∈ [0, mesh().num_faces())
.
- face_normal(self: pydrake.geometry.ContactSurface, face_index: int) numpy.ndarray[numpy.float64[3, 1]]
- HasGradE_M(self: pydrake.geometry.ContactSurface) bool
- Returns
True
ifthis
contains values for ∇eₘ.
- HasGradE_N(self: pydrake.geometry.ContactSurface) bool
- Returns
True
ifthis
contains values for ∇eₙ.
- id_M(self: pydrake.geometry.ContactSurface) pydrake.geometry.GeometryId
Returns the geometry id of Geometry M.
- id_N(self: pydrake.geometry.ContactSurface) pydrake.geometry.GeometryId
Returns the geometry id of Geometry N.
- is_triangle(self: pydrake.geometry.ContactSurface) bool
Simply reports if this contact surface’s mesh representation is triangle. Equivalent to:
representation() == HydroelasticContactRepresentation::kTriangle
and offered as convenient sugar.
- num_faces(self: pydrake.geometry.ContactSurface) int
- num_vertices(self: pydrake.geometry.ContactSurface) int
- poly_e_MN(self: pydrake.geometry.ContactSurface) pydrake.geometry.PolygonSurfaceMeshFieldLinear
Returns a reference to the scalar field eₘₙ for the polygonal mesh.
- Precondition:
is_triangle()
returnsFalse
.
- poly_mesh_W(self: pydrake.geometry.ContactSurface) pydrake.geometry.PolygonSurfaceMesh
Returns a reference to the polygonal surface mesh whose vertex positions are measured and expressed in the world frame.
- Precondition:
is_triangle()
returnsFalse
.
- representation(self: pydrake.geometry.ContactSurface) pydrake.geometry.HydroelasticContactRepresentation
Reports the representation mode of this contact surface. If accessing the mesh or field directly, the APIs that can be successfully exercised are related to this methods return value. See below.
- total_area(self: pydrake.geometry.ContactSurface) float
- tri_e_MN(self: pydrake.geometry.ContactSurface) pydrake.geometry.TriangleSurfaceMeshFieldLinear
Returns a reference to the scalar field eₘₙ for the triangle mesh.
- Precondition:
is_triangle()
returnsTrue
.
- tri_mesh_W(self: pydrake.geometry.ContactSurface) pydrake.geometry.TriangleSurfaceMesh
Returns a reference to the triangular surface mesh whose vertex positions are measured and expressed in the world frame.
- Precondition:
is_triangle()
returnsTrue
.
- template pydrake.geometry.ContactSurface_
Instantiations:
ContactSurface_[float]
,ContactSurface_[AutoDiffXd]
- class pydrake.geometry.ContactSurface_[AutoDiffXd]
The ContactSurface characterizes the intersection of two geometries M and N as a contact surface with a scalar field and a vector field, whose purpose is to support the hydroelastic pressure field contact model as described in:
R. Elandt, E. Drumwright, M. Sherman, and A. Ruina. A pressure field model for fast, robust approximation of net contact force and moment between nominally rigid objects. IROS 2019: 8238-8245.
Mathematical Concepts ———————–
In this section, we give motivation for the concept of contact surface from the hydroelastic pressure field contact model. Here the mathematical discussion is coordinate-free (treatment of the topic without reference to any particular coordinate system); however, our implementation heavily relies on coordinate frames. We borrow terminology from differential geometry.
In this section, the mathematical term compact set (a subset of Euclidean space that is closed and bounded) corresponds to the term geometry (or the space occupied by the geometry) in SceneGraph.
We describe the contact surface 𝕊ₘₙ between two intersecting compact subsets 𝕄 and ℕ of ℝ³ with the scalar fields eₘ and eₙ defined on 𝕄 ⊂ ℝ³ and ℕ ⊂ ℝ³ respectively:
eₘ : 𝕄 → ℝ, eₙ : ℕ → ℝ.
The contact surface 𝕊ₘₙ is the surface of equilibrium eₘ = eₙ. It is the locus of points Q where eₘ(Q) equals eₙ(Q):
𝕊ₘₙ = { Q ∈ 𝕄 ∩ ℕ : eₘ(Q) = eₙ(Q) }.
We can define the scalar field eₘₙ on the surface 𝕊ₘₙ as a scalar function that assigns Q ∈ 𝕊ₘₙ the value of eₘ(Q), which is the same as eₙ(Q):
eₘₙ : 𝕊ₘₙ → ℝ, eₘₙ(Q) = eₘ(Q) = eₙ(Q).
We can also define the scalar field hₘₙ on 𝕄 ∩ ℕ as the difference between eₘ and eₙ:
hₘₙ : 𝕄 ∩ ℕ → ℝ, hₘₙ(Q) = eₘ(Q) - eₙ(Q).
It follows that the gradient vector field ∇hₘₙ on 𝕄 ∩ ℕ equals the difference between the gradient vector fields ∇eₘ and ∇eₙ:
∇hₘₙ : 𝕄 ∩ ℕ → ℝ³, ∇hₘₙ(Q) = ∇eₘ(Q) - ∇eₙ(Q).
By construction, Q ∈ 𝕊ₘₙ if and only if hₘₙ(Q) = 0. In other words, 𝕊ₘₙ is the zero level set of hₘₙ. It follows that, for Q ∈ 𝕊ₘₙ, ∇hₘₙ(Q) is orthogonal to the surface 𝕊ₘₙ at Q in the direction of increasing eₘ - eₙ.
Notice that the domain of eₘₙ is the two-dimensional surface 𝕊ₘₙ, while the domain of ∇hₘₙ is the three-dimensional compact set 𝕄 ∩ ℕ. Even though eₘₙ and ∇hₘₙ are defined on different domains (𝕊ₘₙ and 𝕄 ∩ ℕ), our implementation only represents them on their common domain, i.e., 𝕊ₘₙ.
Discrete Representation ————————-
In practice, hydroelastic geometries themselves have a discrete representation: either a triangular surface mesh for rigid geometries or a tetrahedral volume mesh for compliant geometry. This discretization leads to contact surfaces that are likewise discrete.
Intersection between triangles and tetrahedra (or tetrahedra and tetrahedra) can produce polygons with up to eight sides. A ContactSurface can represent the resulting surface as a mesh of such polygons, or as a mesh of tessellated triangles. The domains of the two representations are identical. The triangular version admits for simple, high-order integration over the domain. Every element is a triangle, and triangles will only disappear and reappear as their areas go to zero. However, this increases the total number of faces in the mesh by more than a factor of three over the polygonal mesh. The polygonal representation produces fewer faces, but high order integration over polygons is problematic. We recommend choosing the cheapest representation that nevertheless supports your required fidelity (see QueryObject::ComputeContactSurfaces()).
The representation of any ContactSurface instance can be reported by calling representation(). If it returns HydroelasticContactRepresentation::kTriangle, then the mesh and pressure field can be accessed via tri_mesh_W() and tri_e_MN(), respectively. If it returns HydroelasticContactRepresentation::kPolygon, then use poly_mesh_W() and poly_e_MN().
Regardless of representation (polygon or triangle), the normal for each mesh face is guaranteed to point “out of” N and “into” M. They can be accessed via the mesh, e.g.,
tri_mesh_W().face_normal(face_index)
. By definition, the normals of the mesh are discontinuous at triangle boundaries.The pressure values on the contact surface are represented as a continuous, piecewise-linear function, accessed via tri_e_MN() or poly_e_MN().
When available, the values of ∇eₘ and ∇eₙ are represented as a discontinuous, piecewise-constant function over the faces – one gradient vector per face. These quantities are accessed via EvaluateGradE_M_W() and EvaluateGradE_N_W(), respectively.
Barycentric Coordinates ————————-
For Point Q on the surface mesh of the contact surface between Geometry M and Geometry N, r_WQ = (x,y,z) is the displacement vector from the origin of the world frame to Q expressed in the coordinate frame of W. We also have the barycentric coordinates (b0, b1, b2) on a triangle of the surface mesh that contains Q. With vertices of the triangle labeled as v₀, v₁, v₂, we can map (b0, b1, b2) to r_WQ by:
r_WQ = b0 * r_Wv₀ + b1 * r_Wv₁ + b2 * r_Wv₂, b0 + b1 + b2 = 1, bᵢ ∈ [0,1],
where r_Wvᵢ is the displacement vector of the vertex labeled as vᵢ from the origin of the world frame, expressed in the world frame.
We use the barycentric coordinates to evaluate the field values.
- __init__(*args, **kwargs)
- area(self: pydrake.geometry.ContactSurface_[AutoDiffXd], face_index: int) pydrake.autodiffutils.AutoDiffXd
- centroid(*args, **kwargs)
Overloaded function.
centroid(self: pydrake.geometry.ContactSurface_[AutoDiffXd], face_index: int) -> numpy.ndarray[object[3, 1]]
centroid(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) -> numpy.ndarray[object[3, 1]]
- Equal(self: pydrake.geometry.ContactSurface_[AutoDiffXd], surface: pydrake.geometry.ContactSurface_[AutoDiffXd]) bool
Checks to see whether the given ContactSurface object is equal via deep exact comparison. NaNs are treated as not equal as per the IEEE standard.
- Parameter
surface
: The contact surface for comparison.
- Returns
True
if the given contact surface is equal.
- Parameter
- EvaluateGradE_M_W(self: pydrake.geometry.ContactSurface_[AutoDiffXd], index: int) numpy.ndarray[object[3, 1]]
Returns the value of ∇eₘ for the face with index
index
.- Raises
RuntimeError if HasGradE_M() returns false. –
- Precondition:
index ∈ [0, mesh().num_faces())
.
- EvaluateGradE_N_W(self: pydrake.geometry.ContactSurface_[AutoDiffXd], index: int) numpy.ndarray[object[3, 1]]
Returns the value of ∇eₙ for the face with index
index
.- Raises
RuntimeError if HasGradE_N() returns false. –
- Precondition:
index ∈ [0, mesh().num_faces())
.
- face_normal(self: pydrake.geometry.ContactSurface_[AutoDiffXd], face_index: int) numpy.ndarray[object[3, 1]]
- HasGradE_M(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) bool
- Returns
True
ifthis
contains values for ∇eₘ.
- HasGradE_N(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) bool
- Returns
True
ifthis
contains values for ∇eₙ.
- id_M(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.geometry.GeometryId
Returns the geometry id of Geometry M.
- id_N(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.geometry.GeometryId
Returns the geometry id of Geometry N.
- is_triangle(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) bool
Simply reports if this contact surface’s mesh representation is triangle. Equivalent to:
representation() == HydroelasticContactRepresentation::kTriangle
and offered as convenient sugar.
- num_faces(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) int
- num_vertices(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) int
- poly_e_MN(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.geometry.PolygonSurfaceMeshFieldLinear_[AutoDiffXd, AutoDiffXd]
Returns a reference to the scalar field eₘₙ for the polygonal mesh.
- Precondition:
is_triangle()
returnsFalse
.
- poly_mesh_W(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]
Returns a reference to the polygonal surface mesh whose vertex positions are measured and expressed in the world frame.
- Precondition:
is_triangle()
returnsFalse
.
- representation(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.geometry.HydroelasticContactRepresentation
Reports the representation mode of this contact surface. If accessing the mesh or field directly, the APIs that can be successfully exercised are related to this methods return value. See below.
- total_area(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.autodiffutils.AutoDiffXd
- tri_e_MN(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.geometry.TriangleSurfaceMeshFieldLinear_[AutoDiffXd, AutoDiffXd]
Returns a reference to the scalar field eₘₙ for the triangle mesh.
- Precondition:
is_triangle()
returnsTrue
.
- tri_mesh_W(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) pydrake.geometry.TriangleSurfaceMesh_[AutoDiffXd]
Returns a reference to the triangular surface mesh whose vertex positions are measured and expressed in the world frame.
- Precondition:
is_triangle()
returnsTrue
.
- pydrake.geometry.ConvertVolumeToSurfaceMesh(*args, **kwargs)
Overloaded function.
ConvertVolumeToSurfaceMesh(volume: pydrake.geometry.VolumeMesh) -> pydrake.geometry.TriangleSurfaceMesh
Converts a tetrahedral volume mesh to a triangulated surface mesh of the boundary surface of the volume.
- Parameter
volume
: The tetrahedral volume mesh, whose vertex positions are measured and expressed in some frame E.
- Returns
The triangulated surface mesh, whose vertex positions are measured and expressed in the same frame E of the volume mesh.
- Precondition:
The vertices of the volume mesh are unique. Adjacent tetrahedra share the same vertices, instead of repeating the vertices with the same coordinates. Otherwise, the returned surface mesh will have extra triangles in addition to the boundary triangles of the volume.
ConvertVolumeToSurfaceMesh(volume: pydrake.geometry.VolumeMesh_[AutoDiffXd]) -> pydrake.geometry.TriangleSurfaceMesh_[AutoDiffXd]
Converts a tetrahedral volume mesh to a triangulated surface mesh of the boundary surface of the volume.
- Parameter
volume
: The tetrahedral volume mesh, whose vertex positions are measured and expressed in some frame E.
- Returns
The triangulated surface mesh, whose vertex positions are measured and expressed in the same frame E of the volume mesh.
- Precondition:
The vertices of the volume mesh are unique. Adjacent tetrahedra share the same vertices, instead of repeating the vertices with the same coordinates. Otherwise, the returned surface mesh will have extra triangles in addition to the boundary triangles of the volume.
- class pydrake.geometry.Convex
Bases:
pydrake.geometry.Shape
Definition of a convex surface mesh.
This shape is not the mesh contained in the file named by
filename
. It is the convex hull of that mesh. As such, the only contents of the mesh file that matter are the vertex positions. All other data is ignored. This includes materials, textures, normals etc. This is true for all roles. Its appearance in an illustration or perception role, will be a faceted polytope whose color is defined by its assigned properties (or by the geometry consumer’s defaults).Because Drake computes the convex hull, the named mesh file need not be convex.
The mesh is defined in a canonical frame C, implicit in the file parsed. Upon loading it in SceneGraph it can be scaled around the origin of C by a given
scale
amount.- __init__(self: pydrake.geometry.Convex, filename: str, scale: float = 1.0) None
Constructs a convex shape specification from the file located at the given file path. Optionally uniformly scaled by the given scale factor.
The mesh file referenced can be an .obj, .gltf, or a tetrahedral .vtk.
- Parameter
filename
: The file name; if it is not absolute, it will be interpreted relative to the current working directory.
- Parameter
scale
: An optional scale to coordinates.
- Raises
RuntimeError if scale < 1e-8. Note that a negative scale is –
considered valid. We want to preclude scales near zero but –
recognise that scale is a convenience tool for "tweaking" models. –
8 orders of magnitude should be plenty without considering –
revisiting the model itself. –
- Parameter
- extension(self: pydrake.geometry.Convex) str
Returns the extension of the mesh filename – all lower case and including the dot. In other words /foo/bar/mesh.obj and /foo/bar/mesh.OBJ would both report the “.obj” extension. The “extension” portion of the filename is defined as in std::filesystem::path::extension().
- filename(self: pydrake.geometry.Convex) str
- GetConvexHull(self: pydrake.geometry.Convex) pydrake.geometry.PolygonSurfaceMesh
Reports the convex hull of the named mesh.
Note: the convex hull is computed on demand on the first invocation. All subsequent invocations should have an O(1) cost.
- Raises
if the referenced mesh data cannot be read or is degenerate –
(insufficient number of vertices, co-linear or coincident –
vertices, etc.) All of the vertices lying on a plane is not –
considered degenerate. –
- scale(self: pydrake.geometry.Convex) float
- class pydrake.geometry.Cylinder
Bases:
pydrake.geometry.Shape
Definition of a cylinder. It is centered in its canonical frame with the length of the cylinder parallel with the frame’s z-axis.
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.Cylinder, radius: float, length: float) -> None
Constructs a cylinder with the given
radius
andlength
.- Raises
RuntimeError if radius or length are not strictly –
positive. –
__init__(self: pydrake.geometry.Cylinder, measures: numpy.ndarray[numpy.float64[2, 1]]) -> None
Constructs a cylinder with a vector of measures: radius and length.
- Raises
RuntimeError if the measures are not strictly positive. –
- length(self: pydrake.geometry.Cylinder) float
- radius(self: pydrake.geometry.Cylinder) float
- class pydrake.geometry.DefaultProximityProperties
These properties will be used as defaults when the geometry as added via API calls or parsed from model files doesn’t say anything more specific.
See also
compliant_contact, hydroelastic_user_guide, friction_model and subsections therein.
- __init__(self: pydrake.geometry.DefaultProximityProperties, **kwargs) None
- property compliance_type
@name Hydroelastic Contact Properties
These properties affect hydroelastic contact only. For more detail, including limits of the numeric parameters,
See also
geometry::AddRigidHydroelasticProperties, geometry::AddCompliantHydroelasticProperties, geometry::AddCompliantHydroelasticPropertiesForHalfSpace.
For more context,
See also
hug_properties. There are three valid options for
compliance_type
: - “undefined”: hydroelastic contact will not be used. - “rigid”: the default hydroelastic compliance type will be rigid; note that rigid-rigid contact is not supported by the hydroelastic contact model, but is supported by point contact (multibody::ContactModel::kPoint or multibody::ContactModel::kHydroelasticWithFallback). - “compliant”: the default hydroelastic compliance type will be compliant.
- property dynamic_friction
@name General Contact Properties
These properties affect contact in general. For more detail, including limits of the numeric parameters,
See also
geometry::AddContactMaterial, multibody::CoulombFriction, mbp_contact_modeling, mbp_dissipation_model. To be valid, either both friction values must be populated, or neither. Friction quantities are unitless.
- property hunt_crossley_dissipation
Controls energy damping from contact, for contact models other than multibody::DiscreteContactApproximation::kSap. Units are seconds per meter.
- property hydroelastic_modulus
A measure of material stiffness, in units of Pascals.
- property point_stiffness
@name Point Contact Properties
These properties affect point contact only. For complete descriptions of the numeric parameters, See point_forces_modeling “Compliant Point Contact Forces”, geometry::AddContactMaterial. A measure of material stiffness, in units of Newtons per meter.
- property relaxation_time
Controls energy damping from contact, only for multibody::DiscreteContactApproximation::kSap. Units are seconds.
- property resolution_hint
Controls how finely primitive geometries are tessellated, units of meters.
While no single value is universally appropriate, this value was selected based on the following idea. We’re attempting to make introducing novel manipulands as easy as possible. Considering a simple soup can as a representative manipuland, we’ve picked a value that would result in a tessellated cylinder with enough faces to be appropriate for contact with a compliant gripper.
- property slab_thickness
For a halfspace, the thickness of compliant material to model, in units of meters.
- property static_friction
See also: dynamic_friction.
- class pydrake.geometry.DepthRange
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.DepthRange, other: pydrake.geometry.DepthRange) -> None
Copy constructor
__init__(self: pydrake.geometry.DepthRange, min_in: float, min_out: float) -> None
Constructs the DepthRange.
- Raises
RuntimeError if either value isn't finite and positive, or if –
min_in >= max_in` –
- max_depth(self: pydrake.geometry.DepthRange) float
- min_depth(self: pydrake.geometry.DepthRange) float
- class pydrake.geometry.DepthRenderCamera
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.DepthRenderCamera, other: pydrake.geometry.DepthRenderCamera) -> None
Copy constructor
__init__(self: pydrake.geometry.DepthRenderCamera, core: drake::geometry::render::RenderCameraCore, depth_range: pydrake.geometry.DepthRange) -> None
Fully-specified constructor. See the documentation on the member getter methods for documentation of parameters.
- Raises
RuntimeError if the depth_range is not fully contained within the –
clipping range. –
- core(self: pydrake.geometry.DepthRenderCamera) drake::geometry::render::RenderCameraCore
This camera’s core render properties.
- depth_range(self: pydrake.geometry.DepthRenderCamera) pydrake.geometry.DepthRange
The range of valid values for the depth camera.
- class pydrake.geometry.DrakeVisualizer
Bases:
pydrake.systems.framework.LeafSystem
A system that publishes LCM messages representing the current state of a SceneGraph instance (whose QueryObject-valued output port is connected to this system’s input port).
The messages are compatible with Meldis.
query_object→ DrakeVisualizer The DrakeVisualizer system broadcasts three kinds of LCM messages:
a message that defines the non-deformable geometries in the world on the
lcm channel named “DRAKE_VIEWER_LOAD_ROBOT” - a message that updates the poses of those non-deformable geometries on the lcm channel named “DRAKE_VIEWER_DRAW”, - a message that sets the world space vertex positions of the deformable geometries on the lcm channel named “DRAKE_VIEWER_DEFORMABLE”
If requested in DrakeVisualizerParams, the above channel names are modified according to the role specified. This allows simultaneous availability of geometry from multiple roles, by using multiple DrakeVisualizer instances.
kIllustration: channel names gain a “_ILLUSTRATION” suffix.
kProximity: channel names gain a “_PROXIMITY” suffix.
kPerception: channel names gain a “_PERCEPTION” suffix.
The system uses the versioning mechanism provided by SceneGraph to detect changes to the geometry so that a change in SceneGraph’s data will propagate to the message receiver.
Visualization by Role
By default, DrakeVisualizer visualizes geometries with the illustration role (see geometry_roles for more details). It can be configured to visualize geometries with other roles (see DrakeVisualizerParams). Only one role can be specified.
The appearance of the geometry in the visualizer is typically defined by the geometry’s properties for the visualized role.
For the visualized role, if a geometry has the (“phong”, “diffuse”)
property described in the table below, that value is used. - Otherwise, if the geometry also has the illustration properties, those properties are likewise tested for the (“phong”, “diffuse”) property. This rule only has significance is the visualized role is not the illustration role. - Otherwise, the configured default color will be applied (see DrakeVisualizerParams).
Group name | Required | Property Name | Property Type | PropertyDescription | | :——–: | :——: | :———–: | :————-: | :——————- | | phong | no | diffuse | Rgba | The rgba value of the object surface. |
Appearance of OBJ files for non-deformable geometries
Meshes represented by OBJ are special. The OBJ file can reference a material file (.mtl). If the mtl file is found by the receiving application, values in the .mtl will take precedence over the (“phong”, “diffuse”) geometry property.
It’s worth emphasizing that these rules permits control over the appearance of collision geometry on a per-geometry basis by assigning an explicit Rgba value to the (“phong”, “diffuse”) property in the geometry’s ProximityProperties.
Note
If collision geometries are added to SceneGraph by parsing URDF/SDF files, they will not have diffuse values. Even if elements were added to the specification files, they would not be parsed. They must be added to the geometries after parsing.
Effective visualization
The best visualization is when draw messages have been preceded by a compatible load message (i.e., a “coherent” message sequence). While LCM doesn’t guarantee that messages will be received/processed in the same order as they are broadcast, your results will be best if DrakeVisualizer is allowed to broadcast coherent messages. Practices that interfere with that will likely produce undesirable results. E.g.,
Evaluating a single instance of DrakeVisualizer across several threads,
such that the data in the per-thread systems::Context varies. - Evaluating multiple instances of DrakeVisualizer in a single thread that share the same lcm::DrakeLcmInterface.
Mesh support
DrakeVisualizer is mesh file format agnostic. A Mesh or Convex shape that references arbitrary mesh files will simply be packaged in the broadcast LCM message. It defers to the message receiver on whether that particular file format is supported.
Scalar support and conversion
DrakeVisualizer is templated on
T
and can be used in adouble
- or AutoDiffXd-valued Diagram. However, the diagram can only be converted from one scalar type to another if the DrakeVisualizer owns its lcm::DrakeLcmInterface instance. Attempts to scalar convert the system otherwise will throw an exception.Note
This class is templated; see
DrakeVisualizer_
for the list of instantiations.- __init__(self: pydrake.geometry.DrakeVisualizer, lcm: pydrake.lcm.DrakeLcmInterface = None, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) None
Creates an instance of DrakeVisualizer.
- Parameter
lcm
: An optional LCM interface. If none is provided, this system will allocate its own instance. If one is provided it must remain valid for the lifetime of this object.
- Parameter
params
: The set of parameters to control this system’s behavior.
- Raises
RuntimeError if params.publish_period <= 0. –
RuntimeError if params.role == Role::kUnassigned. –
- Parameter
- static AddToBuilder(*args, **kwargs)
Overloaded function.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder, scene_graph: pydrake.geometry.SceneGraph, lcm: pydrake.lcm.DrakeLcmInterface = None, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) -> pydrake.geometry.DrakeVisualizer
Connects the newly added DrakeVisualizer to the given SceneGraph’s QueryObject-valued output port. The DrakeVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder, query_object_port: pydrake.systems.framework.OutputPort, lcm: pydrake.lcm.DrakeLcmInterface = None, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) -> pydrake.geometry.DrakeVisualizer
Connects the newly added DrakeVisualizer to the given QueryObject-valued output port. The DrakeVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
- static DispatchLoadMessage(scene_graph: pydrake.geometry.SceneGraph, lcm: pydrake.lcm.DrakeLcmInterface, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) None
(Advanced) Dispatches a load message built on the model geometry for the given SceneGraph instance. This should be used sparingly. When we have a starightforward method for binding lcmtypes in python, this will be replaced with an API that will simply generate the lcm messages that the caller can then do whatever they like with.
- Precondition:
lcm != nullptr
.
- query_object_input_port(self: pydrake.geometry.DrakeVisualizer) pydrake.systems.framework.InputPort
Returns the QueryObject-valued input port. It should be connected to SceneGraph’s QueryObject-valued output port. Failure to do so will cause a runtime error when attempting to broadcast messages.
- template pydrake.geometry.DrakeVisualizer_
Instantiations:
DrakeVisualizer_[float]
,DrakeVisualizer_[AutoDiffXd]
- class pydrake.geometry.DrakeVisualizer_[AutoDiffXd]
Bases:
pydrake.systems.framework.LeafSystem_[AutoDiffXd]
A system that publishes LCM messages representing the current state of a SceneGraph instance (whose QueryObject-valued output port is connected to this system’s input port).
The messages are compatible with Meldis.
query_object→ DrakeVisualizer The DrakeVisualizer system broadcasts three kinds of LCM messages:
a message that defines the non-deformable geometries in the world on the
lcm channel named “DRAKE_VIEWER_LOAD_ROBOT” - a message that updates the poses of those non-deformable geometries on the lcm channel named “DRAKE_VIEWER_DRAW”, - a message that sets the world space vertex positions of the deformable geometries on the lcm channel named “DRAKE_VIEWER_DEFORMABLE”
If requested in DrakeVisualizerParams, the above channel names are modified according to the role specified. This allows simultaneous availability of geometry from multiple roles, by using multiple DrakeVisualizer instances.
kIllustration: channel names gain a “_ILLUSTRATION” suffix.
kProximity: channel names gain a “_PROXIMITY” suffix.
kPerception: channel names gain a “_PERCEPTION” suffix.
The system uses the versioning mechanism provided by SceneGraph to detect changes to the geometry so that a change in SceneGraph’s data will propagate to the message receiver.
Visualization by Role
By default, DrakeVisualizer visualizes geometries with the illustration role (see geometry_roles for more details). It can be configured to visualize geometries with other roles (see DrakeVisualizerParams). Only one role can be specified.
The appearance of the geometry in the visualizer is typically defined by the geometry’s properties for the visualized role.
For the visualized role, if a geometry has the (“phong”, “diffuse”)
property described in the table below, that value is used. - Otherwise, if the geometry also has the illustration properties, those properties are likewise tested for the (“phong”, “diffuse”) property. This rule only has significance is the visualized role is not the illustration role. - Otherwise, the configured default color will be applied (see DrakeVisualizerParams).
Group name | Required | Property Name | Property Type | PropertyDescription | | :——–: | :——: | :———–: | :————-: | :——————- | | phong | no | diffuse | Rgba | The rgba value of the object surface. |
Appearance of OBJ files for non-deformable geometries
Meshes represented by OBJ are special. The OBJ file can reference a material file (.mtl). If the mtl file is found by the receiving application, values in the .mtl will take precedence over the (“phong”, “diffuse”) geometry property.
It’s worth emphasizing that these rules permits control over the appearance of collision geometry on a per-geometry basis by assigning an explicit Rgba value to the (“phong”, “diffuse”) property in the geometry’s ProximityProperties.
Note
If collision geometries are added to SceneGraph by parsing URDF/SDF files, they will not have diffuse values. Even if elements were added to the specification files, they would not be parsed. They must be added to the geometries after parsing.
Effective visualization
The best visualization is when draw messages have been preceded by a compatible load message (i.e., a “coherent” message sequence). While LCM doesn’t guarantee that messages will be received/processed in the same order as they are broadcast, your results will be best if DrakeVisualizer is allowed to broadcast coherent messages. Practices that interfere with that will likely produce undesirable results. E.g.,
Evaluating a single instance of DrakeVisualizer across several threads,
such that the data in the per-thread systems::Context varies. - Evaluating multiple instances of DrakeVisualizer in a single thread that share the same lcm::DrakeLcmInterface.
Mesh support
DrakeVisualizer is mesh file format agnostic. A Mesh or Convex shape that references arbitrary mesh files will simply be packaged in the broadcast LCM message. It defers to the message receiver on whether that particular file format is supported.
Scalar support and conversion
DrakeVisualizer is templated on
T
and can be used in adouble
- or AutoDiffXd-valued Diagram. However, the diagram can only be converted from one scalar type to another if the DrakeVisualizer owns its lcm::DrakeLcmInterface instance. Attempts to scalar convert the system otherwise will throw an exception.- __init__(self: pydrake.geometry.DrakeVisualizer_[AutoDiffXd], lcm: pydrake.lcm.DrakeLcmInterface = None, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) None
Creates an instance of DrakeVisualizer.
- Parameter
lcm
: An optional LCM interface. If none is provided, this system will allocate its own instance. If one is provided it must remain valid for the lifetime of this object.
- Parameter
params
: The set of parameters to control this system’s behavior.
- Raises
RuntimeError if params.publish_period <= 0. –
RuntimeError if params.role == Role::kUnassigned. –
- Parameter
- static AddToBuilder(*args, **kwargs)
Overloaded function.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], scene_graph: pydrake.geometry.SceneGraph_[AutoDiffXd], lcm: pydrake.lcm.DrakeLcmInterface = None, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) -> pydrake.geometry.DrakeVisualizer_[AutoDiffXd]
Connects the newly added DrakeVisualizer to the given SceneGraph’s QueryObject-valued output port. The DrakeVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], query_object_port: pydrake.systems.framework.OutputPort_[AutoDiffXd], lcm: pydrake.lcm.DrakeLcmInterface = None, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) -> pydrake.geometry.DrakeVisualizer_[AutoDiffXd]
Connects the newly added DrakeVisualizer to the given QueryObject-valued output port. The DrakeVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
- static DispatchLoadMessage(scene_graph: pydrake.geometry.SceneGraph_[AutoDiffXd], lcm: pydrake.lcm.DrakeLcmInterface, params: pydrake.geometry.DrakeVisualizerParams = DrakeVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), show_hydroelastic=False, use_role_channel_suffix=False)) None
(Advanced) Dispatches a load message built on the model geometry for the given SceneGraph instance. This should be used sparingly. When we have a starightforward method for binding lcmtypes in python, this will be replaced with an API that will simply generate the lcm messages that the caller can then do whatever they like with.
- Precondition:
lcm != nullptr
.
- query_object_input_port(self: pydrake.geometry.DrakeVisualizer_[AutoDiffXd]) pydrake.systems.framework.InputPort_[AutoDiffXd]
Returns the QueryObject-valued input port. It should be connected to SceneGraph’s QueryObject-valued output port. Failure to do so will cause a runtime error when attempting to broadcast messages.
- class pydrake.geometry.DrakeVisualizerParams
The set of parameters for configuring DrakeVisualizer.
- __init__(self: pydrake.geometry.DrakeVisualizerParams, **kwargs) None
- property default_color
The color to apply to any geometry that hasn’t defined one.
- property publish_period
The duration (in seconds) between published LCM messages that update the poses of the scene’s geometry. (To help avoid small simulation time steps, we use a default period that has an exact representation in binary floating point; see drake#15021 for details.)
- property role
The role of the geometries to be sent to the visualizer.
- property show_hydroelastic
When using the hydroelastic contact model, collision geometries that are declared as geometric primitives are frequently represented by some discretely tessellated mesh when computing contact. It can be quite helpful in assessing contact behavior to visualize these discrete meshes (in place of the idealized primitives).
To visualize these representations it is necessary to request visualization of geometries with the Role::kProximity role (see the role field). It is further necessary to explicitly request the hydroelastic meshes where available (setting show_hydroelastic to
True
).Setting this
show_hydroelastic
toTrue
will have no apparent effect if none of the collision meshes have a hydroelastic mesh associated with them.
- property use_role_channel_suffix
Setting this to
True
will cause LCM channel names to have a suffix appended, allowing simultaneous transmission of multiple geometry roles via multiple DrakeVisualizer instances. See DrakeVisualizer for details.
- class pydrake.geometry.Ellipsoid
Bases:
pydrake.geometry.Shape
Definition of an ellipsoid. It is centered on the origin of its canonical frame with its dimensions aligned with the frame’s axes. The standard equation for the ellipsoid is:
x²/a² + y²/b² + z²/c² = 1,
where a,b,c are the lengths of the principal semi-axes of the ellipsoid. The bounding box of the ellipsoid is [-a,a]x[-b,b]x[-c,c].
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.Ellipsoid, a: float, b: float, c: float) -> None
Constructs an ellipsoid with the given lengths of its principal semi-axes, with a, b, and c measured along the x-, y-, and z- axes of the canonical frame, respectively.
- Raises
RuntimeError if a, b, or c are not strictly positive. –
__init__(self: pydrake.geometry.Ellipsoid, measures: numpy.ndarray[numpy.float64[3, 1]]) -> None
Constructs an ellipsoid with a vector of measures: the lengths of its principal semi-axes, with a, b, and c measured along the x-, y-, and z- axes of the canonical frame, respectively.
- Raises
RuntimeError if the measures are not strictly positive. –
- a(self: pydrake.geometry.Ellipsoid) float
- b(self: pydrake.geometry.Ellipsoid) float
- c(self: pydrake.geometry.Ellipsoid) float
- class pydrake.geometry.EnvironmentMap
- __init__(self: pydrake.geometry.EnvironmentMap, **kwargs) None
- property skybox
- property texture
- class pydrake.geometry.EquirectangularMap
- __init__(self: pydrake.geometry.EquirectangularMap, **kwargs) None
- property path
- class pydrake.geometry.FilterId
Type used to identify transient collision filter declarations in SceneGraph.
- __init__(*args, **kwargs)
- static get_new_id() pydrake.geometry.FilterId
Generates a new identifier for this id type. This new identifier will be different from all previous identifiers created. This method does not make any guarantees about the values of ids from successive invocations. This method is guaranteed to be thread safe.
- get_value(self: pydrake.geometry.FilterId) int
Extracts the underlying representation from the identifier. This is considered invalid for invalid ids and is strictly enforced in Debug builds.
- is_valid(self: pydrake.geometry.FilterId) bool
Reports if the id is valid.
- class pydrake.geometry.FrameId
Type used to identify geometry frames in SceneGraph.
- __init__(*args, **kwargs)
- static get_new_id() pydrake.geometry.FrameId
Generates a new identifier for this id type. This new identifier will be different from all previous identifiers created. This method does not make any guarantees about the values of ids from successive invocations. This method is guaranteed to be thread safe.
- get_value(self: pydrake.geometry.FrameId) int
Extracts the underlying representation from the identifier. This is considered invalid for invalid ids and is strictly enforced in Debug builds.
- is_valid(self: pydrake.geometry.FrameId) bool
Reports if the id is valid.
- class pydrake.geometry.FramePoseVector
A KinematicsVector is a container class used to report kinematics data for registered frames and geometries (keyed by unique FrameId/GeometryId values) to SceneGraph where the set of keys (FrameId/GeometryId) is usually constant and the values (kinematics data) are varying. It is an internal class and one should never interact with it directly. The template aliases FramePoseVector and GeometryConfigurationVector that instantiate KinematicsVector should be used instead.
Click to expand C++ code...
template <typename T> class MySystem : public LeafSystem<T> { public: MySystem() { ... this->DeclareAbstractOutputPort( &AllocInConstructorSystem::CalcFramePoseOutput); ... } private: void CalcFramePoseOutput(const Context<T>& context, geometry::FramePoseVector<T>* poses) const { poses->clear(); for (int i = 0; i < static_cast<int>(frame_ids_.size()); ++i) { poses->set_value(frame_ids_[i], poses_[i]); } } std::vector<FrameId> frame_ids_; std::vector<RigidTransform<T>> poses_; };
If a System only ever emits a single frame/geometry (or small-constant-number of frames/geometries), then there’s a shorter alternative way to write a Calc method, using an initializer_list:
Click to expand C++ code...
void CalcFramePoseOutput(const Context<T>& context, geometry::FramePoseVector<T>* poses) const { const RigidTransform<T>& pose = ...; poses = {{frame_id_, pose}}; }
N.B. When the systems framework calls the
Calc
method, the value pointed to byposes
is in an unspecified state. The implementation ofCalc
must always ensure thatposes
contains the correct value upon return, no matter what value it started with. The easy ways to do this are to call eitherposes->clear()
or the assignment operator*poses = ...
.- Template parameter
Id
: The key used to locate the kinematics data. Can be FrameId or GeometryId.
- Template parameter
KinematicsValue
: The underlying data type of the kinematics data (e.g., pose, configuration, or velocity).
The FramePoseVector and GeometryConfigurationVector classes are aliases of the KinematicsVector instantiated on specific data types (RigidTransform and VectorX respectively). Each of these data types are templated on Eigen scalars. All supported combinations of data type and scalar type are already available to link against in the containing library. No other values for KinematicsValue are supported.
Currently, the following data types with the following scalar types are supported:
Alias | Instantiation | Scalar types ————————————-|--------------------------------------------------|————- FramePoseVector<Scalar> | KinematicsVector<FrameId,RigidTransform<Scalar>> | double/AutoDiffXd/Expression GeometryConfigurationVector<Scalar> | KinematicsVector<GeometryId, VectorX<Scalar>> | double/AutoDiffXd/Expression
Note
This class is templated; see
FramePoseVector_
for the list of instantiations.- __init__(self: pydrake.geometry.FramePoseVector) None
Initializes the vector with no data .
- clear(self: pydrake.geometry.FramePoseVector) None
Clears all values, resetting the size to zero.
- has_id(self: pydrake.geometry.FramePoseVector, id: pydrake.geometry.FrameId) bool
Reports true if the given id is a member of this data.
- ids(self: pydrake.geometry.FramePoseVector) list[pydrake.geometry.FrameId]
Provides a range object for all of the existing ids in the vector. This is intended to be used as:
Click to expand C++ code...
for (Id id : this_vector.ids()) { ... // Obtain the KinematicsValue of an id by `this_vector.value(id)` ... }
- set_value(self: pydrake.geometry.FramePoseVector, id: pydrake.geometry.FrameId, value: pydrake.math.RigidTransform) None
Sets the kinematics
value
for the givenid
.
- size(self: pydrake.geometry.FramePoseVector) int
Returns number of ids().
- value(self: pydrake.geometry.FramePoseVector, id: pydrake.geometry.FrameId) pydrake.math.RigidTransform
Returns the value associated with the given
id
.- Raises
RuntimeError if id is not in the specified set of ids. –
- Template parameter
- template pydrake.geometry.FramePoseVector_
Instantiations:
FramePoseVector_[float]
,FramePoseVector_[AutoDiffXd]
,FramePoseVector_[Expression]
- class pydrake.geometry.FramePoseVector_[AutoDiffXd]
A KinematicsVector is a container class used to report kinematics data for registered frames and geometries (keyed by unique FrameId/GeometryId values) to SceneGraph where the set of keys (FrameId/GeometryId) is usually constant and the values (kinematics data) are varying. It is an internal class and one should never interact with it directly. The template aliases FramePoseVector and GeometryConfigurationVector that instantiate KinematicsVector should be used instead.
Click to expand C++ code...
template <typename T> class MySystem : public LeafSystem<T> { public: MySystem() { ... this->DeclareAbstractOutputPort( &AllocInConstructorSystem::CalcFramePoseOutput); ... } private: void CalcFramePoseOutput(const Context<T>& context, geometry::FramePoseVector<T>* poses) const { poses->clear(); for (int i = 0; i < static_cast<int>(frame_ids_.size()); ++i) { poses->set_value(frame_ids_[i], poses_[i]); } } std::vector<FrameId> frame_ids_; std::vector<RigidTransform<T>> poses_; };
If a System only ever emits a single frame/geometry (or small-constant-number of frames/geometries), then there’s a shorter alternative way to write a Calc method, using an initializer_list:
Click to expand C++ code...
void CalcFramePoseOutput(const Context<T>& context, geometry::FramePoseVector<T>* poses) const { const RigidTransform<T>& pose = ...; poses = {{frame_id_, pose}}; }
N.B. When the systems framework calls the
Calc
method, the value pointed to byposes
is in an unspecified state. The implementation ofCalc
must always ensure thatposes
contains the correct value upon return, no matter what value it started with. The easy ways to do this are to call eitherposes->clear()
or the assignment operator*poses = ...
.- Template parameter
Id
: The key used to locate the kinematics data. Can be FrameId or GeometryId.
- Template parameter
KinematicsValue
: The underlying data type of the kinematics data (e.g., pose, configuration, or velocity).
The FramePoseVector and GeometryConfigurationVector classes are aliases of the KinematicsVector instantiated on specific data types (RigidTransform and VectorX respectively). Each of these data types are templated on Eigen scalars. All supported combinations of data type and scalar type are already available to link against in the containing library. No other values for KinematicsValue are supported.
Currently, the following data types with the following scalar types are supported:
Alias | Instantiation | Scalar types ————————————-|--------------------------------------------------|————- FramePoseVector<Scalar> | KinematicsVector<FrameId,RigidTransform<Scalar>> | double/AutoDiffXd/Expression GeometryConfigurationVector<Scalar> | KinematicsVector<GeometryId, VectorX<Scalar>> | double/AutoDiffXd/Expression
- __init__(self: pydrake.geometry.FramePoseVector_[AutoDiffXd]) None
Initializes the vector with no data .
- clear(self: pydrake.geometry.FramePoseVector_[AutoDiffXd]) None
Clears all values, resetting the size to zero.
- has_id(self: pydrake.geometry.FramePoseVector_[AutoDiffXd], id: pydrake.geometry.FrameId) bool
Reports true if the given id is a member of this data.
- ids(self: pydrake.geometry.FramePoseVector_[AutoDiffXd]) list[pydrake.geometry.FrameId]
Provides a range object for all of the existing ids in the vector. This is intended to be used as:
Click to expand C++ code...
for (Id id : this_vector.ids()) { ... // Obtain the KinematicsValue of an id by `this_vector.value(id)` ... }
- set_value(self: pydrake.geometry.FramePoseVector_[AutoDiffXd], id: pydrake.geometry.FrameId, value: pydrake.math.RigidTransform_[AutoDiffXd]) None
Sets the kinematics
value
for the givenid
.
- size(self: pydrake.geometry.FramePoseVector_[AutoDiffXd]) int
Returns number of ids().
- value(self: pydrake.geometry.FramePoseVector_[AutoDiffXd], id: pydrake.geometry.FrameId) pydrake.math.RigidTransform_[AutoDiffXd]
Returns the value associated with the given
id
.- Raises
RuntimeError if id is not in the specified set of ids. –
- Template parameter
- class pydrake.geometry.FramePoseVector_[Expression]
A KinematicsVector is a container class used to report kinematics data for registered frames and geometries (keyed by unique FrameId/GeometryId values) to SceneGraph where the set of keys (FrameId/GeometryId) is usually constant and the values (kinematics data) are varying. It is an internal class and one should never interact with it directly. The template aliases FramePoseVector and GeometryConfigurationVector that instantiate KinematicsVector should be used instead.
Click to expand C++ code...
template <typename T> class MySystem : public LeafSystem<T> { public: MySystem() { ... this->DeclareAbstractOutputPort( &AllocInConstructorSystem::CalcFramePoseOutput); ... } private: void CalcFramePoseOutput(const Context<T>& context, geometry::FramePoseVector<T>* poses) const { poses->clear(); for (int i = 0; i < static_cast<int>(frame_ids_.size()); ++i) { poses->set_value(frame_ids_[i], poses_[i]); } } std::vector<FrameId> frame_ids_; std::vector<RigidTransform<T>> poses_; };
If a System only ever emits a single frame/geometry (or small-constant-number of frames/geometries), then there’s a shorter alternative way to write a Calc method, using an initializer_list:
Click to expand C++ code...
void CalcFramePoseOutput(const Context<T>& context, geometry::FramePoseVector<T>* poses) const { const RigidTransform<T>& pose = ...; poses = {{frame_id_, pose}}; }
N.B. When the systems framework calls the
Calc
method, the value pointed to byposes
is in an unspecified state. The implementation ofCalc
must always ensure thatposes
contains the correct value upon return, no matter what value it started with. The easy ways to do this are to call eitherposes->clear()
or the assignment operator*poses = ...
.- Template parameter
Id
: The key used to locate the kinematics data. Can be FrameId or GeometryId.
- Template parameter
KinematicsValue
: The underlying data type of the kinematics data (e.g., pose, configuration, or velocity).
The FramePoseVector and GeometryConfigurationVector classes are aliases of the KinematicsVector instantiated on specific data types (RigidTransform and VectorX respectively). Each of these data types are templated on Eigen scalars. All supported combinations of data type and scalar type are already available to link against in the containing library. No other values for KinematicsValue are supported.
Currently, the following data types with the following scalar types are supported:
Alias | Instantiation | Scalar types ————————————-|--------------------------------------------------|————- FramePoseVector<Scalar> | KinematicsVector<FrameId,RigidTransform<Scalar>> | double/AutoDiffXd/Expression GeometryConfigurationVector<Scalar> | KinematicsVector<GeometryId, VectorX<Scalar>> | double/AutoDiffXd/Expression
- __init__(self: pydrake.geometry.FramePoseVector_[Expression]) None
Initializes the vector with no data .
- clear(self: pydrake.geometry.FramePoseVector_[Expression]) None
Clears all values, resetting the size to zero.
- has_id(self: pydrake.geometry.FramePoseVector_[Expression], id: pydrake.geometry.FrameId) bool
Reports true if the given id is a member of this data.
- ids(self: pydrake.geometry.FramePoseVector_[Expression]) list[pydrake.geometry.FrameId]
Provides a range object for all of the existing ids in the vector. This is intended to be used as:
Click to expand C++ code...
for (Id id : this_vector.ids()) { ... // Obtain the KinematicsValue of an id by `this_vector.value(id)` ... }
- set_value(self: pydrake.geometry.FramePoseVector_[Expression], id: pydrake.geometry.FrameId, value: pydrake.math.RigidTransform_[Expression]) None
Sets the kinematics
value
for the givenid
.
- size(self: pydrake.geometry.FramePoseVector_[Expression]) int
Returns number of ids().
- value(self: pydrake.geometry.FramePoseVector_[Expression], id: pydrake.geometry.FrameId) pydrake.math.RigidTransform_[Expression]
Returns the value associated with the given
id
.- Raises
RuntimeError if id is not in the specified set of ids. –
- Template parameter
- class pydrake.geometry.GeometryFrame
This simple class carries the definition of a frame used in the SceneGraph. To register moving frames with SceneGraph (see SceneGraph::RegisterFrame()), a geometry source (see SceneGraph::RegisterSource()) instantiates a frame and passes ownership over to SceneGraph.
A frame is defined by two pieces of information:
the name, which must be unique within a single geometry source and
the “frame group”, an integer identifier that can be used to group frames
together within a geometry source.
The “frame group” is intended as a generic synonym for the model instance id defined by the RigidBodyTree.
See also
SceneGraph
- __init__(self: pydrake.geometry.GeometryFrame, frame_name: str, frame_group_id: int = 0) None
Constructor.
- Parameter
frame_name
: The name of the frame.
- Parameter
frame_group_id
: The optional frame group identifier. If unspecified, defaults to the common, 0 group. Must be non-negative.
- Parameter
- frame_group(self: pydrake.geometry.GeometryFrame) int
- id(self: pydrake.geometry.GeometryFrame) drake::Identifier<drake::geometry::FrameTag>
Returns the globally unique id for this geometry specification. Every instantiation of FrameInstance will contain a unique id value. The id value is preserved across copies. After successfully registering this FrameInstance, this id will serve as the identifier for the registered representation as well.
- name(self: pydrake.geometry.GeometryFrame) str
- class pydrake.geometry.GeometryId
Type used to identify geometry instances in SceneGraph.
- __init__(*args, **kwargs)
- static get_new_id() pydrake.geometry.GeometryId
Generates a new identifier for this id type. This new identifier will be different from all previous identifiers created. This method does not make any guarantees about the values of ids from successive invocations. This method is guaranteed to be thread safe.
- get_value(self: pydrake.geometry.GeometryId) int
Extracts the underlying representation from the identifier. This is considered invalid for invalid ids and is strictly enforced in Debug builds.
- is_valid(self: pydrake.geometry.GeometryId) bool
Reports if the id is valid.
- class pydrake.geometry.GeometryInstance
A geometry instance combines a geometry definition (i.e., a shape of some sort), a pose (relative to a parent “frame” P), material information, and an opaque collection of metadata. The parent frame can be a registered frame or another registered geometry.
Every GeometryInstance must be named. The naming convention mirrors that of valid names in SDF files. Specifically, any user-specified name will have all leading and trailing space and tab characters trimmed off. The trimmed name will have to satisfy the following requirements:
cannot be empty, and
the name should be unique in the scope of its frame and role. For example,
two GeometryInstances can both be called “ball” as long as they are affixed to different frames or if one is a collision geometry and the other is an illustration geometry. This is enforced when a role is assigned to the geometry.
If valid, the trimmed name will be assigned to the instance.
Names can have internal whitespace (e.g., “my geometry name”).
Canonicalized names
The silent transformation of a user-defined name to canonical name mirrors that of specifying geometry names in an SDF file. Consider the following SDF snippet:
Click to expand C++ code...
{xml} ... <visual name=" visual"> <geometry> <sphere> <radius>1.0</radius> </sphere> </geometry> </visual> ...
The name has two leading whitespace characters. The parsing process will consider this name as equivalent to “visual” and tests for uniqueness and non-emptiness will be applied to that trimmed result. The following code has an analogous effect:
Click to expand C++ code...
scene_graph->RegisterGeometry( source_id, frame_id, make_unique<GeometryInstance>(pose, make_unique<Sphere>(1.0), " visual"));
The specified name includes leading whitespace. That name will be trimmed and the result will be stored in the GeometryInstance (to be later validated by SceneGraph as part of geometry registration). Querying the instance of its name will return this canonicalized name.
- __init__(self: pydrake.geometry.GeometryInstance, X_PG: pydrake.math.RigidTransform, shape: drake::geometry::Shape, name: str) None
Constructs a geometry instance specification.
- Parameter
X_PG
: The pose of this geometry (
G
) in its parent’s frame (P
).- Parameter
shape
: The underlying shape for this geometry instance.
- Parameter
name
: The name of the geometry (must satisfy the name requirements).
- Raises
RuntimeError if the canonicalized version of name is empty. –
- Parameter
- id(self: pydrake.geometry.GeometryInstance) drake::geometry::GeometryId
Returns the globally unique id for this geometry specification. Every instantiation of GeometryInstance will contain a unique id value. The id value is preserved across copies. After successfully registering this GeometryInstance, this id will serve as the identifier for the registered representation as well.
- illustration_properties(self: pydrake.geometry.GeometryInstance) drake::geometry::IllustrationProperties
Returns a pointer to the geometry’s const illustration properties (if they are defined). Nullptr otherwise.
- mutable_illustration_properties(self: pydrake.geometry.GeometryInstance) drake::geometry::IllustrationProperties
Returns a pointer to the geometry’s mutable illustration properties (if they are defined). Nullptr otherwise.
- mutable_perception_properties(self: pydrake.geometry.GeometryInstance) drake::geometry::PerceptionProperties
Returns a pointer to the geometry’s mutable perception properties (if they are defined). Nullptr otherwise.
- mutable_proximity_properties(self: pydrake.geometry.GeometryInstance) drake::geometry::ProximityProperties
Returns a pointer to the geometry’s mutable proximity properties (if they are defined). Nullptr otherwise.
- name(self: pydrake.geometry.GeometryInstance) str
Returns the canonicalized name for the instance.
See also
canonicalized_geometry_names “Canonicalized names”
- perception_properties(self: pydrake.geometry.GeometryInstance) drake::geometry::PerceptionProperties
Returns a pointer to the geometry’s const perception properties (if they are defined). Nullptr otherwise.
- pose(self: pydrake.geometry.GeometryInstance) pydrake.math.RigidTransform
Returns the instance geometry’s pose in its parent frame.
- proximity_properties(self: pydrake.geometry.GeometryInstance) drake::geometry::ProximityProperties
Returns a pointer to the geometry’s const proximity properties (if they are defined). Nullptr otherwise.
- set_illustration_properties(self: pydrake.geometry.GeometryInstance, properties: drake::geometry::IllustrationProperties) None
Sets the illustration properties for the given instance.
- set_name(self: pydrake.geometry.GeometryInstance, arg0: str) None
Sets the canonicalized name for the instance.
See also
canonicalized_geometry_names “Canonicalized names”
- set_perception_properties(self: pydrake.geometry.GeometryInstance, properties: drake::geometry::PerceptionProperties) None
Sets the perception properties for the given instance.
- set_pose(self: pydrake.geometry.GeometryInstance, X_PG: pydrake.math.RigidTransform) None
Sets the pose of this instance in its parent’s frame.
- set_proximity_properties(self: pydrake.geometry.GeometryInstance, properties: drake::geometry::ProximityProperties) None
Sets the proximity properties for the given instance.
- shape(self: pydrake.geometry.GeometryInstance) drake::geometry::Shape
Returns the underlying shape specification for this geometry instance.
- Precondition:
release_shape() has not been called nor has this been moved-from.
- class pydrake.geometry.GeometryProperties
The base class for defining a set of geometry properties.
Each property consists of a
(group, property)
name-pair and a typed value. The name pair allows for reuse of common property names (e.g., “diffuse”) to be differentiated in interpretation by associating them with different groups. The only restriction on the value type is that it must be either cloneable or copy-constructible.A set of geometry property values are defined when geometry is registered with SceneGraph by an instantiator and accessed by some downstream consumer entity. Each consumer specifies what properties it expects to find and what default values (if any) it provides. For example, the consumer could document that a particular property is always required and its absence would throw an exception. Alternatively, it could indicate that a property is optional and a default value will be used in its absence. It is the responsibility of the instantiator to make sure that the geometry property values are correctly defined according to the expected consumer’s specification. Correctness includes such issues as key-value pairs placed into a correctly-spelled group, property keys being likewise correctly spelled, and values of the expected type. Correct spelling includes correct case. The instantiator uses the AddProperty() method to add new properties to the set.
To read the property (
some_group
, some_property) from a property set:1. Optionally test to see if the property exists by confirming the group
some_group
is in the set via HasGroup() and that the propertysome_property
is insome_group
via HasProperty(). Attempting to access a property with a non-existent (group, property) pair may lead to an exception (see API documentation below). 2. Acquire a property value via the GetProperty() or GetPropertyOrDefault() methods. NOTE: Reading a property requires a compile-time declaration of the type of value being read. If the stored value is of a different type, an exception will be thrown.The following examples outline a number of ways to create and consume geometry properties. By design, GeometryProperties cannot be constructed, copied, or moved directly. Only derived classes can do so. This facilitates strongly typed sets of properties associated with particular geometry roles. So, for these examples we’ll exercise the derived class associated with proximity queries: ProximityProperties.
The string-based structure of GeometryProperties provides a great deal of flexibility at the cost of spelling sensitivity. It would be easy to introduce typos that would then “hide” property values in some group a consumer wouldn’t look. In these examples, we avoid using string literals as group or property names (at least in the cases where the same name is used multiple times) to help avoid the possibility of typo-induced errors. That is not required and certainly not the only way to avoid such bugs.
Creating properties
Creating properties in a new group
This is a simple example in which a single group is added with properties of various types.
Click to expand C++ code...
const std::string group_name("my_group"); ProximityProperties properties; // This first invocation implicitly creates the group "my_group". properties.AddProperty(group_name, "count", 7); // int type properties.AddProperty(group_name, "length", 7.); // double type properties.AddProperty(group_name, "name", "7"); // std::string type
Creating properties in the default group
Similar to the previous examples, the properties are added to the default group. Just be aware that if multiple sites in your code add properties to the default group, the possibility that names get repeated increases. Property names must be unique within a single group, including the default group.
Click to expand C++ code...
ProximityProperties properties; properties.AddProperty(ProximityProperties::default_group_name(), "count", 7); properties.AddProperty(ProximityProperties::default_group_name(), "width", 7.); properties.AddProperty(ProximityProperties::default_group_name(), "name", "7");
Aggregate properties in a struct
In some cases, there is a set of values that will always be accessed together (specified with coordinated semantics). In these cases, it makes sense to aggregate them into a struct and store that as a single value. This reduces the number of lookups required.
It’s worth noting, that if the data value is a struct, calls to GetPropertyOrDefault() still operate as an “all-or-nothing” basis. If the property struct exists, it will be returned, if it’s missing the default struct will be returned. There is no concept of a “partial” struct in which some undefined values in the struct will be replaced with their corresponding values in the default struct.
Click to expand C++ code...
struct MyData { int i{}; double d{}; std::string s; }; ProximityProperties properties; const std::string group_name("my_group"); MyData data{7, 7., "7"}; properties.AddProperty(group_name, "data1", data); // These alternate forms are also acceptable (but not in succession, as the // property name has already been used by the first invocation). properties.AddProperty(group_name, "data2", MyData{6, 6., "6"}); properties.AddProperty<MyData>(group_name, "data2", {6, 6., "6"});
Reading properties
This section describes how to read properties under several different scenarios: (a) when specific properties are required, (b) when the consumer provides a default value for missing properties, and (c) when the consumer needs to inspect what properties are available.
Look up specific, *required properties*
In this case, the consumer of the properties is looking for one or more specific properties. It will ignore any other properties. More particularly, if those properties are missing, it is considered a runtime error and an exception is thrown.
The error can be handled in one of two ways: simply let the generic exception generated by GeometryProperties propagate upward, or detect the missing property and throw an exception with a custom message. The example below shows both approaches.
Click to expand C++ code...
const IllustrationProperties& properties = FunctionThatReturnsProperties(); // Looking for a Rgba of rgba colors named "rgba" - send generic error that // the property set is missing the required property. const Rgba rgba = properties.GetProperty<Rgba>("MyGroup", "rgba"); // Explicitly detect missing property and throw exception with custom message. if (!properties.HasProperty("MyGroup", "rgba")) { throw RuntimeError( "ThisClass: Missing the necessary 'rgba' property; the object cannot be " "rendered"); } // Otherwise acquire value, confident that no exception will be thrown. const Rgba rgba = properties.GetProperty<Rgba>("MyGroup", "rgba");
Note
calls to
GetProperty()
always require the return type template value (e.g.,Rgba
) to be specified in the call.Look up specific properties with default property values
As with the previous case, the consumer is looking for one or more specific properties. However, in this case, the consumer provides a default value to use in case the target property is not defined. In this invocation, the template parameter need not be explicitly declared – the inferred return type will be the same as the default value.
Click to expand C++ code...
const IllustrationProperties& properties = FunctionThatReturnsProperties(); // Looking for a Rgba of rgba colors named "rgba". const Rgba default_color{0.9, 0.9, 0.9}; const Rgba rgba = properties.GetPropertyOrDefault("MyGroup", "rgba", default_color);
Alternatively, the default value can be provided in one of the following forms:
Click to expand C++ code...
properties.GetPropertyOrDefault("MyGroup", "rgba", Rgba{0.9, 0.9, 0.9}); properties.GetPropertyOrDefault<Rgba>("MyGroup", "rgba", {0.9, 0.9, 0.9});
Iterating through provided properties
Another alternative is to iterate through the properties that have been provided. This might be done for several reasons, e.g.:
the consumer wants to validate the set of properties, giving the user
feedback if an unsupported property has been provided, and/or - the consumer has a default value for every property and allows the registering code to define only those properties that deviate from the specified default.
Working with properties in this manner requires knowledge of how to work with AbstractValue.
Click to expand C++ code...
const IllustrationProperties& properties = FunctionThatReturnsProperties(); for (const auto& pair : properties.GetGroupProperties("MyGroup") { const std::string& name = pair.first; if (name == "rgba") { // Throws an exception if the named parameter is of the wrong type. const Rgba& rgba = pair.second->GetValueOrThrow<Rgba>(); } }
- __init__(*args, **kwargs)
- AddProperty(self: pydrake.geometry.GeometryProperties, group_name: str, name: str, value: object) None
Adds the named property (
group_name
, name) with the givenvalue
. Adds the group if it doesn’t already exist.- Parameter
group_name
: The group name.
- Parameter
name
: The name of the property – must be unique in the group.
- Parameter
value
: The value to assign to the property.
- Raises
RuntimeError if the property already exists. –
- Template parameter
ValueType
: The type of data to store with the attribute – must be copy constructible or cloneable (see Value).
- Parameter
- static default_group_name() str
Returns the default group name. There is no guarantee as to what string corresponds to the default group. Therefore it should always be accessed via this method.
- GetGroupNames(self: pydrake.geometry.GeometryProperties) set[str]
Returns all of the defined group names.
- GetPropertiesInGroup(self: pydrake.geometry.GeometryProperties, group_name: str) dict
Retrieves the indicated property group. The returned group is valid for as long as this instance.
- Raises
RuntimeError if there is no group with the given name. –
- GetProperty(self: pydrake.geometry.GeometryProperties, group_name: str, name: str) object
Retrieves the typed value for the property (
group_name
, name) from this set of properties.- Parameter
group_name
: The name of the group to which the property belongs.
- Parameter
name
: The name of the desired property.
- Raises
RuntimeError if a) the group name is invalid, b) the property name –
is invalid, or c) the property type is not that specified. –
- Template parameter
ValueType
: The expected type of the desired property.
- Returns
const ValueType& of stored value. If ValueType is Eigen::Vector4d, the return type will be a copy translated from Rgba.
- Parameter
- GetPropertyOrDefault(self: pydrake.geometry.GeometryProperties, group_name: str, name: str, default_value: object) object
Retrieves the typed value for the property (
group_name
, name) from the set of properties (if it exists), otherwise returns the given default value. The givendefault_value
is returned only if the property is missing. If the property exists and is of a different type, an exception will be thrown. If it is of the expected type, the stored value will be returned.Generally, it is unnecessary to explicitly declare the
ValueType
of the property value; it will be inferred from the provided default value. Sometimes it is convenient to provide the default value in a form that can be implicitly converted to the final type. In that case, it is necessary to explicitly declare the desiredValueType
so the compiler does not infer the wrong type, e.g.:Click to expand C++ code...
// Note the _integer_ value as default value. const double my_value = properties.GetPropertyOrDefault<double>("g", "p", 2);
- Parameter
group_name
: The name of the group to which the property belongs.
- Parameter
name
: The name of the desired property.
- Parameter
default_value
: The alternate value to return if the property cannot be acquired.
- Raises
RuntimeError if a property of the given name exists but is not of –
ValueType` –
- Parameter
- HasGroup(self: pydrake.geometry.GeometryProperties, group_name: str) bool
Reports if the given named group is part of this property set.
- HasProperty(self: pydrake.geometry.GeometryProperties, group_name: str, name: str) bool
Reports if the property (
group_name
, name) exists in the group.- Parameter
group_name
: The name of the group to which the tested property should belong.
- Parameter
name
: The name of the property under question.
- Returns
true iff the group exists and a property with the given
name
exists in that group.
- Parameter
- num_groups(self: pydrake.geometry.GeometryProperties) int
Reports the number of property groups in this set.
- RemoveProperty(self: pydrake.geometry.GeometryProperties, group_name: str, name: str) bool
Removes the (
group_name
, name) property (if it exists). Upon completion the property will not be in the set.- Returns
True
if the property existed prior to the call.
- UpdateProperty(self: pydrake.geometry.GeometryProperties, group_name: str, name: str, value: object) None
Updates the named property (
group_name
, name) with the givenvalue
. If the property doesn’t already exist, it is equivalent to callingAddProperty
. If the property does exist, its value (which must have the same type asvalue
) will be replaced.- Parameter
group_name
: The group name.
- Parameter
name
: The name of the property – must be unique in the group.
- Parameter
value
: The value to assign to the property.
- Raises
RuntimeError if the property exists with a different type. –
- Template parameter
ValueType
: The type of data to store with the attribute – must be copy constructible or cloneable (see Value).
- Parameter
- class pydrake.geometry.GeometrySet
The GeometrySet, as its name implies, is a convenience class for defining a set of geometries. What makes it unique from a simple
std::set<GeometryId>
instance is that membership doesn’t require explicit GeometryId enumeration; GeometryId values can be added to the set by adding theFrameId
for the frame to which the geometries are rigidly affixed.This class does no validation; it is a simple collection. Ultimately, it serves as the operand of various geometry operations (e.g., CollisionFilterDeclaration and CollisionFilterManager::Apply(). If the operation has a particular prerequisite on the members of a GeometrySet, it is the operation’s responsibility to enforce that requirement.
More formally, the SceneGraph consists of a set of geometries, each associated with a unique identifier. As such, we can consider the set of all identifiers
SG = {g₀, g₁, ..., gₙ}
that belong to a SceneGraph. A GeometrySet should represent a subset of those identifiers,Gₛ ⊆ SG
. The convenience of the GeometrySet class is how the subset is defined. Given a set of frame idsF = {f₀, f₁, ..., fₙ}
and geometry idsG = {g₀, g₁, ..., gₘ}
, Gₛ = G ⋃ geometry(f₀) ⋃ … ⋃ geometry(fₙ) (wheregeometry(f)
is the set of geometries rigidly affixed to frame f).- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.GeometrySet) -> None
__init__(self: pydrake.geometry.GeometrySet, geometry_id: drake::geometry::GeometryId) -> None
See main constructor
__init__(self: pydrake.geometry.GeometrySet, frame_id: drake::Identifier<drake::geometry::FrameTag>) -> None
See main constructor
__init__(self: pydrake.geometry.GeometrySet, geometry_ids: list[drake::geometry::GeometryId]) -> None
See main constructor
__init__(self: pydrake.geometry.GeometrySet, frame_ids: list[drake::Identifier<drake::geometry::FrameTag>]) -> None
See main constructor
__init__(self: pydrake.geometry.GeometrySet, geometry_ids: list[drake::geometry::GeometryId], frame_ids: list[drake::Identifier<drake::geometry::FrameTag>]) -> None
See main constructor
- Add(*args, **kwargs)
Overloaded function.
Add(self: pydrake.geometry.GeometrySet, geometry_id: drake::geometry::GeometryId) -> None
Add(self: pydrake.geometry.GeometrySet, frame_id: drake::Identifier<drake::geometry::FrameTag>) -> None
Add(self: pydrake.geometry.GeometrySet, geometry_ids: list[drake::geometry::GeometryId]) -> None
See main constructor
Add(self: pydrake.geometry.GeometrySet, frame_ids: list[drake::Identifier<drake::geometry::FrameTag>]) -> None
See main constructor
Add(self: pydrake.geometry.GeometrySet, geometry_ids: list[drake::geometry::GeometryId], frame_ids: list[drake::Identifier<drake::geometry::FrameTag>]) -> None
See main constructor
- class pydrake.geometry.GeometryVersion
A version numbering class that reports revisions of SceneGraph’s geometric data.
Other Systems can use this version number to perform updates when they detect changes to the geometric data they consume. The version of the geometry data is made available through SceneGraphInspector.
The geometry data is partitioned by geometric role and have independent role version values. Some of SceneGraph’s API (as variously documented) will cause one or more role versions to change. This class provides the API
IsSameAs
that takes another GeometryVersion as well as a Role to help detect whether the provided role of the geometries may have changed. For example:Click to expand C++ code...
// Downstream system holds an instance of GeometryVersion `old_version` as a // reference to compare against. // Get the version under test from SceneGraphInspector. const GeometryVersion& test_version = scene_graph_inspector.geometry_version(); // Determine if two versions have the same proximity data. bool same_proximity = old_version.IsSameAs(test_version, Role::kProximity);
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.GeometryVersion) -> None
Constructs a default-initialized instance; guaranteed to be different from every other instance.
__init__(self: pydrake.geometry.GeometryVersion, other: pydrake.geometry.GeometryVersion) -> None
Creates a copy of the GeometryVersion.
- IsSameAs(self: pydrake.geometry.GeometryVersion, other: pydrake.geometry.GeometryVersion, role: drake::geometry::Role) bool
Returns true if
this
GeometryVersion has the samerole
version as theother
GeometryVersion.
- class pydrake.geometry.GltfExtension
Specifies how to deal with glTF “extensions” (non-standard capabilities). https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#specifying-extensions
- __init__(self: pydrake.geometry.GltfExtension, **kwargs) None
- property warn_unimplemented
- class pydrake.geometry.HalfSpace
Bases:
pydrake.geometry.Shape
Definition of a half space. In its canonical frame, the plane defining the boundary of the half space is that frame’s z = 0 plane. By implication, the plane’s normal points in the +z direction and the origin lies on the plane. Other shapes are considered to be penetrating the half space if there exists a point on the test shape that lies on the side of the plane opposite the normal.
- __init__(self: pydrake.geometry.HalfSpace) None
- static MakePose(Hz_dir_F: numpy.ndarray[numpy.float64[3, 1]], p_FB: numpy.ndarray[numpy.float64[3, 1]]) pydrake.math.RigidTransform
Creates the pose of a canonical half space in frame F. The half space’s normal is aligned to the positive z-axis of its canonical frame H. Given a vector that points in the same direction, measured in the F frame (Hz_dir_F) and a position vector to a point on the half space’s boundary* expressed in the same frame,
p_FB
, creates the pose of the half space in frame F:X_FH
.- Parameter
Hz_dir_F
: A vector in the direction of the positive z-axis of the canonical frame expressed in frame F. It must be a non-zero vector but need not be unit length.
- Parameter
p_FB
: A point B lying on the half space’s boundary measured and expressed in frame F.
- Returns
X_FH
: The pose of the canonical half-space in frame F.
- Raises
RuntimeError if the normal is close to a zero-vector (e.g., –
‖normal_F‖₂ < ε) –
- Parameter
- class pydrake.geometry.HydroelasticContactRepresentation
Reports on how a hydroelastic contact surface is represented. See contact_surface_discrete_representation “the documentation in ContactSurface” for more details.
Members:
kTriangle :
kPolygon :
- __init__(self: pydrake.geometry.HydroelasticContactRepresentation, value: int) None
- kPolygon = <HydroelasticContactRepresentation.kPolygon: 1>
- kTriangle = <HydroelasticContactRepresentation.kTriangle: 0>
- property name
- property value
- class pydrake.geometry.IllustrationProperties
Bases:
pydrake.geometry.GeometryProperties
The set of properties for geometry used in an “illustration” role.
Examples of functionality that depends on the illustration role: - drake_visualizer_role_consumer “drake::geometry::DrakeVisualizer”
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.IllustrationProperties) -> None
__init__(self: pydrake.geometry.IllustrationProperties, other: pydrake.geometry.IllustrationProperties) -> None
Creates a copy of the properties
- class pydrake.geometry.LightParameter
Light parameter for supporting RenderEngine implementations. Look at the various RenderEngine___Params types to see if they support declaring lights.
- __init__(self: pydrake.geometry.LightParameter, **kwargs) None
- property attenuation_values
- property color
- property cone_angle
- property direction
- property frame
- property intensity
- property position
- property type
- pydrake.geometry.MakePhongIllustrationProperties(diffuse: numpy.ndarray[numpy.float64[4, 1]]) pydrake.geometry.IllustrationProperties
Constructs an IllustrationProperties instance compatible with a simple “phong” material using only the given
diffuse
color.
- pydrake.geometry.MakeRenderEngineGl(params: pydrake.geometry.RenderEngineGlParams = RenderEngineGlParams(default_diffuse=Rgba(r=0.9, g=0.7, b=0.2, a=1.0), default_clear_color=Rgba(r=0.8, g=0.8980392156862745, b=1.0, a=1.0), lights=[])) pydrake.geometry.RenderEngine
Constructs a RenderEngine implementation which uses a purely OpenGL renderer. The engine only works under Ubuntu. If called on a Mac, it will throw.
Note
RenderEngineGl behaves a bit differently from other RenderEngine implementations (e.g., RenderEngineVtk) with respect to displayed images. First, RenderEngineGl can only display a single image type at a time. So, if a shown window has been requested for both label and color images, the images will alternate in the same window. Second, the window display draws all images flipped vertically. The image produced will be compatible with the Drake ecosystem, only the visualization will be upside down. This has been documented in https://github.com/RobotLocomotion/drake/issues/14254.
** Using RenderEngineGl in multiple threads **
Most importantly, a single RenderEngineGl should not be exercised in multiple threads. One thread, one RenderEngineGl instance.
A RenderEngineGl instance and its clones can be used in different threads simultaneously, but only the rendering APIs are threadsafe. Do not mutate the contents of the engine (e.g., adding/removing geometries, etc.) in parallel.
Two independently constructed RenderEngineGl instances can be freely used in different threads – all APIs are available.
The expected workflow is to add a RenderEngineGl instance a SceneGraph instance (see SceneGraph::AddRenderer()) and then to populate SceneGraph with the desired geometry. Each systems::Context allocated for that SceneGraph will receive a clone of the original RenderEngineGl. One systems::Context can be used per thread to create rendered images in parallel.
- Raises
RuntimeError if kHasRenderEngineGl is false. –
- pydrake.geometry.MakeRenderEngineGltfClient(params: pydrake.geometry.RenderEngineGltfClientParams = RenderEngineGltfClientParams(base_url='http://127.0.0.1:8000', render_endpoint='render', verbose=False, cleanup=True)) pydrake.geometry.RenderEngine
Constructs a RenderEngine implementation which generates <a href=”https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html”>glTF </a> files to upload to a render server, and retrieves renderings from said server by copying image data back into drake systems::sensors::Image buffers. The server url and endpoint are provided through the specified RenderEngineGltfClientParams. The returned RenderEngine implements the client side of the render_engine_gltf_client_server_api. The rules for supported geometries and textures are the same as for the VTK-based engine and are described in MakeRenderEngineVtk().
Note
The underlying RenderEngine utilizes [libcurl][libcurl] to communicate with a server. Static curl initialization must be performed once per process, and the operation is [not thread-safe][libcurl_threadsafe]! Instantiating this RenderEngine automatically initializes curl with the default [curl_global_init(CURL_GLOBAL_ALL | CURL_GLOBAL_ACK_EINTR)][libcurl_init], the implication for consuming applications being:
Note: 1. See allow_network “DRAKE_ALLOW_NETWORK” for an environment variable option to deny remote rendering entirely. 2. If you intend to have your rendering take place in a threaded context, you must instantiate this RenderEngine via MakeRenderEngineGltfClient from the main thread before spawning your threaded workers. As soon as one of these RenderEngine instances has been constructed, libcurl will have been initialized.
Click to expand C++ code...
// Setup your server information and create the RenderEngine. This must // be done in a non-threaded context (e.g., at the program start). RenderEngineGltfClientParams params; params.base_url = "http://some-server.url"; auto render_engine = MakeRenderEngineGltfClient(params); // After MakeRenderEngineGltfClient() function call, libcurl has been // initialized and you may now create threads if desired.
3. If you need to use a different initialization strategy for libcurl in your application, you should first create the RenderEngine using MakeRenderEngineGltfClient, then manually call [curl_global_cleanup()][libcurl_cleanup], followed by manually calling [curl_global_init(…)][libcurl_init] with your desired flags. In general, this scenario is atypical and you should not need to worry about this. Applications with specialized libcurl needs, though, must understand the construction and initialization order to be able to modify the behavior to suit their needs.
Click to expand C++ code...
// Follow the steps above to construct the RenderEngine given the // specified RenderEngineGltfClientParams. // Libcurl has been initialized at this point, so your application needs // to reset and re-initialize curl again. curl_global_cleanup(); curl_global_init(...); // <<< your custom flags here // Now that libcurl has been re-initialized to suit your application's // needs, you may now create threads if desired.
[libcurl]: https://curl.se/libcurl/ [libcurl_threadsafe]: https://curl.se/libcurl/c/threadsafe.html [libcurl_init]: https://curl.se/libcurl/c/curl_global_init.html [libcurl_cleanup]: https://curl.se/libcurl/c/curl_global_cleanup.html
- pydrake.geometry.MakeRenderEngineVtk(params: pydrake.geometry.RenderEngineVtkParams) pydrake.geometry.RenderEngine
Constructs a RenderEngine implementation which uses a VTK-based OpenGL renderer.
Warning
On macOS, we’ve observed that RenderEngineVtk sometimes does not obey render::ColorRenderCamera::show_window when it’s set to
True
. Refer to issue #20144 for further discussion.This RenderEngine implementation looks for the following properties when registering visual geometry, categorized by rendered image type.
RGB images
Group name | Property Name | Required | Property Type | PropertyDescription | | :——–: | :———–: | :——: | :————-: | :——————- | | phong | diffuse | no¹ | Eigen::Vector4d | The rgba value of the object surface. | | phong | diffuse_map | no² | std::string | The path to a texture to apply to the geometry.³⁴ |
¹ If no diffuse value is given, a default rgba value will be applied. The default color is a bright orange. This default value can be changed to a different value at construction.
² If no path is specified, or the file cannot be read, the diffuse rgba value is used (or its default).
³ RenderEngineVtk implements a legacy feature for associating textures with meshes. If no
(phong, diffuse_map)
property is provided (or it refers to a file that doesn’t exist), for a mesh named/path/to/mesh.obj
, RenderEngineVtk will search for a file/path/to/mesh.png
(replacing “obj” with “png”). If that image exists, it will be used as a texture on the mesh object. ⁴ The render engine consumes pngs with uchar channels. Pngs with a different bit depth, e.g., uint16 channels, will be converted to that.Note
RenderEngineVtk does not support the OBJ format
usemtl
directive. Instead, it has two ways to associate a color texture with an obj file: - File name matching; see footnote 3 above. - Explicit assignment of arbitrary texture files from within model files. In SDFormat, use the tag tag_drake_diffuse_map. In URDF, use//visual/material/texture
.Depth images
No specific properties required.
Label images
Group name | Property Name | Required | Property Type | PropertyDescription | | :——–: | :———–: | :———–: | :————-: | :——————- | | label | id | no⁵ | RenderLabel | The label to render into the image. |
⁵ When the label property is not set, RenderEngineVtk uses a default render label of RenderLabel::kDontCare.
Geometries accepted by RenderEngineVtk
As documented in RenderEngine::RegisterVisual(), a RenderEngine implementation can use the properties found in the PerceptionProperties to determine whether it accepts a shape provided for registration. RenderEngineVtk makes use of defaults to accept all geometries (assuming the properties pass validation, e.g., render label validation).
- class pydrake.geometry.Mesh
Bases:
pydrake.geometry.Shape
Definition of a general (possibly non-convex) mesh.
The mesh may be a triangular surface mesh or a tetrahedral volume mesh, depending on how it used.
Meshes can be used with all three roles but, currently, the support for the proximity role is limited. Where a general mesh is not supported, the mesh is replaced by its convex hull. See the documentation of QueryObject’s proximity queries for more details. The notable cases where the actual mesh topology is used includes:
Specifying the Mesh as rigid hydroelastic.
Specifying the Mesh as compliant hydroelastic (when it references a
tetrahedral .vtk file). - Specifying the Mesh as deformable (when it references a tetrahedral .vtk file).
This convex-hull substitution is a regrettable stop-gap solution until we fully support general, non-convex meshes throughout proximity queries.
For visual roles (illustration and perception), the specified mesh file is used as directly as possible.
The mesh is defined in a canonical frame C, implicit in the file parsed. Upon loading it in SceneGraph it can be scaled around the origin of C by a given
scale
amount.- __init__(self: pydrake.geometry.Mesh, filename: str, scale: float = 1.0) None
Constructs a mesh shape specification from the mesh file located at the given file path. Optionally uniformly scaled by the given scale factor.
The mesh file referenced can be an .obj, a volume mesh in a .vtk, or a .gltf file. However, not all file formats are appropriate for all roles. (E.g., a tetrahedral .vtk file should not be assigned a perception role.)
- Parameter
filename
: The file name; if it is not absolute, it will be interpreted relative to the current working directory.
- Parameter
scale
: An optional scale to coordinates.
- Raises
RuntimeError if scale < 1e-8. Note that a negative scale is –
considered valid. We want to preclude scales near zero but –
recognise that scale is a convenience tool for "tweaking" models. –
8 orders of magnitude should be plenty without considering –
revisiting the model itself. –
- Parameter
- extension(self: pydrake.geometry.Mesh) str
Returns the extension of the mesh filename – all lower case and including the dot. In other words /foo/bar/mesh.obj and /foo/bar/mesh.OBJ would both report the “.obj” extension. The “extension” portion of the filename is defined as in std::filesystem::path::extension().
- filename(self: pydrake.geometry.Mesh) str
- GetConvexHull(self: pydrake.geometry.Mesh) pydrake.geometry.PolygonSurfaceMesh
Reports the convex hull of the named mesh.
Note: the convex hull is computed on demand on the first invocation. All subsequent invocations should have an O(1) cost.
- Raises
if the referenced mesh data cannot be read or is degenerate –
(insufficient number of vertices, co-linear or coincident –
vertices, etc.) All of the vertices lying on a plane is not –
considered degenerate. –
- scale(self: pydrake.geometry.Mesh) float
- class pydrake.geometry.Meshcat
Provides an interface to Meshcat (https://github.com/meshcat-dev/meshcat).
Each instance of this class spawns a thread which runs an http/websocket server. Users can navigate their browser to the hosted URL to visualize the Meshcat scene. Note that, unlike many visualizers, one cannot open the visualizer until this server is running.
Warning
In the current implementation, Meshcat methods must be called from the same thread where the class instance was constructed. For example, running multiple simulations in parallel using the same Meshcat instance is not yet supported. We may generalize this in the future.
https://github.com/meshcat-dev/meshcat#api provides a nice introduction to the websocket API that we wrap with this class. One of the core concepts is the “scene tree” – a directory-like structure of objects, transforms, and properties. The scene tree is viewable in the browser by clicking on “Open Controls” in the top right corner.
Elements of the tree are referenced programmatically by a “/”-delimited string indicating the object’s path in the scene tree. An object at path “/foo/bar” is a child of an object at path “/foo”, so setting the transform of (or deleting) “/foo” will also affect its children.
The string path arguments to the methods in this class use the following semantics: - A path that begins with “/” is treated as an absolute path, and is used without modification. - A path that does not begin with “/” is treated as a relative path to the default working directory. - The “working directory” is fixed to be “/drake” in the current implementation. So any relative path “foo” will be treated as “/drake/foo”. - Delete(“/foo”) will remove all objects, transforms, and properties in “/foo” and its children from the scene tree. - Delete() is equivalent to Delete(“”) or Delete(“/drake/”). - SetObject(“/foo”, …) places the object at “/foo/<object>”, where “<object>” is a hard-coded suffix used for all objects. You can use the Delete(“/foo/<object>”) to delete the object only (and not the children of “/foo”) and must use SetProperty(“/foo/<object>”, …) to change object-specific properties.
The root directory contains a number of elements that are set up automatically in the browser. These include “/Background”, “/Lights”, “/Grid”, and “/Cameras”. To find more details please see the @link https://github.com/meshcat-dev/meshcat#api meshcat documentation @endlink and the @link https://threejs.org/docs/index.html three.js documentation @endlink. - You can modify these elements, create new lights/cameras, and even delete these elements (one at a time). - Delete(“/”) is not allowed. It will be silently ignored.
For convenience, Meshcat fosters a work flow in which all user-created objects created in Drake are contained in the “/drake” folder. Objects added with a relative path are placed in the “/drake” folder for you. The benefits are: - It’s simple to distinguish between user objects and “infrastructure” objects in the visualizer. - All user objects can easily be cleared by a single, parameter-free call to Delete(). You are welcome to use absolute paths to organize your data, but the burden on tracking and cleaning them up lie on you.
Meshcat has an experimental AR/VR option (using WebXR). It can be enabled through url parameters. For example, for a meshcat url
http://localhost:7000
, the following will enable the VR mode:http://localhost:7000?webxr=vr
To to use augmented reality (where the meshcat background is replaced with your device’s camera image), use:
http://localhost:7000?webxr=ar
If augmented reality is not available, it will fallback to VR mode.
Some notes on using the AR/VR modes:
Before starting the WebXR session, position the interactive camera to be
approximately where you want the origin of the head set’s origin to be. - The meshcat scene controls are disabled while the WebXR session is active. - WebXR sessions can only be run with perspective cameras. - The controllers can be visualized but currently can’t interact with the Drake simulation physically. To visualize the controllers append the additional url parameter
controller=on
as inhttp://localhost:7000?webxr=vr&controller=on
.If you do not have AR/VR hardware, you can use an emulator in your browser to experiment with the mode. Use an browser plugin like WebXR API Emulator (i.e., for [Chrome](https://chrome.google.com/webstore/detail/webxr-api-emulator/mjddjgeghkdijejnciaefnkjmkafnnje) or [Firefox](https://addons.mozilla.org/en-US/firefox/addon/webxr-api-emulator/)).
The AR/VR mode is not currently supported in offline mode (i.e., when saving as StaticHtml()).
See MeshcatParams for options to control the hostname and port to bind to.
See allow_network “DRAKE_ALLOW_NETWORK” for an environment variable option to deny Meshcat entirely.
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.Meshcat, port: Optional[int] = None) -> None
Constructs the Meshcat instance on
port
. If no port is specified, it will listen on the first available port starting at 7000 (up to 7999). If port 0 is specified, it will listen on an arbitrary “ephemeral” port.- Precondition:
We require
port
== 0 ||port
>= 1024.
- Raises
RuntimeError if no requested port is available. –
__init__(self: pydrake.geometry.Meshcat, params: pydrake.geometry.MeshcatParams) -> None
Constructs the Meshcat instance using the given
params
.
- AddButton(self: pydrake.geometry.Meshcat, name: str, keycode: str = '') None
Adds a button with the label
name
to the meshcat browser controls GUI. If the optionalkeycode
is set to a javascript string key code (such as “KeyG” or “ArrowLeft”, see https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values), then a keydown callback is registered in the GUI which will alsoclick
the button. If the button already existed, then resets its click count to zero; and sets the keycode if no keycode was set before.- Raises
RuntimeError if name has already been added as any other type –
of control (e.g., slider) –
RuntimeError if a button of the same name has already been –
assigned a different keycode. –
- AddSlider(self: pydrake.geometry.Meshcat, name: str, min: float, max: float, step: float, value: float, decrement_keycode: str = '', increment_keycode: str = '') None
Adds a slider with the label
name
to the meshcat browser controls GUI. The slider range is given by [min,max`]. `step
is the smallest increment by which the slider can change values (and therefore send updates back to this Meshcat instance).value
specifies the initial value; it will be truncated to the slider range and rounded to the nearest increment. If the optionaldecrement_keycode
orincrement_keycode
are set to a javascript string key code (such as “KeyG” or “ArrowLeft”, see https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values), then keydown callbacks will be registered in the GUI that will move the slider bystep
(within the limits) when those buttons are pressed.- Raises
RuntimeError if name has already been added as any type of –
control (e.g., either button or slider) –
- Delete(self: pydrake.geometry.Meshcat, path: str = '') None
Deletes the object at the given
path
as well as all of its children. See meshcat_path for the detailed semantics of deletion.
- DeleteAddedControls(self: pydrake.geometry.Meshcat) None
Removes all buttons and sliders from the GUI that have been registered by this Meshcat instance. It does not clear the default GUI elements set in the meshcat browser (e.g. for cameras and lights).
- DeleteButton(self: pydrake.geometry.Meshcat, name: str) None
Removes the button
name
from the GUI.- Raises
RuntimeError if name is not a registered button. –
- DeleteRecording(self: pydrake.geometry.Meshcat) None
Deletes the current animation holding the recorded frames. Animation options (autoplay, repetitions, etc) will also be reset, and any pointers obtained from get_mutable_recording() will be rendered invalid. This does not* currently remove the animation from Meshcat.
- DeleteSlider(self: pydrake.geometry.Meshcat, name: str) None
Removes the slider
name
from the GUI.- Raises
RuntimeError if name is not a registered slider. –
- Flush(self: pydrake.geometry.Meshcat) None
Blocks the calling thread until all buffered data in the websocket thread has been sent to any connected clients. This can be especially useful when sending many or large mesh files / texture maps, to avoid large “backpressure” and/or simply to make sure that the simulation does not get far ahead of the visualization.
- class Gamepad
Status of a gamepad obtained from the Meshcat javascript client.
- __init__(self: pydrake.geometry.Meshcat.Gamepad, **kwargs) None
- property axes
An array of floating point values representing e.g. analog thumbsticks. Each entry in the array is a floating point value in the range -1.0 – 1.0, representing the axis position from the lowest value (-1.0) to the highest value (1.0).
In the standard gamepad mapping, we have: - axes[0] Left stick x (negative left/positive right) - axes[1] Left stick y (negative up/positive down) - axes[2] Right stick x (negative left/positive right) - axes[3] Right stick y (negative up/positive down)
Note that a stick that is left alone may not output all zeros. https://beej.us/blog/data/javascript-gamepad/ gives some useful advice for applying a deadzone to these values.
- property button_values
An array of floating point values representing analog buttons, such as the triggers on many modern gamepads. The values are normalized to the range [0.0, 1.0], with 0.0 representing a button that is not pressed, and 1.0 representing a button that is fully pressed.
See https://w3c.github.io/gamepad/#dfn-standard-gamepad for the standard mapping of gamepad buttons to this vector.
- property index
An an integer that is auto-incremented to be unique for each device currently connected to the system. If
index.has_value() == false
, then we have not yet received any gamepad status from the Meshcat browser.
- get_mutable_recording(self: pydrake.geometry.Meshcat) drake::geometry::MeshcatAnimation
Returns a mutable reference to this Meshcat’s MeshcatAnimation object. This can be used to set animation properties (like autoplay, the loop mode, number of repetitions, etc). The return value will only remain valid for the lifetime of
this
or until DeleteRecording() is called.
- GetButtonClicks(self: pydrake.geometry.Meshcat, name: str) int
Returns the number of times the button
name
has been clicked in the GUI, from the time that it was added tothis
. If multiple browsers are open, then this number is the cumulative number of clicks in all browsers.- Raises
RuntimeError if name is not a registered button. –
- GetGamepad(self: pydrake.geometry.Meshcat) drake::geometry::Meshcat::Gamepad
Returns the status from the most recently updated gamepad data in the Meshcat. See Gamepad for details on the returned values.
Note that in javascript, gamepads are not detected until users “opt-in” by pressing a gamepad button or moving the thumbstick in the Meshcat window. If no gamepad information is available in javascript, then no messages are sent and the returned gamepad index will not have a value.
Currently Meshcat only attempts to support one gamepad. If multiple gamepads are detected in the same Meshcat window, then only the status of the first connected gamepad in
navigator.GetGamepads()
is returned. If multiple Meshcat windows are connected to this Meshcat instance, and gamepads are being used in multiple windows, then the returned status will be the most recently received status message. Therefore using multiple gamepads simultaneously is not recommended.This feature is provided primarily to support applications where Drake is running on a remote machine (e.g. in the cloud), and the Meshcat javascript in the browser is the only code running on the local machine which has access to the gamepad.
For more details on javascript support for gamepads (or to test that your gamepad is working), see https://beej.us/blog/data/javascript-gamepad/.
- GetNumActiveConnections(self: pydrake.geometry.Meshcat) int
(Advanced) Returns the number of currently-open websocket connections.
- GetRealtimeRate(self: pydrake.geometry.Meshcat) float
Gets the realtime rate that is displayed in the meshcat visualizer stats strip chart. See SetRealtimeRate(). Note that this value might be a smoothing function across multiple calls to SetRealtimeRate() rather than the most recent argument value, in case this class ever adds smoothing capability.
- GetSliderNames(self: pydrake.geometry.Meshcat) list[str]
Returns the names of all sliders.
- GetSliderValue(self: pydrake.geometry.Meshcat, name: str) float
Gets the current
value
of the slidername
.- Raises
RuntimeError if name is not a registered slider. –
- GetTrackedCameraPose(self: pydrake.geometry.Meshcat) Optional[pydrake.math.RigidTransform]
Returns the most recently received camera pose.
A meshcat browser session can be configured to transmit its camera pose. It is enabled by appending a url parameter. For example, if the url for the meshcat server is:
A particular browser can be configured to transmit its camera pose back to Drake by supplying the following url:
http://localhost:7000/?tracked_camera=on
It is possible to use that URL in multiple browsers simultaneously. A particular view will only transmit its camera position when its camera position actually changes. As such, the returned camera pose will reflect the pose of the camera from that most-recently manipulated browser.
std::nullopt is returned if:
No meshcat session has transmitted its camera pose.
The meshcat session that last transmitted its pose is no longer
connected. - The meshcat session transmitting has an orthographic camera.
- HasPath(self: pydrake.geometry.Meshcat, path: str) bool
- class OrthographicCamera
Properties for an orthographic camera in three.js: https://threejs.org/docs/#api/en/cameras/OrthographicCamera
- __init__(self: pydrake.geometry.Meshcat.OrthographicCamera, **kwargs) None
- property bottom
Camera frustum bottom plane.
- property far
Camera frustum far plane.
- property left
Camera frustum left plane.
- property near
Camera frustum near plane.
- property right
Camera frustum right plane.
- property top
Camera frustum top plane.
- property zoom
The zoom factor of the camera.
- class PerspectiveCamera
Properties for a perspective camera in three.js: https://threejs.org/docs/#api/en/cameras/PerspectiveCamera
- __init__(self: pydrake.geometry.Meshcat.PerspectiveCamera, **kwargs) None
- property aspect
Camera frustum aspect ratio.
- property far
Camera frustum far plane.
- property fov
Camera frustum vertical field of view.
- property near
Camera frustum near plane.
- property zoom
The zoom factor of the camera.
- PlotSurface(self: pydrake.geometry.Meshcat, path: str, X: numpy.ndarray[numpy.float64[m, n], flags.f_contiguous], Y: numpy.ndarray[numpy.float64[m, n], flags.f_contiguous], Z: numpy.ndarray[numpy.float64[m, n], flags.f_contiguous], rgba: pydrake.geometry.Rgba = Rgba(r=0.1, g=0.1, b=0.9, a=1.0), wireframe: bool = False, wireframe_line_width: float = 1.0) None
Sets the “object” at
path
to be a triangle surface mesh representing a 3D surface, via an API that roughly follows matplotlib’s plot_surface() method.- Parameter
X
: matrix of
x
coordinate values defining the vertices of the mesh.- Parameter
Y
: matrix of
y
coordinate values.- Parameter
Z
: matrix of
z
coordinate values.- Parameter
rgba
: is the mesh face or wireframe color.
- Parameter
wireframe
: if “true”, then only the triangle edges are visualized, not the faces.
- Parameter
wireframe_line_width
: is the width in pixels. Due to limitations in WebGL implementations, the line width may be 1 regardless of the set value.
Typically, X and Y are obtained via, e.g.
Click to expand C++ code...
constexpr int nx = 15, ny = 11; X = RowVector<double, nx>::LinSpaced(0, 1).replicate<ny, 1>(); Y = Vector<double, ny>::LinSpaced(0, 1).replicate<1, nx>();
in C++ or e.g.
Click to expand C++ code...
xs = np.linspace(0, 1, 15) ys = np.linspace(0, 1, 11) [X, Y] = np.meshgrid(xs, ys)
in Python, and Z is the surface evaluated on each X, Y value.
- Precondition:
X, Y, and Z must be the same shape.
- Parameter
- port(self: pydrake.geometry.Meshcat) int
Returns the port on localhost listening for http connections.
- PublishRecording(self: pydrake.geometry.Meshcat) None
Sends the recording to Meshcat as an animation. The published animation only includes transforms and properties; the objects that they modify must be sent to the visualizer separately (e.g. by calling Publish()).
- ResetRenderMode(self: pydrake.geometry.Meshcat) None
Resets the default camera, camera target, background, grid lines, and axes to their default settings.
- Set2dRenderMode(self: pydrake.geometry.Meshcat, X_WC: pydrake.math.RigidTransform = RigidTransform(R=RotationMatrix([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]), p=[0.0, - 1.0, 0.0]), xmin: float = - 1.0, xmax: float = 1.0, ymin: float = - 1.0, ymax: float = 1.0) None
Applies a number of settings to make Meshcat act as a 2D renderer. The camera is set to an orthographic camera with
X_WC
specifying the pose of the camera in world. The camera looks down the +Cy axis, with +Cz corresponding to positive y in the 2D frame, and -Cx corresponding to positive x in the 2D frame.Additionally sets the background, grid lines, and axes “visible” properties to false.
- SetAnimation(self: pydrake.geometry.Meshcat, animation: drake::geometry::MeshcatAnimation) None
Sets the MeshcatAnimation, which creates a slider interface element to play/pause/rewind through a series of animation frames in the visualizer.
See also StartRecording(), which records supported calls to
this
into a MeshcatAnimation, and PublishRecording(), which calls SetAnimation() with the recording.
- SetCamera(*args, **kwargs)
Overloaded function.
SetCamera(self: pydrake.geometry.Meshcat, camera: drake::geometry::Meshcat::PerspectiveCamera, path: str = ‘/Cameras/default/rotated’) -> None
Sets the Meshcat object on
path
to a perspective camera. We provide a default value ofpath
corresponding to the default camera object in Meshcat.SetCamera(self: pydrake.geometry.Meshcat, camera: drake::geometry::Meshcat::OrthographicCamera, path: str = ‘/Cameras/default/rotated’) -> None
Sets the Meshcat object on
path
to an orthographic camera. We provide a default value ofpath
corresponding to the default camera object in Meshcat.
- SetCameraPose(self: pydrake.geometry.Meshcat, camera_in_world: numpy.ndarray[numpy.float64[3, 1]], target_in_world: numpy.ndarray[numpy.float64[3, 1]]) None
A convenience function for positioning the camera and its view target in the world frame. The camera is placed at
camera_in_world
and looks towardtarget_in_world
. The camera is oriented around this view direction so that the camera’s up vector points in the positive Wz direction as much as possible.Unlike SetCameraTarget() this can be used to orient orthographic cameras as well.
Note
This is Drake’s z-up world frame and not the three.js world frame you’d have to use if you set the “position” on the camera directly.
Warning
The behavior is undefined if camera and target positions are coincident.
- Parameter
camera_in_world
: the position of the camera’s origin C in Drake’s z-up world frame (p_WC).
- Parameter
target_in_world
: the position of the target point T in Drake’s z-up world frame (p_WT).
- Parameter
- SetCameraTarget(self: pydrake.geometry.Meshcat, target_in_world: numpy.ndarray[numpy.float64[3, 1]]) None
Positions the camera’s view target point T to the location in
target_in_world
(p_WT).If the camera is orthographic (i.e., by calling Set2DRenderMode() or SetCamera(OrthographicCamera)), this will have no effect.
Warning
Setting the target position to be coincident with the camera position will lead to undefined behavior.
- Parameter
target_in_world
: the position of the target point T in Drake’s z-up world frame (p_WT).
- Parameter
- SetEnvironmentMap(self: pydrake.geometry.Meshcat, image_path: os.PathLike) None
Sets the environment texture. For objects with physically-based rendering (PBR) material properties (e.g., metallic surfaces), this defines the luminance environment, contributing to total illumination and appearing in reflections.
The image should be of a format typically supported by web browsers: e.g., jpg, png, etc. Furthermore, the image must be an ` equirectangular image <https://en.wikipedia.org/wiki/Equirectangular_projection>`_ (as opposed to a cube-map).
If the path is empty, the environment map will be cleared.
- Raises
if image_path is not empty and the file isn't accessible. –
- Precondition:
If
image_path
names an accessible file, it is an appropriate image type.
- SetLine(self: pydrake.geometry.Meshcat, path: str, vertices: numpy.ndarray[numpy.float64[3, n], flags.f_contiguous], line_width: float = 1.0, rgba: pydrake.geometry.Rgba = Rgba(r=0.1, g=0.1, b=0.1, a=1.0)) None
Sets the “object” at
path
in the scene tree to a piecewise-linear interpolation between thevertices
.- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
vertices
: are the 3D points defining the lines.
- Parameter
line_width
: is the width in pixels. Due to limitations in WebGL implementations, the line width may be 1 regardless of the set value.
- Parameter
rgba
: is the line color.
- Parameter
- SetLineSegments(self: pydrake.geometry.Meshcat, path: str, start: numpy.ndarray[numpy.float64[3, n], flags.f_contiguous], end: numpy.ndarray[numpy.float64[3, n], flags.f_contiguous], line_width: float = 1.0, rgba: pydrake.geometry.Rgba = Rgba(r=0.1, g=0.1, b=0.1, a=1.0)) None
Sets the “object” at
path
in the scene tree to a number of line segments.- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
start
: is a 3-by-N matrix of 3D points defining the start of each segment.
- Parameter
end
: is a 3-by-N matrix of 3D points defining the end of each segment.
- Parameter
line_width
: is the width in pixels. Due to limitations in WebGL implementations, the line width may be 1 regardless of the set value.
- Parameter
rgba
: is the line color.
- Raises
RuntimeError if start.cols != end.cols() –
- Parameter
- SetObject(*args, **kwargs)
Overloaded function.
SetObject(self: pydrake.geometry.Meshcat, path: str, shape: pydrake.geometry.Shape, rgba: pydrake.geometry.Rgba = Rgba(r=0.9, g=0.9, b=0.9, a=1.0)) -> None
Sets the 3D object at a given
path
in the scene tree. Note thatpath`="/foo" will always set an object in the tree at "/foo/<object>". See meshcat_path. Any objects previously set at this `path
will be replaced.- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
shape
: a Shape that specifies the geometry of the object.
- Parameter
rgba
: an Rgba that specifies the (solid) color of the object.
Note
If
shape
is a mesh, the file referred to can be either an .obj file or an embedded .gltf file (it has all geometry data and texture data contained within the single .gltf file).SetObject(self: pydrake.geometry.Meshcat, path: str, cloud: drake::perception::PointCloud, point_size: float = 0.001, rgba: pydrake.geometry.Rgba = Rgba(r=0.9, g=0.9, b=0.9, a=1.0)) -> None
Sets the “object” at a given
path
in the scene tree to bepoint_cloud
. Note thatpath`="/foo" will always set an object in the tree at "/foo/<object>". See meshcat_path. Any objects previously set at this `path
will be replaced.- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
point_cloud
: a perception::PointCloud; if
point_cloud.has_rgbs()
is true, then meshcat will render the colored points.- Parameter
point_size
: is the size of each rendered point.
- Parameter
rgba
: is the default color, which is only used if
point_cloud.has_rgbs() == false
.
SetObject(self: pydrake.geometry.Meshcat, path: str, mesh: pydrake.geometry.TriangleSurfaceMesh, rgba: pydrake.geometry.Rgba = Rgba(r=0.1, g=0.1, b=0.1, a=1.0), wireframe: bool = False, wireframe_line_width: float = 1.0, side: pydrake.geometry.Meshcat.SideOfFaceToRender = <SideOfFaceToRender.kDoubleSide: 2>) -> None
Sets the “object” at
path
in the scene tree to a TriangleSurfaceMesh.- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
mesh
: is a TriangleSurfaceMesh object.
- Parameter
rgba
: is the mesh face or wireframe color.
- Parameter
wireframe
: if “true”, then only the triangle edges are visualized, not the faces.
- Parameter
wireframe_line_width
: is the width in pixels. Due to limitations in WebGL implementations, the line width may be 1 regardless of the set value.
- SetProperty(*args, **kwargs)
Overloaded function.
SetProperty(self: pydrake.geometry.Meshcat, path: str, property: str, value: bool, time_in_recording: Optional[float] = None) -> None
Sets a single named property of the object at the given path. For example,
Click to expand C++ code...
meshcat.SetProperty("/Background", "visible", false);
will turn off the background. See meshcat_path “Meshcat paths” for more details about these properties and how to address them.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path for the semantics.
- Parameter
property
: the string name of the property to set
- Parameter
value
: the new value.
- Parameter
time_in_recording
: (optional). If recording (see StartRecording()), then in addition to publishing the property to any meshcat browsers immediately, this transform is saved to the current animation at
time_in_recording
.
SetProperty(self: pydrake.geometry.Meshcat, path: str, property: str, value: float, time_in_recording: Optional[float] = None) -> None
Sets a single named property of the object at the given path. For example,
Click to expand C++ code...
meshcat.SetProperty("/Lights/DirectionalLight/<object>", "intensity", 1.0);
See meshcat_path “Meshcat paths” for more details about these properties and how to address them.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path for the semantics.
- Parameter
property
: the string name of the property to set
- Parameter
value
: the new value.
- Parameter
time_in_recording
: (optional) the time at which this property should be applied, if Meshcat is current recording (see StartRecording()). If Meshcat is not currently recording, then this value is simply ignored.
SetProperty(self: pydrake.geometry.Meshcat, path: str, property: str, value: list[float], time_in_recording: Optional[float] = None) -> None
Sets a single named property of the object at the given path. For example,
Click to expand C++ code...
meshcat.SetProperty("/Background", "top_color", {1.0, 0.0, 0.0});
See meshcat_path “Meshcat paths” for more details about these properties and how to address them.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path for the semantics.
- Parameter
property
: the string name of the property to set
- Parameter
value
: the new value.
- Parameter
time_in_recording
: (optional) the time at which this property should be applied, if Meshcat is current recording (see StartRecording()). If Meshcat is not currently recording, then this value is simply ignored.
- SetRealtimeRate(self: pydrake.geometry.Meshcat, rate: float) None
Sets the realtime rate that is displayed in the meshcat visualizer stats strip chart. This rate is the ratio between sim time and real world time. 1 indicates the simulator is the same speed as real time. 2 indicates running twice as fast as real time, 0.5 is half speed, etc.
See also
drake::systems::Simulator::set_target_realtime_rate()
- Parameter
rate
: the realtime rate value to be displayed, will be converted to a percentage (multiplied by 100)
- Parameter
- SetSliderValue(self: pydrake.geometry.Meshcat, name: str, value: float) None
Sets the current
value
of the slidername
. value will be truncated to the slider range and rounded to the nearest increment specified by the sliderstep
. This will update the slider element in all connected meshcat browsers.- Raises
RuntimeError if name is not a registered slider. –
- SetTransform(*args, **kwargs)
Overloaded function.
SetTransform(self: pydrake.geometry.Meshcat, path: str, X_ParentPath: pydrake.math.RigidTransform, time_in_recording: Optional[float] = None) -> None
Set the RigidTransform for a given path in the scene tree relative to its parent path. An object’s pose is the concatenation of all of the transforms along its path, so setting the transform of “/foo” will move the objects at “/foo/box1” and “/foo/robots/HAL9000”.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
X_ParentPath
: the relative transform from the path to its immediate parent.
- Parameter
time_in_recording
: (optional). If recording (see StartRecording()), then in addition to publishing the transform to any meshcat browsers immediately, this transform is saved to the current animation at
time_in_recording
.
SetTransform(self: pydrake.geometry.Meshcat, path: str, matrix: numpy.ndarray[numpy.float64[4, 4], flags.f_contiguous]) -> None
Set the homogeneous transform for a given path in the scene tree relative to its parent path. An object’s pose is the concatenation of all of the transforms along its path, so setting the transform of “/foo” will move the objects at “/foo/box1” and “/foo/robots/HAL9000”.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
matrix
: the relative transform from the path to its immediate parent.
Note: Prefer to use the overload which takes a RigidTransformd unless you need the fully parameterized homogeneous transform (which additionally allows scale and sheer).
Note: Meshcat does not properly support non-uniform scaling. See Drake issue #18095.
- SetTriangleColorMesh(self: pydrake.geometry.Meshcat, path: str, vertices: numpy.ndarray[numpy.float64[3, n], flags.f_contiguous], faces: numpy.ndarray[numpy.int32[3, n], flags.f_contiguous], colors: numpy.ndarray[numpy.float64[3, n], flags.f_contiguous], wireframe: bool = False, wireframe_line_width: float = 1.0, side: pydrake.geometry.Meshcat.SideOfFaceToRender = <SideOfFaceToRender.kDoubleSide: 2>) None
Sets the “object” at
path
in the scene tree to a triangular mesh with per-vertex coloring.- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
vertices
: is a 3-by-N matrix of 3D point defining the vertices of the mesh.
- Parameter
faces
: is a 3-by-M integer matrix with each entry denoting an index into vertices and each column denoting one face (aka SurfaceTriangle).
- Parameter
colors
: is a 3-by-N matrix of RGB color values, one color per vertex of the mesh. Color values are in the range [0, 1].
- Parameter
wireframe
: if “true”, then only the triangle edges are visualized, not the faces.
- Parameter
wireframe_line_width
: is the width in pixels. Due to limitations in WebGL implementations, the line width may be 1 regardless of the set value.
- Parameter
- SetTriangleMesh(self: pydrake.geometry.Meshcat, path: str, vertices: numpy.ndarray[numpy.float64[3, n], flags.f_contiguous], faces: numpy.ndarray[numpy.int32[3, n], flags.f_contiguous], rgba: pydrake.geometry.Rgba = Rgba(r=0.1, g=0.1, b=0.1, a=1.0), wireframe: bool = False, wireframe_line_width: float = 1.0, side: pydrake.geometry.Meshcat.SideOfFaceToRender = <SideOfFaceToRender.kDoubleSide: 2>) None
Sets the “object” at
path
in the scene tree to a triangular mesh.- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
vertices
: is a 3-by-N matrix of 3D point defining the vertices of the mesh.
- Parameter
faces
: is a 3-by-M integer matrix with each entry denoting an index into vertices and each column denoting one face (aka SurfaceTriangle).
- Parameter
rgba
: is the mesh face or wireframe color.
- Parameter
wireframe
: if “true”, then only the triangle edges are visualized, not the faces.
- Parameter
wireframe_line_width
: is the width in pixels. Due to limitations in WebGL implementations, the line width may be 1 regardless of the set value.
- Parameter
- class SideOfFaceToRender
Members:
kFrontSide :
kBackSide :
kDoubleSide :
- __init__(self: pydrake.geometry.Meshcat.SideOfFaceToRender, value: int) None
- kBackSide = <SideOfFaceToRender.kBackSide: 1>
- kDoubleSide = <SideOfFaceToRender.kDoubleSide: 2>
- kFrontSide = <SideOfFaceToRender.kFrontSide: 0>
- property name
- property value
- StartRecording(self: pydrake.geometry.Meshcat, frames_per_second: float = 64.0, set_visualizations_while_recording: bool = True) None
Sets a flag indicating that subsequent calls to SetTransform and SetProperty should also be “recorded” into a MeshcatAnimation when their optional time_in_recording argument is supplied. The data in these events will be combined with any frames previously added to the animation; if the same transform/property is set at the same time, then it will overwrite the existing frame in the animation.
- Parameter
set_visualizations_while_recording
: if true, then each method will send the visualization immediately to Meshcat and record the visualization in the animation. Set to false to avoid updating the visualization during recording. One exception is calls to SetObject, which will always be sent to the visualizer immediately (because meshcat animations do not support SetObject).
- Parameter
- StaticHtml(self: pydrake.geometry.Meshcat) str
Returns an HTML string that can be saved to a file for a snapshot of the visualizer and its contents. The HTML can be viewed in the browser without any connection to a Meshcat “server” (e.g.
this
). This is a great way to save and share your 3D content.Note that controls (e.g. sliders and buttons) are not included in the HTML output, because their usefulness relies on a connection to the server.
You can also use your browser to download this file, by typing “/download” on the end of the URL (i.e., accessing
web_url() + "/download"
).
- StopRecording(self: pydrake.geometry.Meshcat) None
Sets a flag to pause/stop recording. When stopped, publish events will not add frames to the animation.
- web_url(self: pydrake.geometry.Meshcat) str
Returns the hosted http URL.
- ws_url(self: pydrake.geometry.Meshcat) str
(Advanced) Returns the ws:// URL for direct connection to the websocket interface. Most users should connect via a browser opened to web_url().
- class pydrake.geometry.MeshcatAnimation
An interface for recording/playback animations in Meshcat. Use Meshcat::SetAnimation to publish a MeshcatAnimation to the visualizer.
Currently, an animation consists of (only) transforms and properties that are set at a particular integer frame number. Although we do not support calls to SetObject/Delete in an animation, you can consider using
SetProperty(frame, path, "visible", true/false)
in your animation to make the object appear or disappear at a particular frame.- __init__(self: pydrake.geometry.MeshcatAnimation, frames_per_second: float = 64.0) None
Constructs the animation object.
- Parameter
frames_per_second
: a positive integer specifying the timing at which the frames are played back.
- Parameter
- autoplay(self: pydrake.geometry.MeshcatAnimation) bool
- clamp_when_finished(self: pydrake.geometry.MeshcatAnimation) bool
- frame(self: pydrake.geometry.MeshcatAnimation, time_from_start: float) int
Uses the frame rate to convert from time to the frame number, using std::floor.
- Precondition:
time
≥ start_time().
- frames_per_second(self: pydrake.geometry.MeshcatAnimation) float
Returns the frame rate at which the animation will be played back.
- loop_mode(self: pydrake.geometry.MeshcatAnimation) drake::geometry::MeshcatAnimation::LoopMode
- class LoopMode
Members:
kLoopOnce : Plays the clip once.
kLoopRepeat : Plays the clip with the chosen number of repetitions, each time
jumping from the end of the clip directly to its beginning.
kLoopPingPong : Plays the clip with the chosen number of repetitions, alternately
playing forward and backward.
- __init__(self: pydrake.geometry.MeshcatAnimation.LoopMode, value: int) None
- kLoopOnce = <LoopMode.kLoopOnce: 2200>
- kLoopPingPong = <LoopMode.kLoopPingPong: 2202>
- kLoopRepeat = <LoopMode.kLoopRepeat: 2201>
- property name
- property value
- repetitions(self: pydrake.geometry.MeshcatAnimation) int
- set_autoplay(self: pydrake.geometry.MeshcatAnimation, play: bool) None
Set the behavior when the animation is first sent to the visualizer. The animation will play immediately iff
play
is true. The default is true.
- set_clamp_when_finished(self: pydrake.geometry.MeshcatAnimation, clamp: bool) None
Sets the behavior at the end of the animation. If true, then the animation will automatically be paused on its last frame. If false, the scene will be reset to before the animation. The default is true.
Note: This setting has no impact if the action is interrupted (it has only an effect if its last loop has really finished).
- set_loop_mode(self: pydrake.geometry.MeshcatAnimation, mode: drake::geometry::MeshcatAnimation::LoopMode) None
Sets the loop behavior on play.
See also
LoopMode for details. The default is kLoopRepeat.
- set_repetitions(self: pydrake.geometry.MeshcatAnimation, repetitions: int) None
Sets the number of repetitions of the animation each time it is played. This number has no effect when the loop mode is set to kLoopOnce.
repetitions
must be a positive integer. The default value is 1.
- SetProperty(*args, **kwargs)
Overloaded function.
SetProperty(self: pydrake.geometry.MeshcatAnimation, frame: int, path: str, property: str, value: bool) -> None
Sets a single named property of the object at the given
path
at the specifiedframe
in the animation.See also
Meshcat::SetProperty.
- Parameter
frame
: a non-negative integer indicating the frame at which this transform is applied.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path for the semantics.
- Parameter
property
: the string name of the property to set
- Parameter
value
: the new value.
- Raises
RuntimeError if this path/property has already been set with a –
different type. –
SetProperty(self: pydrake.geometry.MeshcatAnimation, frame: int, path: str, property: str, value: float) -> None
Sets a single named property of the object at the given
path
at the specifiedframe
in the animation.See also
Meshcat::SetProperty.
- Parameter
frame
: a non-negative integer indicating the frame at which this transform is applied.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path for the semantics.
- Parameter
property
: the string name of the property to set
- Parameter
value
: the new value.
- Raises
RuntimeError if this path/property has already been set with a –
different type. –
SetProperty(self: pydrake.geometry.MeshcatAnimation, frame: int, path: str, property: str, value: list[float]) -> None
Sets a single named property of the object at the given
path
at the specifiedframe
in the animation.See also
Meshcat::SetProperty.
- Parameter
frame
: a non-negative integer indicating the frame at which this transform is applied.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path for the semantics.
- Parameter
property
: the string name of the property to set
- Parameter
value
: the new value.
- Raises
RuntimeError if this path/property has already been set with a –
different type. –
- SetTransform(self: pydrake.geometry.MeshcatAnimation, frame: int, path: str, X_ParentPath: pydrake.math.RigidTransform) None
Set the RigidTransform at
frame
in the animation for a givenpath
in the the scene tree.See also
Meshcat::SetTransform.
- Parameter
frame
: a non-negative integer indicating the frame at which this transform is applied.
- Parameter
path
: a “/”-delimited string indicating the path in the scene tree. See meshcat_path “Meshcat paths” for the semantics.
- Parameter
X_ParentPath
: the relative transform from the path to its immediate parent.
- Raises
RuntimeError if the position or quaternion properties of this path –
have already been set to an incorrect type. –
- Parameter
- class pydrake.geometry.MeshcatCone
Bases:
pydrake.geometry.Shape
Definition of a cone. Its point is at the origin, its height extends in the direction of the frame’s +z axis. Or, more formally: a finite section of a Lorentz cone (aka “second-order cone”), defined by
sqrt(x²/a² + y²/b²) ≤ z; z ∈ [0, height],
where
a
andb
are the lengths of the principal semi-axes of the horizontal section atz=height()
.This shape is currently only supported by Meshcat. It will not appear in any renderings, proximity queries, or other visualizers.
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.MeshcatCone, height: float, a: float = 1.0, b: float = 1.0) -> None
Constructs the parameterized cone.
- Raises
RuntimeError if height, a, or b are not strictly –
positive. –
__init__(self: pydrake.geometry.MeshcatCone, measures: numpy.ndarray[numpy.float64[3, 1]]) -> None
Constructs a cone with a vector of measures: height and principal semi-axes.
- Raises
RuntimeError if the measures are not strictly positive. –
- a(self: pydrake.geometry.MeshcatCone) float
- b(self: pydrake.geometry.MeshcatCone) float
- height(self: pydrake.geometry.MeshcatCone) float
- class pydrake.geometry.MeshcatParams
The set of parameters for configuring Meshcat.
- __init__(self: pydrake.geometry.MeshcatParams, **kwargs) None
- property host
Meshcat will listen only on the given hostname (e.g., “localhost”). If “*” is specified, then it will listen on all interfaces. If empty, an appropriate default value will be chosen (currently “*”).
- property initial_properties
Configures the initial conditions for Meshcat. These properties will be applied immediately during construction. This can be used to change defaults such as background, lighting, etc.
In other words, instead calling the Meshcat() constructor and then immediately making a bunch of SetProperty(path, property, value) calls to configure the newly-created object, instead you can append those (path, property, value) to to this list, and the Meshcat() constructor will take care of it.
- property port
Meshcat will listen on the given http
port
. If no port is specified, then it will listen on the first available port starting at 7000 (up to 7999). If port 0 is specified, it will listen on an arbitrary “ephemeral” port.- Precondition:
We require
port
== 0 ||port
>= 1024.
- class PropertyTuple
A helper struct for the
initial_properties
params. The members follow the same semantics as calls to Meshcat::SetProperty(path, property, value).- __init__(self: pydrake.geometry.MeshcatParams.PropertyTuple, **kwargs) None
- property path
- property property
- property value
- property show_stats_plot
Determines whether or not to display the stats plot widget in the Meshcat user interface. This plot including realtime rate and WebGL render statistics.
- property web_url_pattern
The
web_url_pattern
may be used to change the web_url() (and therefore the ws_url()) reported by Meshcat. This may be useful in case Meshcat sits behind a firewall or proxy.The pattern follows the std::format specification language, except that
arg-id
substitutions are performed using named arguments instead of positional indices.There are two arguments available to the pattern: -
{port}
will be substituted with the Meshcat server’s listen port number; -{host}
will be substituted with this params structure’shost
field, or else with “localhost” in case thehost
was one of the placeholders for “all interfaces”.
- class pydrake.geometry.MeshcatPointCloudVisualizer
Bases:
pydrake.systems.framework.LeafSystem
MeshcatPointCloudVisualizer is a systems::LeafSystem that publishes a perception::PointCloud from its input port to Meshcat.
cloud→ X_ParentCloud→ MeshcatPointCloudVisualizer The PointCloud on the
cloud
input port must have XYZ values. RGB values are optional. The optional input portX_ParentCloud
sets the MeshcatTransform at the path representing thecloud
. If it is not connected, then we setX_ParentCloud
to the identity transform.Note
This class is templated; see
MeshcatPointCloudVisualizer_
for the list of instantiations.- __init__(self: pydrake.geometry.MeshcatPointCloudVisualizer, meshcat: pydrake.geometry.Meshcat, path: str, publish_period: float = 0.03125) None
Creates an instance of MeshcatPointCloudVisualizer
- Parameter
meshcat
: is a shared Meshcat instance.
- Parameter
path
: is the Meshcat path (see meshcat_path)
- Parameter
publish_period
: is the duration (in simulation seconds) between updates sent to the visualizer. It must be non-negative.
- Parameter
- cloud_input_port(self: pydrake.geometry.MeshcatPointCloudVisualizer) pydrake.systems.framework.InputPort
Returns the RigidTransform-valued input port.
- Delete(self: pydrake.geometry.MeshcatPointCloudVisualizer) None
Calls Meshcat::Delete(path), where
path
is the value passed in the constructor.
- pose_input_port(self: pydrake.geometry.MeshcatPointCloudVisualizer) pydrake.systems.framework.InputPort
Returns the PointCloud-valued input port.
- set_default_rgba(self: pydrake.geometry.MeshcatPointCloudVisualizer, arg0: pydrake.geometry.Rgba) None
Sets the default color, which is applied to all points only if
has_rgbs() == false
for the cloud on the input port.
- set_point_size(self: pydrake.geometry.MeshcatPointCloudVisualizer, arg0: float) None
Sets the size of each point in the cloud. The default is 0.001. The units are undocumented in threejs (https://threejs.org/docs/index.html?q=PointsMaterial#api/en/materials/PointsMaterial.size), but we believe they are in meters.
- template pydrake.geometry.MeshcatPointCloudVisualizer_
Instantiations:
MeshcatPointCloudVisualizer_[float]
,MeshcatPointCloudVisualizer_[AutoDiffXd]
- class pydrake.geometry.MeshcatPointCloudVisualizer_[AutoDiffXd]
Bases:
pydrake.systems.framework.LeafSystem_[AutoDiffXd]
MeshcatPointCloudVisualizer is a systems::LeafSystem that publishes a perception::PointCloud from its input port to Meshcat.
cloud→ X_ParentCloud→ MeshcatPointCloudVisualizer The PointCloud on the
cloud
input port must have XYZ values. RGB values are optional. The optional input portX_ParentCloud
sets the MeshcatTransform at the path representing thecloud
. If it is not connected, then we setX_ParentCloud
to the identity transform.- __init__(self: pydrake.geometry.MeshcatPointCloudVisualizer_[AutoDiffXd], meshcat: pydrake.geometry.Meshcat, path: str, publish_period: float = 0.03125) None
Creates an instance of MeshcatPointCloudVisualizer
- Parameter
meshcat
: is a shared Meshcat instance.
- Parameter
path
: is the Meshcat path (see meshcat_path)
- Parameter
publish_period
: is the duration (in simulation seconds) between updates sent to the visualizer. It must be non-negative.
- Parameter
- cloud_input_port(self: pydrake.geometry.MeshcatPointCloudVisualizer_[AutoDiffXd]) pydrake.systems.framework.InputPort_[AutoDiffXd]
Returns the RigidTransform-valued input port.
- Delete(self: pydrake.geometry.MeshcatPointCloudVisualizer_[AutoDiffXd]) None
Calls Meshcat::Delete(path), where
path
is the value passed in the constructor.
- pose_input_port(self: pydrake.geometry.MeshcatPointCloudVisualizer_[AutoDiffXd]) pydrake.systems.framework.InputPort_[AutoDiffXd]
Returns the PointCloud-valued input port.
- set_default_rgba(self: pydrake.geometry.MeshcatPointCloudVisualizer_[AutoDiffXd], arg0: pydrake.geometry.Rgba) None
Sets the default color, which is applied to all points only if
has_rgbs() == false
for the cloud on the input port.
- set_point_size(self: pydrake.geometry.MeshcatPointCloudVisualizer_[AutoDiffXd], arg0: float) None
Sets the size of each point in the cloud. The default is 0.001. The units are undocumented in threejs (https://threejs.org/docs/index.html?q=PointsMaterial#api/en/materials/PointsMaterial.size), but we believe they are in meters.
- class pydrake.geometry.MeshcatVisualizer
Bases:
pydrake.systems.framework.LeafSystem
A system wrapper for Meshcat that publishes the current state of a SceneGraph instance (whose QueryObject-valued output port is connected to this system’s input port). While this system will add geometry to Meshcat, the Meshcat instance is also available for users to add their own visualization alongside the MeshcatVisualizer visualizations. This can be enormously valuable for impromptu visualizations.
query_object→ MeshcatVisualizer The system uses the versioning mechanism provided by SceneGraph to detect changes to the geometry so that a change in SceneGraph’s data will propagate to Meshcat.
By default, MeshcatVisualizer visualizes geometries with the illustration role (see geometry_roles for more details). It can be configured to visualize geometries with other roles. Only one role can be specified. See DrakeVisualizer which uses the same mechanisms for more details.
Warning
MeshcatVisualizer does not support Context-per-thread parallelism. This is because of limitations in both Meshcat and MeshcatVisualizer. We may generalize this in the future if Meshcat limitations are removed.
Instances of MeshcatVisualizer created by scalar-conversion will publish to the same Meshcat instance.
Note
This class is templated; see
MeshcatVisualizer_
for the list of instantiations.- __init__(self: pydrake.geometry.MeshcatVisualizer, meshcat: pydrake.geometry.Meshcat, params: pydrake.geometry.MeshcatVisualizerParams = MeshcatVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), prefix='visualizer', delete_on_initialization_event=True, enable_alpha_slider=False, initial_alpha_slider_value=1.0, visible_by_default=True, show_hydroelastic=False, include_unspecified_accepting=True)) None
Creates an instance of MeshcatVisualizer.
- Parameter
meshcat
: A Meshcat instance. This class will assume shared ownership for the lifetime of the object.
- Parameter
params
: The set of parameters to control this system’s behavior.
- Raises
RuntimeError if params.publish_period <= 0. –
RuntimeError if params.role == Role::kUnassigned. –
- Parameter
- static AddToBuilder(*args, **kwargs)
Overloaded function.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder, scene_graph: pydrake.geometry.SceneGraph, meshcat: pydrake.geometry.Meshcat, params: pydrake.geometry.MeshcatVisualizerParams = MeshcatVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), prefix=’visualizer’, delete_on_initialization_event=True, enable_alpha_slider=False, initial_alpha_slider_value=1.0, visible_by_default=True, show_hydroelastic=False, include_unspecified_accepting=True)) -> pydrake.geometry.MeshcatVisualizer
Adds a MeshcatVisualizer and connects it to the given SceneGraph’s QueryObject-valued output port. See MeshcatVisualizer::MeshcatVisualizer(MeshcatVisualizer*, MeshcatVisualizerParams) for details. The MeshcatVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder, query_object_port: pydrake.systems.framework.OutputPort, meshcat: pydrake.geometry.Meshcat, params: pydrake.geometry.MeshcatVisualizerParams = MeshcatVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), prefix=’visualizer’, delete_on_initialization_event=True, enable_alpha_slider=False, initial_alpha_slider_value=1.0, visible_by_default=True, show_hydroelastic=False, include_unspecified_accepting=True)) -> pydrake.geometry.MeshcatVisualizer
Adds a MeshcatVisualizer and connects it to the given QueryObject-valued output port. See MeshcatVisualizer::MeshcatVisualizer(MeshcatVisualizer*, MeshcatVisualizerParams) for details. The MeshcatVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
- Delete(self: pydrake.geometry.MeshcatVisualizer) None
Calls Meshcat::Delete(std::string path), with the path set to MeshcatVisualizerParams::prefix. Since this visualizer will only ever add geometry under this prefix, this will remove all geometry/transforms added by the visualizer, or by a previous instance of this visualizer using the same prefix. Use MeshcatVisualizer::delete_on_initialization_event to determine whether this should be called on initialization.
- DeleteRecording(self: pydrake.geometry.MeshcatVisualizer) None
Convenience function that calls Meshcat::DeleteRecording on the underlying Meshcat object; refer to Meshcat::DeleteRecording for full documentation.
- get_mutable_recording(self: pydrake.geometry.MeshcatVisualizer) pydrake.geometry.MeshcatAnimation
Convenience function that calls Meshcat::get_mutable_recording on the underlying Meshcat object; refer to Meshcat::get_mutable_recording for full documentation.
- PublishRecording(self: pydrake.geometry.MeshcatVisualizer) None
Convenience function that calls Meshcat::PublishRecording on the underlying Meshcat object; refer to Meshcat::PublishRecording for full documentation.
- query_object_input_port(self: pydrake.geometry.MeshcatVisualizer) pydrake.systems.framework.InputPort
Returns the QueryObject-valued input port. It should be connected to SceneGraph’s QueryObject-valued output port. Failure to do so will cause a runtime error when attempting to broadcast messages.
- ResetRealtimeRateCalculator(self: pydrake.geometry.MeshcatVisualizer) None
Resets the realtime rate calculator. Calculation will resume on the next periodic publish event. This is useful for correcting the realtime rate after simulation is resumed from a paused state, etc.
- StartRecording(self: pydrake.geometry.MeshcatVisualizer, set_transforms_while_recording: bool = True) pydrake.geometry.MeshcatAnimation
Convenience function that calls Meshcat::StartRecording on the underlying Meshcat object, with
frames_per_second = 1 / publish_period
; refer to Meshcat::StartRecording for full documentation.
- StopRecording(self: pydrake.geometry.MeshcatVisualizer) None
Convenience function that calls Meshcat::StopRecording on the underlying Meshcat object; refer to Meshcat::StopRecording for full documentation.
- template pydrake.geometry.MeshcatVisualizer_
Instantiations:
MeshcatVisualizer_[float]
,MeshcatVisualizer_[AutoDiffXd]
- class pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]
Bases:
pydrake.systems.framework.LeafSystem_[AutoDiffXd]
A system wrapper for Meshcat that publishes the current state of a SceneGraph instance (whose QueryObject-valued output port is connected to this system’s input port). While this system will add geometry to Meshcat, the Meshcat instance is also available for users to add their own visualization alongside the MeshcatVisualizer visualizations. This can be enormously valuable for impromptu visualizations.
query_object→ MeshcatVisualizer The system uses the versioning mechanism provided by SceneGraph to detect changes to the geometry so that a change in SceneGraph’s data will propagate to Meshcat.
By default, MeshcatVisualizer visualizes geometries with the illustration role (see geometry_roles for more details). It can be configured to visualize geometries with other roles. Only one role can be specified. See DrakeVisualizer which uses the same mechanisms for more details.
Warning
MeshcatVisualizer does not support Context-per-thread parallelism. This is because of limitations in both Meshcat and MeshcatVisualizer. We may generalize this in the future if Meshcat limitations are removed.
Instances of MeshcatVisualizer created by scalar-conversion will publish to the same Meshcat instance.
- __init__(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd], meshcat: pydrake.geometry.Meshcat, params: pydrake.geometry.MeshcatVisualizerParams = MeshcatVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), prefix='visualizer', delete_on_initialization_event=True, enable_alpha_slider=False, initial_alpha_slider_value=1.0, visible_by_default=True, show_hydroelastic=False, include_unspecified_accepting=True)) None
Creates an instance of MeshcatVisualizer.
- Parameter
meshcat
: A Meshcat instance. This class will assume shared ownership for the lifetime of the object.
- Parameter
params
: The set of parameters to control this system’s behavior.
- Raises
RuntimeError if params.publish_period <= 0. –
RuntimeError if params.role == Role::kUnassigned. –
- Parameter
- static AddToBuilder(*args, **kwargs)
Overloaded function.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], scene_graph: pydrake.geometry.SceneGraph_[AutoDiffXd], meshcat: pydrake.geometry.Meshcat, params: pydrake.geometry.MeshcatVisualizerParams = MeshcatVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), prefix=’visualizer’, delete_on_initialization_event=True, enable_alpha_slider=False, initial_alpha_slider_value=1.0, visible_by_default=True, show_hydroelastic=False, include_unspecified_accepting=True)) -> pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]
Adds a MeshcatVisualizer and connects it to the given SceneGraph’s QueryObject-valued output port. See MeshcatVisualizer::MeshcatVisualizer(MeshcatVisualizer*, MeshcatVisualizerParams) for details. The MeshcatVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
AddToBuilder(builder: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], query_object_port: pydrake.systems.framework.OutputPort_[AutoDiffXd], meshcat: pydrake.geometry.Meshcat, params: pydrake.geometry.MeshcatVisualizerParams = MeshcatVisualizerParams(publish_period=0.015625, role=<Role.kIllustration: 2>, default_color=Rgba(r=0.9, g=0.9, b=0.9, a=1.0), prefix=’visualizer’, delete_on_initialization_event=True, enable_alpha_slider=False, initial_alpha_slider_value=1.0, visible_by_default=True, show_hydroelastic=False, include_unspecified_accepting=True)) -> pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]
Adds a MeshcatVisualizer and connects it to the given QueryObject-valued output port. See MeshcatVisualizer::MeshcatVisualizer(MeshcatVisualizer*, MeshcatVisualizerParams) for details. The MeshcatVisualizer’s name (see systems::SystemBase::set_name) will be set to a sensible default value, unless the default name was already in use by another system.
- Delete(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]) None
Calls Meshcat::Delete(std::string path), with the path set to MeshcatVisualizerParams::prefix. Since this visualizer will only ever add geometry under this prefix, this will remove all geometry/transforms added by the visualizer, or by a previous instance of this visualizer using the same prefix. Use MeshcatVisualizer::delete_on_initialization_event to determine whether this should be called on initialization.
- DeleteRecording(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]) None
Convenience function that calls Meshcat::DeleteRecording on the underlying Meshcat object; refer to Meshcat::DeleteRecording for full documentation.
- get_mutable_recording(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]) pydrake.geometry.MeshcatAnimation
Convenience function that calls Meshcat::get_mutable_recording on the underlying Meshcat object; refer to Meshcat::get_mutable_recording for full documentation.
- PublishRecording(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]) None
Convenience function that calls Meshcat::PublishRecording on the underlying Meshcat object; refer to Meshcat::PublishRecording for full documentation.
- query_object_input_port(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]) pydrake.systems.framework.InputPort_[AutoDiffXd]
Returns the QueryObject-valued input port. It should be connected to SceneGraph’s QueryObject-valued output port. Failure to do so will cause a runtime error when attempting to broadcast messages.
- ResetRealtimeRateCalculator(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]) None
Resets the realtime rate calculator. Calculation will resume on the next periodic publish event. This is useful for correcting the realtime rate after simulation is resumed from a paused state, etc.
- StartRecording(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd], set_transforms_while_recording: bool = True) pydrake.geometry.MeshcatAnimation
Convenience function that calls Meshcat::StartRecording on the underlying Meshcat object, with
frames_per_second = 1 / publish_period
; refer to Meshcat::StartRecording for full documentation.
- StopRecording(self: pydrake.geometry.MeshcatVisualizer_[AutoDiffXd]) None
Convenience function that calls Meshcat::StopRecording on the underlying Meshcat object; refer to Meshcat::StopRecording for full documentation.
- class pydrake.geometry.MeshcatVisualizerParams
The set of parameters for configuring MeshcatVisualizer.
- __init__(self: pydrake.geometry.MeshcatVisualizerParams, **kwargs) None
- property default_color
The color to apply to any geometry that hasn’t defined one.
- property delete_on_initialization_event
Determines whether to send a Meshcat::Delete(prefix) message on an initialization event to remove any visualizations e.g. from a previous simulation. See declare_initialization_events “Declare initialization events” for more information.
- property enable_alpha_slider
Determines whether to enable the alpha slider for geometry display.
- property include_unspecified_accepting
(Advanced) For a given geometry, if the GeometryProperties for our
role
has the property(meshcat, accepting)
then the visualizer will show the geometry only if the property’s value matches ourprefix
. If that property is absent then the geometry will be shown only ifinclude_unspecified_accepting
is true.
- property initial_alpha_slider_value
Initial alpha slider value. This value should lie in the range [0, 1]. Furthermore, the slider value is quantized which means the value used here will be replaced with the nearest quantized value supported by the slider implementation.
- property prefix
A prefix to add to the path for all objects and transforms curated by the MeshcatVisualizer. It can be an absolute path or relative path. If relative, this
prefix
will be appended to the Meshcatprefix
based on the standard path semantics in Meshcat. See meshcat_path “Meshcat paths” for details.
- property publish_period
The duration (in simulation seconds) between attempts to update poses in the visualizer. (To help avoid small simulation time steps, we use a default period that has an exact representation in binary floating point; see drake#15021 for details.)
- property role
The role of the geometries to be sent to the visualizer.
- property show_hydroelastic
When using the hydroelastic contact model, collision geometries that are declared as geometric primitives are frequently represented by some discretely tessellated mesh when computing contact. It can be quite helpful in assessing contact behavior to visualize these discrete meshes (in place of the idealized primitives).
To visualize these representations it is necessary to request visualization of geometries with the Role::kProximity role (see the role field). It is further necessary to explicitly request the hydroelastic meshes where available (setting show_hydroelastic to
True
).Setting this
show_hydroelastic
toTrue
will have no apparent effect if none of the collision meshes have a hydroelastic mesh associated with them.This option is ignored by MeshcatVisualizer<T> when T is not
double
, e.g. if T == AutoDiffXd.
- property visible_by_default
Determines whether our meshcat path should be default to being visible.
- class pydrake.geometry.NullTexture
(Internal use only) A place holder indicating that no texture has been provided for environment map (and, therefore, no environment map).
- __init__(self: pydrake.geometry.NullTexture, **kwargs) None
- class pydrake.geometry.PenetrationAsPointPair
A characterization of the intersection of two penetrating geometries. The characterization consists of a pair of points and a normal. The points represent a point on each geometry that most deeply penetrates the other geometry (in the normal direction). For convenience, the penetration depth is provided and is equal to:
depth =
(p_WCb - p_WCa) ⋅ nhat_BA_W
(depth is strictly positive when there is penetration and otherwise not defined.)
- Template parameter
T
: The underlying scalar type. Must be a valid Eigen scalar.
Note
This class is templated; see
PenetrationAsPointPair_
for the list of instantiations.- __init__(self: pydrake.geometry.PenetrationAsPointPair, **kwargs) None
- property depth
The penetration depth.
- property id_A
The id of the first geometry in the contact.
- property id_B
The id of the second geometry in the contact.
- property nhat_BA_W
The unit-length normal which defines the penetration direction, pointing from geometry B into geometry A, measured and expressed in the world frame. It approximates the normal to the plane on which the contact patch lies.
- property p_WCa
The point on A that most deeply penetrates B, measured and expressed in the world frame.
- property p_WCb
The point on B that most deeply penetrates A, measured and expressed in the world frame.
- Template parameter
- template pydrake.geometry.PenetrationAsPointPair_
Instantiations:
PenetrationAsPointPair_[float]
,PenetrationAsPointPair_[AutoDiffXd]
,PenetrationAsPointPair_[Expression]
- class pydrake.geometry.PenetrationAsPointPair_[AutoDiffXd]
A characterization of the intersection of two penetrating geometries. The characterization consists of a pair of points and a normal. The points represent a point on each geometry that most deeply penetrates the other geometry (in the normal direction). For convenience, the penetration depth is provided and is equal to:
depth =
(p_WCb - p_WCa) ⋅ nhat_BA_W
(depth is strictly positive when there is penetration and otherwise not defined.)
- Template parameter
T
: The underlying scalar type. Must be a valid Eigen scalar.
- __init__(self: pydrake.geometry.PenetrationAsPointPair_[AutoDiffXd], **kwargs) None
- property depth
The penetration depth.
- property id_A
The id of the first geometry in the contact.
- property id_B
The id of the second geometry in the contact.
- property nhat_BA_W
The unit-length normal which defines the penetration direction, pointing from geometry B into geometry A, measured and expressed in the world frame. It approximates the normal to the plane on which the contact patch lies.
- property p_WCa
The point on A that most deeply penetrates B, measured and expressed in the world frame.
- property p_WCb
The point on B that most deeply penetrates A, measured and expressed in the world frame.
- Template parameter
- class pydrake.geometry.PenetrationAsPointPair_[Expression]
A characterization of the intersection of two penetrating geometries. The characterization consists of a pair of points and a normal. The points represent a point on each geometry that most deeply penetrates the other geometry (in the normal direction). For convenience, the penetration depth is provided and is equal to:
depth =
(p_WCb - p_WCa) ⋅ nhat_BA_W
(depth is strictly positive when there is penetration and otherwise not defined.)
- Template parameter
T
: The underlying scalar type. Must be a valid Eigen scalar.
- __init__(self: pydrake.geometry.PenetrationAsPointPair_[Expression], **kwargs) None
- property depth
The penetration depth.
- property id_A
The id of the first geometry in the contact.
- property id_B
The id of the second geometry in the contact.
- property nhat_BA_W
The unit-length normal which defines the penetration direction, pointing from geometry B into geometry A, measured and expressed in the world frame. It approximates the normal to the plane on which the contact patch lies.
- property p_WCa
The point on A that most deeply penetrates B, measured and expressed in the world frame.
- property p_WCb
The point on B that most deeply penetrates A, measured and expressed in the world frame.
- Template parameter
- class pydrake.geometry.PerceptionProperties
Bases:
pydrake.geometry.GeometryProperties
The set of properties for geometry used in a “perception” role.
Examples of functionality that depends on the perception role: - render::RenderEngineVtk
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.PerceptionProperties) -> None
__init__(self: pydrake.geometry.PerceptionProperties, other: pydrake.geometry.PerceptionProperties) -> None
Creates a copy of the properties
- class pydrake.geometry.PolygonSurfaceMesh
PolygonSurfaceMesh represents a surface comprised of polygonal elements (three or more sides).
Note
This class is templated; see
PolygonSurfaceMesh_
for the list of instantiations.- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.PolygonSurfaceMesh) -> None
Advanced() Constructs an empty mesh. This enables compatibility with STL container types and facilitates some unit tests. Otherwise, it shouldn’t be used.
__init__(self: pydrake.geometry.PolygonSurfaceMesh, face_data: list[int], vertices: list[numpy.ndarray[numpy.float64[3, 1]]]) -> None
Constructs a mesh from specified vertex and mesh data.
The vertices are simply a vector of position vectors (interpreted as being measured and expressed in the mesh’s frame M).
The polygon data is more complex. Syntactically, it is a sequence of integers which encodes P polygons. Each polygon can have an arbitrary number of vertices. The encoding of the P polygons is as follows:
|c₁|v₁₀|v₁₁|…|cᵢ|cᵢ₀|cᵢ₁|…|cₚ|cₚ₀|cₚ₁|…|
Each polygon is defined in sequence. The definition consists of an integer indicating the number of vertices in that polygon (c₁, cᵢ, and cₘ in the illustration above). The next cᵢ integers in the sequence are zero-based indices into the vector of vertex positions (indicating which vertices the polygon spans). The vertex indices are sorted such that the plane normal found by applying the right-handed rule is used as the face normal.
This implies the following: Polygon one: Located at index i₁ = 0 in
face_data
. c₁ = face_data[i₁] is the number of vertices in polygon one. Polygon two: Located at index i₂ = i₁ + c₁ + 1 inface_data
. c₂ = face_data[i₂] is the number of vertices in polygon zero. Polygon j: Located at index iⱼ = iⱼ₋₁ + cⱼ₋₁ + 1 cⱼ = face_data[iⱼ]The polygons must all be planar and convex.
- Parameter
face_data
: The sequence of counts and indices which encode the faces of the mesh (see above).
- Parameter
vertices
: The vertex positions, measured and expressed in this mesh’s frame.
- Precondition:
The indices in
face_data
all refer to valid indices intovertices
.
Note
If
face_data
includes a zero-area polygon, that polygon will have a non-NaN centroid chosen arbitrarily. For hydroelastics, this is acceptable because its zero area will neutralize its contribution to computation of contact wrench. If all polygons have zero area, the mesh’s centroid will be chosen arbitrarily as well.
- area(self: pydrake.geometry.PolygonSurfaceMesh, f: int) float
Returns area of a polygonal element.
- Precondition:
f ∈ {0, 1, 2, …, num_faces()-1}.
- CalcBoundingBox(self: pydrake.geometry.PolygonSurfaceMesh) tuple[numpy.ndarray[numpy.float64[3, 1]], numpy.ndarray[numpy.float64[3, 1]]]
Calculates the axis-aligned bounding box of this surface mesh M.
- Returns
the center and the size vector of the box expressed in M’s frame.
- centroid(self: pydrake.geometry.PolygonSurfaceMesh) numpy.ndarray[numpy.float64[3, 1]]
Returns the geometric centroid of this mesh measured and expressed in the mesh’s frame M. (M is the frame in which this mesh’s vertices are measured and expressed.) Note that the centroid is not necessarily a point on the surface. If the total mesh area is exactly zero, we define the centroid to be (0,0,0).
- element(self: pydrake.geometry.PolygonSurfaceMesh, e: int) pydrake.geometry.SurfacePolygon
Returns the polygonal element identified by the given index
e
.- Precondition:
e ∈ {0, 1, 2, …, num_faces()-1}.
- element_centroid(self: pydrake.geometry.PolygonSurfaceMesh, e: int) numpy.ndarray[numpy.float64[3, 1]]
Returns the geometric centroid of the element indicated be index
e
, measured and expressed in the mesh’s frame M.- Precondition:
f ∈ {0, 1, 2, …, num_faces()-1}.
- Equal(self: pydrake.geometry.PolygonSurfaceMesh, mesh: pydrake.geometry.PolygonSurfaceMesh) bool
Checks to see whether the given PolygonSurfaceMesh object is equal via deep exact comparison. NaNs are treated as not equal as per the IEEE standard.
- Parameter
mesh
: The mesh for comparison.
- Returns
True
if the given mesh is equal.
- Parameter
- face_data(self: pydrake.geometry.PolygonSurfaceMesh) list[int]
- face_normal(self: pydrake.geometry.PolygonSurfaceMesh, f: int) numpy.ndarray[numpy.float64[3, 1]]
Returns the unit face normal vector of a polygon. It respects the right-handed normal rule. A near-zero-area triangle may get an unreliable normal vector. A zero-area triangle will get a zero vector.
- Precondition:
f ∈ {0, 1, 2, …, num_faces()-1}.
- num_elements(self: pydrake.geometry.PolygonSurfaceMesh) int
Returns the number of elements in the mesh. For PolygonSurfaceMesh, an element is a polygon. Returns the same number as num_faces() and enables mesh consumers to be templated on mesh type.
- num_faces(self: pydrake.geometry.PolygonSurfaceMesh) int
Returns the number of polygonal elements in the mesh.
- num_vertices(self: pydrake.geometry.PolygonSurfaceMesh) int
Returns the number of vertices in the mesh.
- total_area(self: pydrake.geometry.PolygonSurfaceMesh) float
Returns the total area of all the faces of this surface mesh.
- vertex(self: pydrake.geometry.PolygonSurfaceMesh, v: int) numpy.ndarray[numpy.float64[3, 1]]
Returns the vertex identified by the given index
v
.- Precondition:
v ∈ {0, 1, 2, …, num_vertices()-1}.
- template pydrake.geometry.PolygonSurfaceMesh_
Instantiations:
PolygonSurfaceMesh_[float]
,PolygonSurfaceMesh_[AutoDiffXd]
- class pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]
PolygonSurfaceMesh represents a surface comprised of polygonal elements (three or more sides).
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) -> None
Advanced() Constructs an empty mesh. This enables compatibility with STL container types and facilitates some unit tests. Otherwise, it shouldn’t be used.
__init__(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd], face_data: list[int], vertices: list[numpy.ndarray[object[3, 1]]]) -> None
Constructs a mesh from specified vertex and mesh data.
The vertices are simply a vector of position vectors (interpreted as being measured and expressed in the mesh’s frame M).
The polygon data is more complex. Syntactically, it is a sequence of integers which encodes P polygons. Each polygon can have an arbitrary number of vertices. The encoding of the P polygons is as follows:
|c₁|v₁₀|v₁₁|…|cᵢ|cᵢ₀|cᵢ₁|…|cₚ|cₚ₀|cₚ₁|…|
Each polygon is defined in sequence. The definition consists of an integer indicating the number of vertices in that polygon (c₁, cᵢ, and cₘ in the illustration above). The next cᵢ integers in the sequence are zero-based indices into the vector of vertex positions (indicating which vertices the polygon spans). The vertex indices are sorted such that the plane normal found by applying the right-handed rule is used as the face normal.
This implies the following: Polygon one: Located at index i₁ = 0 in
face_data
. c₁ = face_data[i₁] is the number of vertices in polygon one. Polygon two: Located at index i₂ = i₁ + c₁ + 1 inface_data
. c₂ = face_data[i₂] is the number of vertices in polygon zero. Polygon j: Located at index iⱼ = iⱼ₋₁ + cⱼ₋₁ + 1 cⱼ = face_data[iⱼ]The polygons must all be planar and convex.
- Parameter
face_data
: The sequence of counts and indices which encode the faces of the mesh (see above).
- Parameter
vertices
: The vertex positions, measured and expressed in this mesh’s frame.
- Precondition:
The indices in
face_data
all refer to valid indices intovertices
.
Note
If
face_data
includes a zero-area polygon, that polygon will have a non-NaN centroid chosen arbitrarily. For hydroelastics, this is acceptable because its zero area will neutralize its contribution to computation of contact wrench. If all polygons have zero area, the mesh’s centroid will be chosen arbitrarily as well.
- area(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd], f: int) pydrake.autodiffutils.AutoDiffXd
Returns area of a polygonal element.
- Precondition:
f ∈ {0, 1, 2, …, num_faces()-1}.
- CalcBoundingBox(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) tuple[numpy.ndarray[object[3, 1]], numpy.ndarray[object[3, 1]]]
Calculates the axis-aligned bounding box of this surface mesh M.
- Returns
the center and the size vector of the box expressed in M’s frame.
- centroid(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) numpy.ndarray[object[3, 1]]
Returns the geometric centroid of this mesh measured and expressed in the mesh’s frame M. (M is the frame in which this mesh’s vertices are measured and expressed.) Note that the centroid is not necessarily a point on the surface. If the total mesh area is exactly zero, we define the centroid to be (0,0,0).
- element(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd], e: int) pydrake.geometry.SurfacePolygon
Returns the polygonal element identified by the given index
e
.- Precondition:
e ∈ {0, 1, 2, …, num_faces()-1}.
- element_centroid(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd], e: int) numpy.ndarray[object[3, 1]]
Returns the geometric centroid of the element indicated be index
e
, measured and expressed in the mesh’s frame M.- Precondition:
f ∈ {0, 1, 2, …, num_faces()-1}.
- Equal(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd], mesh: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) bool
Checks to see whether the given PolygonSurfaceMesh object is equal via deep exact comparison. NaNs are treated as not equal as per the IEEE standard.
- Parameter
mesh
: The mesh for comparison.
- Returns
True
if the given mesh is equal.
- Parameter
- face_data(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) list[int]
- face_normal(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd], f: int) numpy.ndarray[object[3, 1]]
Returns the unit face normal vector of a polygon. It respects the right-handed normal rule. A near-zero-area triangle may get an unreliable normal vector. A zero-area triangle will get a zero vector.
- Precondition:
f ∈ {0, 1, 2, …, num_faces()-1}.
- num_elements(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) int
Returns the number of elements in the mesh. For PolygonSurfaceMesh, an element is a polygon. Returns the same number as num_faces() and enables mesh consumers to be templated on mesh type.
- num_faces(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) int
Returns the number of polygonal elements in the mesh.
- num_vertices(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) int
Returns the number of vertices in the mesh.
- total_area(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd]) pydrake.autodiffutils.AutoDiffXd
Returns the total area of all the faces of this surface mesh.
- vertex(self: pydrake.geometry.PolygonSurfaceMesh_[AutoDiffXd], v: int) numpy.ndarray[object[3, 1]]
Returns the vertex identified by the given index
v
.- Precondition:
v ∈ {0, 1, 2, …, num_vertices()-1}.
- class pydrake.geometry.PolygonSurfaceMeshFieldLinear
MeshFieldLinear represents a continuous piecewise-linear scalar field
f
defined on a (triangular or tetrahedral) mesh; the field value changes linearly within each element E (triangle or tetrahedron), and the gradient ∇f is constant within each element. The field is continuous across adjacent elements, but its gradient is discontinuous from one element to the other.To represent a piecewise linear field f, we store one field value per vertex of the mesh. Each element E (triangle or tetrahedron) has (d+1) vertices, where d is the dimension of the element. For triangle, d = 2, and for tetrahedron, d = 3.
On each element E, we define a linear function fᵉ:ℝ³→ℝ using the field values at vertices of E. The gradient ∇fᵉ:ℝ³→ℝ³ is a constant map, so we write ∇fᵉ for the constant gradient vector on E as well. For a point Q in element E, we have:
f(Q) = fᵉ(Q) for Q ∈ E, ∇f(Q) = ∇fᵉ for Q ∈ E.
Notice that the domain of fᵉ is the entire space of ℝ³, while the domain of f is the underlying space of the mesh.
The following sections are details for interested readers.
** Barycentric coordinate **
For a linear triangle or tetrahedron element E in 3-D, we use barycentric coordinate:
(b₀, b₁, b₂) for triangle, (b₀, b₁, b₂, b₃) for tetrahedron, ∑bᵢ = 1, bᵢ ≥ 0,
to identify a point Q that lies in the simplicial element E. The coefficient bᵢ is the weight of vertex Vᵉᵢ of the element E, where the index i is a local index within the element E, not the global index of the entire mesh. In other words, vertex Vᵉᵢ is the iᵗʰ vertex of E, not the iᵗʰ vertex among all vertices in the mesh. The point Q in E can be expressed as:
Q = ∑bᵉᵢ(Q)Vᵉᵢ,
where we indicate the barycentric coordinate of a point Q on an element E as bᵉᵢ(Q).
** Field value from barycentric coordinates **
At a point Q in element E, the piecewise linear field f has value:
f(Q) = fᵉ(Q) = ∑bᵉᵢ(Q)Fᵉᵢ
where Fᵉᵢ is the field value at the iᵗʰ vertex of element E.
** Frame dependency **
A MeshFieldLinear is a frame-dependent quantity. Instances of a field should be named, as with any other frame-dependent quantity, with a trailing _F indicating the field’s frame F. The field’s frame is implicitly defined to be the same as the mesh’s frame on which the field is instantiated. The field’s frame affects two APIs:
The gradients reported by EvaluateGradient() are expressed in the field’s
frame. - The cartesian point passed to EvaluateCartesian() must be measured and expressed in the field’s frame.
The field (along with its corresponding mesh) can be transformed into a new frame by invoking the TransformVertices() method on the mesh and Transform() on the field, passing the same math::RigidTransform to both.
** Gradient **
Consider each bᵉᵢ:ℝ³→ℝ as a linear function, its gradient ∇bᵉᵢ:ℝ³→ℝ³ is a constant map, and we write ∇bᵉᵢ for the constant gradient vector. The gradient of the piecewise linear field f at a point Q in an element E is:
∇f(Q) = ∇fᵉ = ∑Fᵉᵢ∇bᵉᵢ.
** Field value from Cartesian coordinates **
At a point Q in element E, the piecewise linear field f has value:
f(Q) = ∇fᵉ⋅Q + fᵉ(0,0,0).
Notice that (0,0,0) may or may not lie in element E.
- Template parameter
T
: a valid Eigen scalar for field values.
- Template parameter
MeshType
: the type of the meshes: TriangleSurfaceMesh or VolumeMesh.
Note
This class is templated; see
PolygonSurfaceMeshFieldLinear_
for the list of instantiations.- __init__(*args, **kwargs)
- EvaluateAtVertex(self: pydrake.geometry.PolygonSurfaceMeshFieldLinear, v: int) float
Evaluates the field value at a vertex.
- Parameter
v
: The index of the vertex.
- Precondition:
v ∈ [0, this->mesh().num_vertices()).
- Parameter
- EvaluateCartesian(self: pydrake.geometry.PolygonSurfaceMeshFieldLinear, e: int, p_MQ: numpy.ndarray[numpy.float64[3, 1]]) float
Evaluates the field at a point Qp on an element. If the element is a tetrahedron, Qp is the input point Q. If the element is a triangle, Qp is the projection of Q on the triangle’s plane.
If gradients have been calculated, it evaluates the field value directly. Otherwise, it converts Cartesian coordinates to barycentric coordinates for barycentric interpolation.
The return type depends on both the field’s scalar type
T
and the Cartesian coordinate typeC
. See drake::geometry::promoted_numerical “promoted_numerical_t” for details.- Parameter
e
: The index of the element.
- Parameter
p_MQ
: The position of point Q expressed in frame M, in Cartesian coordinates. M is the frame of the mesh.
- Raises
RuntimeError if the field does not have gradients defined and –
the MeshType doesn't support Barycentric coordinates. –
- Parameter
- EvaluateGradient(self: pydrake.geometry.PolygonSurfaceMeshFieldLinear, e: int) numpy.ndarray[numpy.float64[3, 1]]
Evaluates the gradient in the domain of the element indicated by
e
. The gradient is a vector in R³ expressed in frame M. For surface meshes, it will particularly lie parallel to the plane of the corresponding triangle.- Raises
RuntimeError if the gradient vector was not calculated. –
RuntimeError if the gradient field is marked degenerate. –
- template pydrake.geometry.PolygonSurfaceMeshFieldLinear_
Instantiations:
PolygonSurfaceMeshFieldLinear_[float,float]
,PolygonSurfaceMeshFieldLinear_[AutoDiffXd,AutoDiffXd]
- class pydrake.geometry.PolygonSurfaceMeshFieldLinear_[AutoDiffXd,AutoDiffXd]
MeshFieldLinear represents a continuous piecewise-linear scalar field
f
defined on a (triangular or tetrahedral) mesh; the field value changes linearly within each element E (triangle or tetrahedron), and the gradient ∇f is constant within each element. The field is continuous across adjacent elements, but its gradient is discontinuous from one element to the other.To represent a piecewise linear field f, we store one field value per vertex of the mesh. Each element E (triangle or tetrahedron) has (d+1) vertices, where d is the dimension of the element. For triangle, d = 2, and for tetrahedron, d = 3.
On each element E, we define a linear function fᵉ:ℝ³→ℝ using the field values at vertices of E. The gradient ∇fᵉ:ℝ³→ℝ³ is a constant map, so we write ∇fᵉ for the constant gradient vector on E as well. For a point Q in element E, we have:
f(Q) = fᵉ(Q) for Q ∈ E, ∇f(Q) = ∇fᵉ for Q ∈ E.
Notice that the domain of fᵉ is the entire space of ℝ³, while the domain of f is the underlying space of the mesh.
The following sections are details for interested readers.
** Barycentric coordinate **
For a linear triangle or tetrahedron element E in 3-D, we use barycentric coordinate:
(b₀, b₁, b₂) for triangle, (b₀, b₁, b₂, b₃) for tetrahedron, ∑bᵢ = 1, bᵢ ≥ 0,
to identify a point Q that lies in the simplicial element E. The coefficient bᵢ is the weight of vertex Vᵉᵢ of the element E, where the index i is a local index within the element E, not the global index of the entire mesh. In other words, vertex Vᵉᵢ is the iᵗʰ vertex of E, not the iᵗʰ vertex among all vertices in the mesh. The point Q in E can be expressed as:
Q = ∑bᵉᵢ(Q)Vᵉᵢ,
where we indicate the barycentric coordinate of a point Q on an element E as bᵉᵢ(Q).
** Field value from barycentric coordinates **
At a point Q in element E, the piecewise linear field f has value:
f(Q) = fᵉ(Q) = ∑bᵉᵢ(Q)Fᵉᵢ
where Fᵉᵢ is the field value at the iᵗʰ vertex of element E.
** Frame dependency **
A MeshFieldLinear is a frame-dependent quantity. Instances of a field should be named, as with any other frame-dependent quantity, with a trailing _F indicating the field’s frame F. The field’s frame is implicitly defined to be the same as the mesh’s frame on which the field is instantiated. The field’s frame affects two APIs:
The gradients reported by EvaluateGradient() are expressed in the field’s
frame. - The cartesian point passed to EvaluateCartesian() must be measured and expressed in the field’s frame.
The field (along with its corresponding mesh) can be transformed into a new frame by invoking the TransformVertices() method on the mesh and Transform() on the field, passing the same math::RigidTransform to both.
** Gradient **
Consider each bᵉᵢ:ℝ³→ℝ as a linear function, its gradient ∇bᵉᵢ:ℝ³→ℝ³ is a constant map, and we write ∇bᵉᵢ for the constant gradient vector. The gradient of the piecewise linear field f at a point Q in an element E is:
∇f(Q) = ∇fᵉ = ∑Fᵉᵢ∇bᵉᵢ.
** Field value from Cartesian coordinates **
At a point Q in element E, the piecewise linear field f has value:
f(Q) = ∇fᵉ⋅Q + fᵉ(0,0,0).
Notice that (0,0,0) may or may not lie in element E.
- Template parameter
T
: a valid Eigen scalar for field values.
- Template parameter
MeshType
: the type of the meshes: TriangleSurfaceMesh or VolumeMesh.
- __init__(*args, **kwargs)
- EvaluateAtVertex(self: pydrake.geometry.PolygonSurfaceMeshFieldLinear_[AutoDiffXd, AutoDiffXd], v: int) pydrake.autodiffutils.AutoDiffXd
Evaluates the field value at a vertex.
- Parameter
v
: The index of the vertex.
- Precondition:
v ∈ [0, this->mesh().num_vertices()).
- Parameter
- EvaluateCartesian(self: pydrake.geometry.PolygonSurfaceMeshFieldLinear_[AutoDiffXd, AutoDiffXd], e: int, p_MQ: numpy.ndarray[object[3, 1]]) pydrake.autodiffutils.AutoDiffXd
Evaluates the field at a point Qp on an element. If the element is a tetrahedron, Qp is the input point Q. If the element is a triangle, Qp is the projection of Q on the triangle’s plane.
If gradients have been calculated, it evaluates the field value directly. Otherwise, it converts Cartesian coordinates to barycentric coordinates for barycentric interpolation.
The return type depends on both the field’s scalar type
T
and the Cartesian coordinate typeC
. See drake::geometry::promoted_numerical “promoted_numerical_t” for details.- Parameter
e
: The index of the element.
- Parameter
p_MQ
: The position of point Q expressed in frame M, in Cartesian coordinates. M is the frame of the mesh.
- Raises
RuntimeError if the field does not have gradients defined and –
the MeshType doesn't support Barycentric coordinates. –
- Parameter
- EvaluateGradient(self: pydrake.geometry.PolygonSurfaceMeshFieldLinear_[AutoDiffXd, AutoDiffXd], e: int) numpy.ndarray[object[3, 1]]
Evaluates the gradient in the domain of the element indicated by
e
. The gradient is a vector in R³ expressed in frame M. For surface meshes, it will particularly lie parallel to the plane of the corresponding triangle.- Raises
RuntimeError if the gradient vector was not calculated. –
RuntimeError if the gradient field is marked degenerate. –
- class pydrake.geometry.ProximityProperties
Bases:
pydrake.geometry.GeometryProperties
The set of properties for geometry used in a proximity role.
Examples of functionality that depends on the proximity role:
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.ProximityProperties) -> None
__init__(self: pydrake.geometry.ProximityProperties, other: pydrake.geometry.ProximityProperties) -> None
Creates a copy of the properties
- class pydrake.geometry.QueryObject
The QueryObject serves as a mechanism to perform geometry queries on the world’s geometry. The SceneGraph has an abstract-valued port that contains a QueryObject (i.e., a QueryObject-valued output port).
To perform geometry queries on SceneGraph: - a LeafSystem must have a QueryObject-valued input port and connect it to the corresponding query output port on SceneGraph, - the querying LeafSystem can evaluate the input port, retrieving a
const QueryObject&
in return, and, finally, - invoke the appropriate method on the QueryObject.The const reference returned by the input port is considered “live” - it is linked to the context, system, and cache (making full use of all of those mechanisms). This const reference should never be persisted; doing so can lead to erroneous query results. It is simpler and more advisable to acquire it for evaluation in a limited scope (e.g., CalcTimeDerivatives()) and then discard it. If a QueryObject is needed for many separate functions in a LeafSystem, each should re-evaluate the input port. The underlying caching mechanism should make the cost of this negligible.
The QueryObject can be copied. The copied instance is no longer “live”; it is now “baked”. Essentially, it freezes the state of the live scene graph in its current configuration and disconnects it from the system and context. This means, even if the original context changes values, the copied/baked instance will always reproduce the same query results. This baking process is not cheap and should not be done without consideration.
A QueryObject cannot be converted to a different scalar type. A QueryObject of scalar type T can only be acquired from the output port of a SceneGraph of type T evaluated on a corresponding Context, also of type T.
QueryObject’s support for arbitrary scalar type is incomplete. Not all queries support all scalar types to the same degree. Furthermore, the queries are typically served by families of algorithms. The evaluation of a query between a particular pair of geometries will depend on the query, the pair of geometry types involved, and the scalar type. From query to query, the treatment of a geometry (or geometry pair) for a given scalar type can vary in many ways, including but not limited to: ignoring the geometry, throwing an exception, results with limited precision, or full, accurate support. The queries below provide tables to help inform your expectations when evaluating queries. The tables all use a common methodology and admit a common interpretation.
For each (query, geometry-pair, scalar) combination, we create a set of geometric configurations with known answers. We evaluate the precision of the query result (if supported at all) over the entire set and report the worst observed error. This is a purely empirical approach and doesn’t fully characterize the families of underlying algorithms, and the reported error may be misleading in that we’ve missed far worse latent error or that the error reported doesn’t well represent the average case.
The families of algorithms also differ in how their inherent errors scale with the scale of the problem (e.g., size of geometries, magnitude of distance/depth, etc.) Attempting to fully characterize that aspect is both arduous and problematic, so, we’ve chosen a more representative approach.
Because Drake is primarily intended for robot simulation, we’ve created geometric configurations on the scale of common robot manipulators (on the order of 20cm). We position them with a known penetration depth (or separating distance) of 2 mm. The error reported is the deviation from that expected result.
When interpreting the tables, keep the following in mind: - The table illustrates trends in broad strokes, only. It does not represent an exhaustive analysis. - If your problem involves larger geometries, greater penetration depths, or larger separating distances, the error will vary. Do not assume that observed error in this context is necessarily relative – there truly is that much variability in the families of algorithms. - These values are an attempt to capture the worst case outcome. The error shown is a single-significant-digit approximation of that observed error. - These values may not actually represent the true worst case; discovering the true worst case is generally challenging. These represent our best effort to date. If you find outcomes that are worse those reported here, please ` submit a bug <https://github.com/RobotLocomotion/drake/issues/new>`_. - These tables represent Drake’s transient state. The eventual goal is to report no more than 1e-14 error across all supportable geometry pairs and scalars. At that point, the table will simply disappear.
Note
This class is templated; see
QueryObject_
for the list of instantiations.- __init__(self: pydrake.geometry.QueryObject) None
Constructs a default QueryObject (all pointers are null).
- ComputeContactSurfaces(self: pydrake.geometry.QueryObject, representation: pydrake.geometry.HydroelasticContactRepresentation) list[drake::geometry::ContactSurface<double>]
Reports pairwise intersections and characterizes each non-empty intersection as a ContactSurface for hydroelastic contact model. The computation is subject to collision filtering.
For two intersecting geometries g_A and g_B, it is guaranteed that they will map to
id_A
andid_B
in a fixed, repeatable manner, whereid_A
andid_B
are GeometryId’s of geometries g_A and g_B respectively.In the current incarnation, this function represents an incomplete implementation. That has several implications, as described below:
This table shows which shapes can be declared for use in hydroelastic
contact, and what compliance can be assigned.
Shape | Compliant | Rigid | | :——-: | :——-: | :—: | |Sphere | yes | yes | | Cylinder | yes | yes | | Box | yes | yes | | Capsule | yes | yes | | Ellipsoid | yes | yes | | HalfSpace | yes | yes | | Mesh | yesᵃ | yesᵇ | | Convex | yesᶜ | yesᶜ |
ᵃ The exact representation of a compliant mesh depends on the type of
mesh file it references: - .obj: the convex hull of the mesh will be used (as if it were declared to be a Convex shape). - .vtk: the tetrahedral mesh will be used directly. This external working <a href=”https://docs.google.com/document/d/1VZtVsxIjOLKvgQ8SNSrF6PtWuPW5z9PP7-dQuxfmqpc/edit?usp=sharing”> document</a> provides guidance how to generate a tetrahedral mesh in a VTK file from a surface mesh in an OBJ file. - ᵇ For rigid Mesh, please specify a surface mesh in an OBJ file in Mesh(filename). A tetrahedral mesh in a VTK file can also be specified. - ᶜ The Convex shape can reference either an .obj or a .vtk tetrahedral mesh. In both cases, its convex hull will be used to define the hydroelastic representation.
We do not support contact between two rigid geometries. One geometry
must* be compliant, and the other could be rigid or compliant. If two rigid geometries collide, an exception will be thrown. More particularly, if such a geometry pair cannot be culled an exception will be thrown. No exception is thrown if the pair has been filtered. - If you need all combinations of rigid-rigid contact, rigid-compliant contact, and compliant-compliant contact, you might consider ComputeContactSurfacesWithFallback(). - The hydroelastic modulus (N/m^2) of each compliant geometry is set in ProximityProperties by AddCompliantHydroelasticProperties(). - The tessellation of the corresponding meshes is controlled by the resolution hint (where appropriate), as defined by AddCompliantHydroelasticProperties() and AddRigidHydroelasticProperties().
Scalar support
This method provides support for both double and AutoDiffXd, but not Expression. Like with the other proximity queries, derivatives can only be introduced via geometry poses. We cannot differentiate w.r.t. geometric properties (e.g., radius, length, etc.)
- Parameter
representation
: Controls the mesh representation of the contact surface. See contact_surface_discrete_representation “contact surface representation” for more details.
- Returns
A vector populated with all detected intersections characterized as contact surfaces. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
- ComputeContactSurfacesWithFallback(self: pydrake.geometry.QueryObject, representation: pydrake.geometry.HydroelasticContactRepresentation) tuple[list[drake::geometry::ContactSurface<double>], list[drake::geometry::PenetrationAsPointPair<double>]]
Reports pairwise intersections and characterizes each non-empty intersection as a ContactSurface where possible and as a PenetrationAsPointPair where not.
This method can be thought of as a combination of ComputeContactSurfaces() and ComputePointPairPenetration(). For each geometry pair, we attempt to compute a ContactSurface. If that fails, rather than throwing, we attempt to characterize the contact as a point pair. If that fails, we throw. See the documentation of those constituent methods to understand the circumstances in which they fail.
The ordering of the added results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
Scalar support
The scalar support is a combination of the scalar support offered by ComputeContactSurfaces() and ComputePointPairPenetration(). This method supports double and AutoDiffXd to the extent that those constituent methods do, but does not support Expression.
- Parameter
representation
: Controls the mesh representation of the contact surface. See contact_surface_discrete_representation “contact surface representation” for more details.
- Parameter
surfaces
: The vector that contact surfaces will be added to. The vector will not be cleared.
- Parameter
point_pairs
: The vector that fall back point pair data will be added to. The vector will not be cleared.
- Precondition:
Neither
surfaces
norpoint_pairs
is nullptr.
- Raises
RuntimeError for the reasons described in ComputeContactSurfaces() –
and ComputePointPairPenetration() –
Note
The
surfaces
andpoint_pairs
are output pointers in C++, but are return values in the Python bindings.- Parameter
- ComputePointPairPenetration(self: pydrake.geometry.QueryObject) list[drake::geometry::PenetrationAsPointPair<double>]
Computes the penetrations across all pairs of geometries in the world with the penetrations characterized by pairs of points (see PenetrationAsPointPair), providing some measure of the penetration “depth” of the two objects, but not the overlapping volume.
Only reports results for penetrating geometries; if two geometries are separated, there will be no result for that pair. Geometries whose surfaces are just touching (osculating) are not considered in penetration. Surfaces whose penetration is within an epsilon of osculation, are likewise not considered penetrating. Pairs of anchored geometry are also not reported. This method is affected by collision filtering.
For two penetrating geometries g_A and g_B, it is guaranteed that they will map to
id_A
andid_B
in a fixed, repeatable manner.Characterizing the returned values
As discussed in the query_object_precision_methodology “class’s documentation”, these tables document the support given by this query for pairs of geometry types and scalar. See the description in the link for details on how to interpret the tables’ results. The query is symmetric with respect to shape ordering, the pair (ShapeA, ShapeB) will be the same as (ShapeB, ShapeA), so we only fill in half of each table.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | 2e-15 | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | 3e-5ᶜ | 2e-5ᶜ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | 2e-15ᶜ | 3e-5ᶜ | 2e-15ᶜ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | 1e-3ᶜ | 4e-5ᶜ | 1e-3ᶜ | 2e-3ᶜ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | 4e-4ᶜ | 2e-4ᶜ | 4e-4ᶜ | 2e-3ᶜ | 5e-4ᶜ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | 6e-15 | 4e-15 | 3e-15ᶜ | 4e-15 | 3e-15 | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | 3e-15 | 5e-15 | 3e-5ᶜ | 5e-15 | 2e-4ᶜ | 3e-15 | ᵇ | 5e-15 | *Table 1*: Worst observed error (in m) for 2mm penetration between geometries approximately 20cm in size for
T
=double
.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵈ | throwsᵈ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | 2e-15 | 3e-15 | throwsᵈ | 2e-15 | throwsᵈ | 2e-15 | ᵇ | 5e-15 | *Table 2*: Worst observed error (in m) for 2mm penetration between geometries approximately 20cm in size for
T
= drake::AutoDiffXd “AutoDiffXd”.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵉ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵉ | throwsᵉ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ᵇ | throwsᵉ | *Table 3*: Support for
T
= drake::symbolic::Expression.ᵃ Penetration depth between two HalfSpace instances has no meaning; either
they don’t intersect, or they have infinite penetration. - ᵇ Meshes are represented by the convex hull of the mesh, therefore the results for Mesh are assumed to be the same as for Convex. - ᶜ These results are computed using an iterative algorithm. For particular configurations, the solution may be correct to machine precision. The values reported here are confirmed, observed worst case answers. - ᵈ These results are simply not supported for
T
= drake::AutoDiffXd “AutoDiffXd” at this time. - ᵉ These results are simply not supported forT
= drake::symbolic::Expression at this time.- Returns
A vector populated with all detected penetrations characterized as point pairs. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- Raises
RuntimeError if a Shape-Shape pair is in collision and indicated –
as throws in the support table above. –
- ComputeSignedDistancePairClosestPoints(self: pydrake.geometry.QueryObject, geometry_id_A: pydrake.geometry.GeometryId, geometry_id_B: pydrake.geometry.GeometryId) drake::geometry::SignedDistancePair<double>
A variant of ComputeSignedDistancePairwiseClosestPoints() which computes the signed distance (and witnesses) between a specific pair of geometries indicated by id. This function has the same restrictions on scalar report as ComputeSignedDistancePairwiseClosestPoints().
Note
This query is unique among the distance queries in that it doesn’t respect collision filters. As long as the geometry ids refer to geometries with proximity roles, signed distance can be computed (subject to supported scalar tables above).
Characterizing the returned values
This method merely exercises the same mechanisms as ComputeSignedDistancePairwiseClosestPoints() for evaluating signed distance. Refer to query_object_compute_pairwise_distance_table “the table for ComputeSignedDistancePairwiseClosestPoints()” for details.
- Raises
RuntimeError if either geometry id is invalid (e.g., doesn't refer –
to an existing geometry, lacking proximity role, etc.), the pair –
is unsupported as indicated by the scalar support table. –
Warning
For Mesh shapes, their convex hulls are used in this query. It is not computationally efficient or particularly accurate.
- ComputeSignedDistancePairwiseClosestPoints(self: pydrake.geometry.QueryObject, max_distance: float = inf) list[drake::geometry::SignedDistancePair<double>]
Computes the signed distance together with the nearest points across all pairs of geometries in the world. Reports both the separating geometries and penetrating geometries.
This query provides φ(A, B), the signed distance between two objects A and B.
If the objects do not overlap (i.e., A ⋂ B = ∅), φ > 0 and represents the minimal distance between the two objects. More formally: φ = min(|Aₚ - Bₚ|) ∀ Aₚ ∈ A and Bₚ ∈ B.
Note
The pair (Aₚ, Bₚ) is a “witness” of the distance. The pair need not be unique (think of two parallel planes).
If the objects touch or overlap (i.e., A ⋂ B ≠ ∅), φ ≤ 0 and can be interpreted as the negative penetration depth. It is the smallest length of the vector v, such that by shifting one object along that vector relative to the other, the two objects will no longer be overlapping. More formally, φ(A, B) = -min |v|. s.t (Tᵥ · A) ⋂ B = ∅ where Tᵥ is a rigid transformation that displaces A by the vector v, namely Tᵥ · A = {u + v | ∀ u ∈ A}. By implication, there exist points Aₚ and Bₚ on the surfaces of objects A and B, respectively, such that Aₚ + v = Bₚ, Aₚ ∈ A ∩ B, Bₚ ∈ A ∩ B. These points are the witnesses to the penetration.
This method is affected by collision filtering; geometry pairs that have been filtered will not produce signed distance query results.
For a geometry pair (A, B), the returned results will always be reported in a fixed order (e.g., always (A, B) and never (B, A)). The basis for the ordering is arbitrary (and therefore undocumented), but guaranteed to be fixed and repeatable.
Notice that this is an O(N²) operation, where N is the number of geometries remaining in the world after applying collision filter. We report the distance between dynamic objects, and between dynamic and anchored objects. We DO NOT report the distance between two anchored objects.
Using maximum distance
While the algorithm generally has O(N²) complexity in time and space, that can be reduced by the judicious use of the
max_distance
parameter. Ifφ(A, B) > max_distance
, the pair (A, B) will not be included in the results (making it O(M²) in space where M < N). Furthermore, the broadphase culling algorithm can exploitmax_distance
to cheaply eliminate pairs of geometry that are “obviously” too far (likewise reducing the time complexity).Passing
max_distance = 0
is conceptually related to calling HasCollisions(). If contact is sparse (very few actually contacting geometry pairs), the two invocations will be quite similar in cost. However, the distinction between the two is that this method would have to include all pairs that satisfyφ(A, B) <= 0
, whereas HasCollisions() stops at the first. So, the more actually colliding geometry pairs there are, the bigger the difference in cost between the two approaches.Characterizing the returned values
As discussed in the query_object_precision_methodology “class’s documentation”, this table documents the support given by this query for pairs of geometry types and scalar. See the description in the link for details on how to interpret the table results. The query is symmetric with respect to shape ordering, the pair (ShapeA, ShapeB) will be the same as (ShapeB, ShapeA), so we only fill in half the table.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | 4e-15 | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | 3e-6 | 2e-5 | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | 3e-15 | 2e-5 | 3e-15 | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | 6e-6 | 1e-5 | 6e-6 | 2e-5 | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | 9e-6 | 5e-6 | 9e-6 | 5e-5 | 2e-5 | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | 3e-15 | 6e-15 | 3e-6 | 5e-15 | 4e-5 | 3e-15 | ᶜ | 6e-15 | *Table 4*: Worst observed error (in m) for 2mm penetration/separation between geometries approximately 20cm in size for
T
=double
.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵇ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵇ | throwsᵇ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | 2e-15 | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | 2e-15 | ᶜ | 5e-15 | *Table 5*: Worst observed error (in m) for 2mm penetration/separation between geometries approximately 20cm in size for
T
= drake::AutoDiffXd “AutoDiffXd”.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵈ | throwsᵈ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ᶜ | throwsᵈ | *Table 6*: Support for
T
= drake::symbolic::Expression.ᵃ We don’t currently support queries between HalfSpace and any other shape
(except for Sphere). - ᵇ These results are simply not supported for
T
= drake::AutoDiffXd “AutoDiffXd” at this time. - ᶜ Meshes are represented by the convex hull of the mesh, therefore the results for Mesh are the same as for Convex. - ᵈ These results are simply not supported forT
= drake::symbolic::Expression at this time.Characterizing the returned gradients
In most cases, the returned gradient vectors are the normalized displacement vectors between two witness points. However, when two geometries touch at zero distance, their witness points have a zero displacement vector that we cannot normalize.
When two geometries touch at zero distance, we have special implementation to choose reasonable gradients for some cases shown as “Ok” in the table below. Otherwise, they are “NaN” in the table. In general, we try to choose the gradient, when two geometries touch, in the most consistent way, but the problem sometimes doesn’t have a unique solution. For example, any direction is qualified to be the gradient for two concentric spheres. Or two boxes touching at their vertices can pick a gradient from a continuous family of directions.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | Ok | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | NaN | NaN | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | NaN | NaN | NaN | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | NaN | NaN | NaN | NaN | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | NaN | NaN | NaN | NaN | NaN | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | NaN | NaN | NaN | NaN | NaN | NaN | ░░░░░ | ░░░░░ | | Mesh | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ░░░░░ | | Sphere | Ok | Ok | Okᵃ | Ok | Okᵃ | Ok | Okᵃ | Ok | *Table 7*: Support for signed-distance gradients when two geometries touch at zero distance.
ᵃ Return the gradient as a Vector3d of NaN if the sphere has zero radius.
- Parameter
max_distance
: The maximum distance at which distance data is reported.
- Returns
The signed distance (and supporting data) for all unfiltered geometry pairs whose distance is less than or equal to
max_distance
. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.- Raises
RuntimeError as indicated in the table above. –
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- ComputeSignedDistanceToPoint(self: pydrake.geometry.QueryObject, p_WQ: numpy.ndarray[numpy.float64[3, 1]], threshold: float = inf) list[drake::geometry::SignedDistanceToPoint<double>]
Computes the signed distances and gradients to a query point from each geometry in the scene.
This query provides φᵢ(p), φᵢ:ℝ³→ℝ, the signed distance to the position p of a query point from geometry Gᵢ in the scene. It returns an array of the signed distances from all geometries.
Optionally you can specify a threshold distance that will filter out any object beyond the threshold. By default, we report distances from the query point to every object.
This query also provides the gradient vector ∇φᵢ(p) of the signed distance function from geometry Gᵢ. Note that, in general, if p is outside Gᵢ, then ∇φᵢ(p) equals the unit vector in the direction from the nearest point Nᵢ on Gᵢ’s surface to p. If p is inside Gᵢ, then ∇φᵢ(p) is in the direction from p to Nᵢ. This observation is written formally as:
∇φᵢ(p) = (p - Nᵢ)/|p - Nᵢ| if p is outside Gᵢ
∇φᵢ(p) = -(p - Nᵢ)/|p - Nᵢ| if p is inside Gᵢ
Note that ∇φᵢ(p) is also defined on Gᵢ’s surface, but we cannot use the above formula.
Characterizing the returned values
This table is a variant of that described in this query_object_precision_methodology “class’s documentation”. The query evaluates signed distance between one shape and a point (in contrast to other queries which involve two shapes). Therefore, we don’t need a matrix of shape pairs, but a list of shapes. Otherwise, the methodology is the same as described, with the point being represented as a zero-radius sphere.
Scalar | Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace |Mesh | Sphere | | :——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | double | 2e-15 | 4e-15 | ᵃ | 3e-15 | 3e-5ᵇ | 5e-15 | ᵃ | 4e-15 | | AutoDiffXd | 1e-15 | 4e-15 | ᵃ | ᵃ | ᵃ | 5e-15 | ᵃ | 3e-15 | | Expression | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | *Table 8*: Worst observed error (in m) for 2mm penetration/separation between geometry approximately 20cm in size and a point.
ᵃ Unsupported geometry/scalar combinations are simply ignored; no results
are reported for that geometry. - ᵇ This uses an iterative algorithm which introduces a relatively large and variable error. For example, as the eccentricity of the ellipsoid increases, this error may get worse. It also depends on the location of the projection of the query point on the ellipsoid; the closer that point is to the high curvature area, the bigger the effect. It is not immediately clear how much worse the answer will get.
Note
For a sphere G, the signed distance function φᵢ(p) has an undefined gradient vector at the center of the sphere–every point on the sphere’s surface has the same distance to the center. In this case, we will assign ∇φᵢ(p) the unit vector Gx (x-directional vector of G’s frame) expressed in World frame.
Note
For a box, at a point p on an edge or a corner of the box, the signed distance function φᵢ(p) has an undefined gradient vector. In this case, we will assign a unit vector in the direction of the average of the outward face unit normals of the incident faces of the edge or the corner. A point p is considered being on a face, or an edge, or a corner of the box if it lies within a certain tolerance from them.
Note
For a box B, if a point p is inside the box, and it is equidistant to multiple nearest faces, the signed distance function φᵢ(p) at p will have an undefined gradient vector. There is a nearest point candidate associated with each nearest face. In this case, we arbitrarily pick the point Nᵢ associated with one of the nearest faces. Please note that, due to the possible round off error arising from applying a pose X_WG to B, there is no guarantee which of the nearest faces will be used.
Note
The signed distance function is a continuous function with respect to the position of the query point, but its gradient vector field may not be continuous. Specifically at a position equidistant to multiple nearest points, its gradient vector field is not continuous.
Note
For a convex object, outside the object at positive distance from the boundary, the signed distance function is smooth (having continuous first-order partial derivatives).
- Parameter
p_WQ
: Position of a query point Q in world frame W.
- Parameter
threshold
: We ignore any object beyond this distance. By default, it is infinity, so we report distances from the query point to every object.
- Returns
signed_distances
: A vector populated with per-object signed distance values (and supporting data) for every supported geometry as shown in the table. See SignedDistanceToPoint. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
- FindCollisionCandidates(self: pydrake.geometry.QueryObject) list[drake::SortedPair<drake::geometry::GeometryId>]
Applies a conservative culling mechanism to create a subset of all possible geometry pairs based on non-zero intersections. A geometry pair that is absent from the results is either a) culled by collision filters or b) known to be separated. The caller is responsible for confirming that the remaining, unculled geometry pairs are actually in collision.
- Returns
A vector populated with collision pair candidates (the order will remain constant for a fixed population but can change as geometry ids are added/removed).
- GetPoseInParent(self: pydrake.geometry.QueryObject, frame_id: pydrake.geometry.FrameId) pydrake.math.RigidTransform
Reports the position of the frame indicated by
frame_id
relative to its parent frame. If the frame was registered with the world frame as its parent frame, this value will be identical to that returned by GetPoseInWorld().- Raises
RuntimeError if the frame frame_id is not valid. –
- GetPoseInWorld(*args, **kwargs)
Overloaded function.
GetPoseInWorld(self: pydrake.geometry.QueryObject, frame_id: pydrake.geometry.FrameId) -> pydrake.math.RigidTransform
Reports the position of the frame indicated by
frame_id
relative to the world frame.- Raises
RuntimeError if the frame frame_id is not valid. –
GetPoseInWorld(self: pydrake.geometry.QueryObject, geometry_id: pydrake.geometry.GeometryId) -> pydrake.math.RigidTransform
Reports the position of the frame of the rigid geometry indicated by
geometry_id
relative to the world frame (X_WG).Note
This query is meaningless for deformable geometries. Their current state cannot be represented by a single rigid transformation. Instead, one should use GetConfigurationsInWorld() to get the current vertex positions of the deformable geometry in the world frame. On the other hand, it is meaningful to query the fixed pose of the reference geometry in its parent frame (see SceneGraphInspector::GetPoseInFrame()).
- Raises
RuntimeError if the geometry geometry_id is not valid or if it –
is deformable. –
- HasCollisions(self: pydrake.geometry.QueryObject) bool
Reports true if there are any collisions between unfiltered pairs in the world.
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- inspector(self: pydrake.geometry.QueryObject) pydrake.geometry.SceneGraphInspector
Provides an inspector for the topological structure of the underlying scene graph data (see SceneGraphInspector for details).
- RenderColorImage(self: pydrake.geometry.QueryObject, camera: pydrake.geometry.ColorRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)2>
Renders an RGB image for the given
camera
posed with respect to the indicated parent frame P.- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
color_image_out
: The rendered color image.
- Parameter
- RenderDepthImage(self: pydrake.geometry.QueryObject, camera: pydrake.geometry.DepthRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)6>
Renders a depth image for the given
camera
posed with respect to the indicated parent frame P.In contrast to the other rendering methods, rendering depth images doesn’t provide the option to display the window; generally, basic depth images are not readily communicative to humans.
- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
depth_image_out
: The rendered depth image.
- Parameter
- RenderLabelImage(self: pydrake.geometry.QueryObject, camera: pydrake.geometry.ColorRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)7>
Renders a label image for the given
camera
posed with respect to the indicated parent frame P.- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
label_image_out
: The rendered label image.
- Parameter
- template pydrake.geometry.QueryObject_
Instantiations:
QueryObject_[float]
,QueryObject_[AutoDiffXd]
,QueryObject_[Expression]
- class pydrake.geometry.QueryObject_[AutoDiffXd]
The QueryObject serves as a mechanism to perform geometry queries on the world’s geometry. The SceneGraph has an abstract-valued port that contains a QueryObject (i.e., a QueryObject-valued output port).
To perform geometry queries on SceneGraph: - a LeafSystem must have a QueryObject-valued input port and connect it to the corresponding query output port on SceneGraph, - the querying LeafSystem can evaluate the input port, retrieving a
const QueryObject&
in return, and, finally, - invoke the appropriate method on the QueryObject.The const reference returned by the input port is considered “live” - it is linked to the context, system, and cache (making full use of all of those mechanisms). This const reference should never be persisted; doing so can lead to erroneous query results. It is simpler and more advisable to acquire it for evaluation in a limited scope (e.g., CalcTimeDerivatives()) and then discard it. If a QueryObject is needed for many separate functions in a LeafSystem, each should re-evaluate the input port. The underlying caching mechanism should make the cost of this negligible.
The QueryObject can be copied. The copied instance is no longer “live”; it is now “baked”. Essentially, it freezes the state of the live scene graph in its current configuration and disconnects it from the system and context. This means, even if the original context changes values, the copied/baked instance will always reproduce the same query results. This baking process is not cheap and should not be done without consideration.
A QueryObject cannot be converted to a different scalar type. A QueryObject of scalar type T can only be acquired from the output port of a SceneGraph of type T evaluated on a corresponding Context, also of type T.
QueryObject’s support for arbitrary scalar type is incomplete. Not all queries support all scalar types to the same degree. Furthermore, the queries are typically served by families of algorithms. The evaluation of a query between a particular pair of geometries will depend on the query, the pair of geometry types involved, and the scalar type. From query to query, the treatment of a geometry (or geometry pair) for a given scalar type can vary in many ways, including but not limited to: ignoring the geometry, throwing an exception, results with limited precision, or full, accurate support. The queries below provide tables to help inform your expectations when evaluating queries. The tables all use a common methodology and admit a common interpretation.
For each (query, geometry-pair, scalar) combination, we create a set of geometric configurations with known answers. We evaluate the precision of the query result (if supported at all) over the entire set and report the worst observed error. This is a purely empirical approach and doesn’t fully characterize the families of underlying algorithms, and the reported error may be misleading in that we’ve missed far worse latent error or that the error reported doesn’t well represent the average case.
The families of algorithms also differ in how their inherent errors scale with the scale of the problem (e.g., size of geometries, magnitude of distance/depth, etc.) Attempting to fully characterize that aspect is both arduous and problematic, so, we’ve chosen a more representative approach.
Because Drake is primarily intended for robot simulation, we’ve created geometric configurations on the scale of common robot manipulators (on the order of 20cm). We position them with a known penetration depth (or separating distance) of 2 mm. The error reported is the deviation from that expected result.
When interpreting the tables, keep the following in mind: - The table illustrates trends in broad strokes, only. It does not represent an exhaustive analysis. - If your problem involves larger geometries, greater penetration depths, or larger separating distances, the error will vary. Do not assume that observed error in this context is necessarily relative – there truly is that much variability in the families of algorithms. - These values are an attempt to capture the worst case outcome. The error shown is a single-significant-digit approximation of that observed error. - These values may not actually represent the true worst case; discovering the true worst case is generally challenging. These represent our best effort to date. If you find outcomes that are worse those reported here, please ` submit a bug <https://github.com/RobotLocomotion/drake/issues/new>`_. - These tables represent Drake’s transient state. The eventual goal is to report no more than 1e-14 error across all supportable geometry pairs and scalars. At that point, the table will simply disappear.
- __init__(self: pydrake.geometry.QueryObject_[AutoDiffXd]) None
Constructs a default QueryObject (all pointers are null).
- ComputeContactSurfaces(self: pydrake.geometry.QueryObject_[AutoDiffXd], representation: pydrake.geometry.HydroelasticContactRepresentation) list[drake::geometry::ContactSurface<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >]
Reports pairwise intersections and characterizes each non-empty intersection as a ContactSurface for hydroelastic contact model. The computation is subject to collision filtering.
For two intersecting geometries g_A and g_B, it is guaranteed that they will map to
id_A
andid_B
in a fixed, repeatable manner, whereid_A
andid_B
are GeometryId’s of geometries g_A and g_B respectively.In the current incarnation, this function represents an incomplete implementation. That has several implications, as described below:
This table shows which shapes can be declared for use in hydroelastic
contact, and what compliance can be assigned.
Shape | Compliant | Rigid | | :——-: | :——-: | :—: | |Sphere | yes | yes | | Cylinder | yes | yes | | Box | yes | yes | | Capsule | yes | yes | | Ellipsoid | yes | yes | | HalfSpace | yes | yes | | Mesh | yesᵃ | yesᵇ | | Convex | yesᶜ | yesᶜ |
ᵃ The exact representation of a compliant mesh depends on the type of
mesh file it references: - .obj: the convex hull of the mesh will be used (as if it were declared to be a Convex shape). - .vtk: the tetrahedral mesh will be used directly. This external working <a href=”https://docs.google.com/document/d/1VZtVsxIjOLKvgQ8SNSrF6PtWuPW5z9PP7-dQuxfmqpc/edit?usp=sharing”> document</a> provides guidance how to generate a tetrahedral mesh in a VTK file from a surface mesh in an OBJ file. - ᵇ For rigid Mesh, please specify a surface mesh in an OBJ file in Mesh(filename). A tetrahedral mesh in a VTK file can also be specified. - ᶜ The Convex shape can reference either an .obj or a .vtk tetrahedral mesh. In both cases, its convex hull will be used to define the hydroelastic representation.
We do not support contact between two rigid geometries. One geometry
must* be compliant, and the other could be rigid or compliant. If two rigid geometries collide, an exception will be thrown. More particularly, if such a geometry pair cannot be culled an exception will be thrown. No exception is thrown if the pair has been filtered. - If you need all combinations of rigid-rigid contact, rigid-compliant contact, and compliant-compliant contact, you might consider ComputeContactSurfacesWithFallback(). - The hydroelastic modulus (N/m^2) of each compliant geometry is set in ProximityProperties by AddCompliantHydroelasticProperties(). - The tessellation of the corresponding meshes is controlled by the resolution hint (where appropriate), as defined by AddCompliantHydroelasticProperties() and AddRigidHydroelasticProperties().
Scalar support
This method provides support for both double and AutoDiffXd, but not Expression. Like with the other proximity queries, derivatives can only be introduced via geometry poses. We cannot differentiate w.r.t. geometric properties (e.g., radius, length, etc.)
- Parameter
representation
: Controls the mesh representation of the contact surface. See contact_surface_discrete_representation “contact surface representation” for more details.
- Returns
A vector populated with all detected intersections characterized as contact surfaces. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
- ComputeContactSurfacesWithFallback(self: pydrake.geometry.QueryObject_[AutoDiffXd], representation: pydrake.geometry.HydroelasticContactRepresentation) tuple[list[drake::geometry::ContactSurface<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >], list[drake::geometry::PenetrationAsPointPair<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >]]
Reports pairwise intersections and characterizes each non-empty intersection as a ContactSurface where possible and as a PenetrationAsPointPair where not.
This method can be thought of as a combination of ComputeContactSurfaces() and ComputePointPairPenetration(). For each geometry pair, we attempt to compute a ContactSurface. If that fails, rather than throwing, we attempt to characterize the contact as a point pair. If that fails, we throw. See the documentation of those constituent methods to understand the circumstances in which they fail.
The ordering of the added results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
Scalar support
The scalar support is a combination of the scalar support offered by ComputeContactSurfaces() and ComputePointPairPenetration(). This method supports double and AutoDiffXd to the extent that those constituent methods do, but does not support Expression.
- Parameter
representation
: Controls the mesh representation of the contact surface. See contact_surface_discrete_representation “contact surface representation” for more details.
- Parameter
surfaces
: The vector that contact surfaces will be added to. The vector will not be cleared.
- Parameter
point_pairs
: The vector that fall back point pair data will be added to. The vector will not be cleared.
- Precondition:
Neither
surfaces
norpoint_pairs
is nullptr.
- Raises
RuntimeError for the reasons described in ComputeContactSurfaces() –
and ComputePointPairPenetration() –
Note
The
surfaces
andpoint_pairs
are output pointers in C++, but are return values in the Python bindings.- Parameter
- ComputePointPairPenetration(self: pydrake.geometry.QueryObject_[AutoDiffXd]) list[drake::geometry::PenetrationAsPointPair<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >]
Computes the penetrations across all pairs of geometries in the world with the penetrations characterized by pairs of points (see PenetrationAsPointPair), providing some measure of the penetration “depth” of the two objects, but not the overlapping volume.
Only reports results for penetrating geometries; if two geometries are separated, there will be no result for that pair. Geometries whose surfaces are just touching (osculating) are not considered in penetration. Surfaces whose penetration is within an epsilon of osculation, are likewise not considered penetrating. Pairs of anchored geometry are also not reported. This method is affected by collision filtering.
For two penetrating geometries g_A and g_B, it is guaranteed that they will map to
id_A
andid_B
in a fixed, repeatable manner.Characterizing the returned values
As discussed in the query_object_precision_methodology “class’s documentation”, these tables document the support given by this query for pairs of geometry types and scalar. See the description in the link for details on how to interpret the tables’ results. The query is symmetric with respect to shape ordering, the pair (ShapeA, ShapeB) will be the same as (ShapeB, ShapeA), so we only fill in half of each table.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | 2e-15 | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | 3e-5ᶜ | 2e-5ᶜ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | 2e-15ᶜ | 3e-5ᶜ | 2e-15ᶜ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | 1e-3ᶜ | 4e-5ᶜ | 1e-3ᶜ | 2e-3ᶜ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | 4e-4ᶜ | 2e-4ᶜ | 4e-4ᶜ | 2e-3ᶜ | 5e-4ᶜ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | 6e-15 | 4e-15 | 3e-15ᶜ | 4e-15 | 3e-15 | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | 3e-15 | 5e-15 | 3e-5ᶜ | 5e-15 | 2e-4ᶜ | 3e-15 | ᵇ | 5e-15 | *Table 1*: Worst observed error (in m) for 2mm penetration between geometries approximately 20cm in size for
T
=double
.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵈ | throwsᵈ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | 2e-15 | 3e-15 | throwsᵈ | 2e-15 | throwsᵈ | 2e-15 | ᵇ | 5e-15 | *Table 2*: Worst observed error (in m) for 2mm penetration between geometries approximately 20cm in size for
T
= drake::AutoDiffXd “AutoDiffXd”.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵉ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵉ | throwsᵉ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ᵇ | throwsᵉ | *Table 3*: Support for
T
= drake::symbolic::Expression.ᵃ Penetration depth between two HalfSpace instances has no meaning; either
they don’t intersect, or they have infinite penetration. - ᵇ Meshes are represented by the convex hull of the mesh, therefore the results for Mesh are assumed to be the same as for Convex. - ᶜ These results are computed using an iterative algorithm. For particular configurations, the solution may be correct to machine precision. The values reported here are confirmed, observed worst case answers. - ᵈ These results are simply not supported for
T
= drake::AutoDiffXd “AutoDiffXd” at this time. - ᵉ These results are simply not supported forT
= drake::symbolic::Expression at this time.- Returns
A vector populated with all detected penetrations characterized as point pairs. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- Raises
RuntimeError if a Shape-Shape pair is in collision and indicated –
as throws in the support table above. –
- ComputeSignedDistancePairClosestPoints(self: pydrake.geometry.QueryObject_[AutoDiffXd], geometry_id_A: pydrake.geometry.GeometryId, geometry_id_B: pydrake.geometry.GeometryId) drake::geometry::SignedDistancePair<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >
A variant of ComputeSignedDistancePairwiseClosestPoints() which computes the signed distance (and witnesses) between a specific pair of geometries indicated by id. This function has the same restrictions on scalar report as ComputeSignedDistancePairwiseClosestPoints().
Note
This query is unique among the distance queries in that it doesn’t respect collision filters. As long as the geometry ids refer to geometries with proximity roles, signed distance can be computed (subject to supported scalar tables above).
Characterizing the returned values
This method merely exercises the same mechanisms as ComputeSignedDistancePairwiseClosestPoints() for evaluating signed distance. Refer to query_object_compute_pairwise_distance_table “the table for ComputeSignedDistancePairwiseClosestPoints()” for details.
- Raises
RuntimeError if either geometry id is invalid (e.g., doesn't refer –
to an existing geometry, lacking proximity role, etc.), the pair –
is unsupported as indicated by the scalar support table. –
Warning
For Mesh shapes, their convex hulls are used in this query. It is not computationally efficient or particularly accurate.
- ComputeSignedDistancePairwiseClosestPoints(self: pydrake.geometry.QueryObject_[AutoDiffXd], max_distance: float = inf) list[drake::geometry::SignedDistancePair<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >]
Computes the signed distance together with the nearest points across all pairs of geometries in the world. Reports both the separating geometries and penetrating geometries.
This query provides φ(A, B), the signed distance between two objects A and B.
If the objects do not overlap (i.e., A ⋂ B = ∅), φ > 0 and represents the minimal distance between the two objects. More formally: φ = min(|Aₚ - Bₚ|) ∀ Aₚ ∈ A and Bₚ ∈ B.
Note
The pair (Aₚ, Bₚ) is a “witness” of the distance. The pair need not be unique (think of two parallel planes).
If the objects touch or overlap (i.e., A ⋂ B ≠ ∅), φ ≤ 0 and can be interpreted as the negative penetration depth. It is the smallest length of the vector v, such that by shifting one object along that vector relative to the other, the two objects will no longer be overlapping. More formally, φ(A, B) = -min |v|. s.t (Tᵥ · A) ⋂ B = ∅ where Tᵥ is a rigid transformation that displaces A by the vector v, namely Tᵥ · A = {u + v | ∀ u ∈ A}. By implication, there exist points Aₚ and Bₚ on the surfaces of objects A and B, respectively, such that Aₚ + v = Bₚ, Aₚ ∈ A ∩ B, Bₚ ∈ A ∩ B. These points are the witnesses to the penetration.
This method is affected by collision filtering; geometry pairs that have been filtered will not produce signed distance query results.
For a geometry pair (A, B), the returned results will always be reported in a fixed order (e.g., always (A, B) and never (B, A)). The basis for the ordering is arbitrary (and therefore undocumented), but guaranteed to be fixed and repeatable.
Notice that this is an O(N²) operation, where N is the number of geometries remaining in the world after applying collision filter. We report the distance between dynamic objects, and between dynamic and anchored objects. We DO NOT report the distance between two anchored objects.
Using maximum distance
While the algorithm generally has O(N²) complexity in time and space, that can be reduced by the judicious use of the
max_distance
parameter. Ifφ(A, B) > max_distance
, the pair (A, B) will not be included in the results (making it O(M²) in space where M < N). Furthermore, the broadphase culling algorithm can exploitmax_distance
to cheaply eliminate pairs of geometry that are “obviously” too far (likewise reducing the time complexity).Passing
max_distance = 0
is conceptually related to calling HasCollisions(). If contact is sparse (very few actually contacting geometry pairs), the two invocations will be quite similar in cost. However, the distinction between the two is that this method would have to include all pairs that satisfyφ(A, B) <= 0
, whereas HasCollisions() stops at the first. So, the more actually colliding geometry pairs there are, the bigger the difference in cost between the two approaches.Characterizing the returned values
As discussed in the query_object_precision_methodology “class’s documentation”, this table documents the support given by this query for pairs of geometry types and scalar. See the description in the link for details on how to interpret the table results. The query is symmetric with respect to shape ordering, the pair (ShapeA, ShapeB) will be the same as (ShapeB, ShapeA), so we only fill in half the table.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | 4e-15 | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | 3e-6 | 2e-5 | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | 3e-15 | 2e-5 | 3e-15 | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | 6e-6 | 1e-5 | 6e-6 | 2e-5 | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | 9e-6 | 5e-6 | 9e-6 | 5e-5 | 2e-5 | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | 3e-15 | 6e-15 | 3e-6 | 5e-15 | 4e-5 | 3e-15 | ᶜ | 6e-15 | *Table 4*: Worst observed error (in m) for 2mm penetration/separation between geometries approximately 20cm in size for
T
=double
.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵇ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵇ | throwsᵇ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | 2e-15 | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | 2e-15 | ᶜ | 5e-15 | *Table 5*: Worst observed error (in m) for 2mm penetration/separation between geometries approximately 20cm in size for
T
= drake::AutoDiffXd “AutoDiffXd”.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵈ | throwsᵈ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ᶜ | throwsᵈ | *Table 6*: Support for
T
= drake::symbolic::Expression.ᵃ We don’t currently support queries between HalfSpace and any other shape
(except for Sphere). - ᵇ These results are simply not supported for
T
= drake::AutoDiffXd “AutoDiffXd” at this time. - ᶜ Meshes are represented by the convex hull of the mesh, therefore the results for Mesh are the same as for Convex. - ᵈ These results are simply not supported forT
= drake::symbolic::Expression at this time.Characterizing the returned gradients
In most cases, the returned gradient vectors are the normalized displacement vectors between two witness points. However, when two geometries touch at zero distance, their witness points have a zero displacement vector that we cannot normalize.
When two geometries touch at zero distance, we have special implementation to choose reasonable gradients for some cases shown as “Ok” in the table below. Otherwise, they are “NaN” in the table. In general, we try to choose the gradient, when two geometries touch, in the most consistent way, but the problem sometimes doesn’t have a unique solution. For example, any direction is qualified to be the gradient for two concentric spheres. Or two boxes touching at their vertices can pick a gradient from a continuous family of directions.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | Ok | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | NaN | NaN | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | NaN | NaN | NaN | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | NaN | NaN | NaN | NaN | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | NaN | NaN | NaN | NaN | NaN | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | NaN | NaN | NaN | NaN | NaN | NaN | ░░░░░ | ░░░░░ | | Mesh | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ░░░░░ | | Sphere | Ok | Ok | Okᵃ | Ok | Okᵃ | Ok | Okᵃ | Ok | *Table 7*: Support for signed-distance gradients when two geometries touch at zero distance.
ᵃ Return the gradient as a Vector3d of NaN if the sphere has zero radius.
- Parameter
max_distance
: The maximum distance at which distance data is reported.
- Returns
The signed distance (and supporting data) for all unfiltered geometry pairs whose distance is less than or equal to
max_distance
. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.- Raises
RuntimeError as indicated in the table above. –
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- ComputeSignedDistanceToPoint(self: pydrake.geometry.QueryObject_[AutoDiffXd], p_WQ: numpy.ndarray[object[3, 1]], threshold: float = inf) list[drake::geometry::SignedDistanceToPoint<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >]
Computes the signed distances and gradients to a query point from each geometry in the scene.
This query provides φᵢ(p), φᵢ:ℝ³→ℝ, the signed distance to the position p of a query point from geometry Gᵢ in the scene. It returns an array of the signed distances from all geometries.
Optionally you can specify a threshold distance that will filter out any object beyond the threshold. By default, we report distances from the query point to every object.
This query also provides the gradient vector ∇φᵢ(p) of the signed distance function from geometry Gᵢ. Note that, in general, if p is outside Gᵢ, then ∇φᵢ(p) equals the unit vector in the direction from the nearest point Nᵢ on Gᵢ’s surface to p. If p is inside Gᵢ, then ∇φᵢ(p) is in the direction from p to Nᵢ. This observation is written formally as:
∇φᵢ(p) = (p - Nᵢ)/|p - Nᵢ| if p is outside Gᵢ
∇φᵢ(p) = -(p - Nᵢ)/|p - Nᵢ| if p is inside Gᵢ
Note that ∇φᵢ(p) is also defined on Gᵢ’s surface, but we cannot use the above formula.
Characterizing the returned values
This table is a variant of that described in this query_object_precision_methodology “class’s documentation”. The query evaluates signed distance between one shape and a point (in contrast to other queries which involve two shapes). Therefore, we don’t need a matrix of shape pairs, but a list of shapes. Otherwise, the methodology is the same as described, with the point being represented as a zero-radius sphere.
Scalar | Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace |Mesh | Sphere | | :——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | double | 2e-15 | 4e-15 | ᵃ | 3e-15 | 3e-5ᵇ | 5e-15 | ᵃ | 4e-15 | | AutoDiffXd | 1e-15 | 4e-15 | ᵃ | ᵃ | ᵃ | 5e-15 | ᵃ | 3e-15 | | Expression | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | *Table 8*: Worst observed error (in m) for 2mm penetration/separation between geometry approximately 20cm in size and a point.
ᵃ Unsupported geometry/scalar combinations are simply ignored; no results
are reported for that geometry. - ᵇ This uses an iterative algorithm which introduces a relatively large and variable error. For example, as the eccentricity of the ellipsoid increases, this error may get worse. It also depends on the location of the projection of the query point on the ellipsoid; the closer that point is to the high curvature area, the bigger the effect. It is not immediately clear how much worse the answer will get.
Note
For a sphere G, the signed distance function φᵢ(p) has an undefined gradient vector at the center of the sphere–every point on the sphere’s surface has the same distance to the center. In this case, we will assign ∇φᵢ(p) the unit vector Gx (x-directional vector of G’s frame) expressed in World frame.
Note
For a box, at a point p on an edge or a corner of the box, the signed distance function φᵢ(p) has an undefined gradient vector. In this case, we will assign a unit vector in the direction of the average of the outward face unit normals of the incident faces of the edge or the corner. A point p is considered being on a face, or an edge, or a corner of the box if it lies within a certain tolerance from them.
Note
For a box B, if a point p is inside the box, and it is equidistant to multiple nearest faces, the signed distance function φᵢ(p) at p will have an undefined gradient vector. There is a nearest point candidate associated with each nearest face. In this case, we arbitrarily pick the point Nᵢ associated with one of the nearest faces. Please note that, due to the possible round off error arising from applying a pose X_WG to B, there is no guarantee which of the nearest faces will be used.
Note
The signed distance function is a continuous function with respect to the position of the query point, but its gradient vector field may not be continuous. Specifically at a position equidistant to multiple nearest points, its gradient vector field is not continuous.
Note
For a convex object, outside the object at positive distance from the boundary, the signed distance function is smooth (having continuous first-order partial derivatives).
- Parameter
p_WQ
: Position of a query point Q in world frame W.
- Parameter
threshold
: We ignore any object beyond this distance. By default, it is infinity, so we report distances from the query point to every object.
- Returns
signed_distances
: A vector populated with per-object signed distance values (and supporting data) for every supported geometry as shown in the table. See SignedDistanceToPoint. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
- FindCollisionCandidates(self: pydrake.geometry.QueryObject_[AutoDiffXd]) list[drake::SortedPair<drake::geometry::GeometryId>]
Applies a conservative culling mechanism to create a subset of all possible geometry pairs based on non-zero intersections. A geometry pair that is absent from the results is either a) culled by collision filters or b) known to be separated. The caller is responsible for confirming that the remaining, unculled geometry pairs are actually in collision.
- Returns
A vector populated with collision pair candidates (the order will remain constant for a fixed population but can change as geometry ids are added/removed).
- GetPoseInParent(self: pydrake.geometry.QueryObject_[AutoDiffXd], frame_id: pydrake.geometry.FrameId) pydrake.math.RigidTransform_[AutoDiffXd]
Reports the position of the frame indicated by
frame_id
relative to its parent frame. If the frame was registered with the world frame as its parent frame, this value will be identical to that returned by GetPoseInWorld().- Raises
RuntimeError if the frame frame_id is not valid. –
- GetPoseInWorld(*args, **kwargs)
Overloaded function.
GetPoseInWorld(self: pydrake.geometry.QueryObject_[AutoDiffXd], frame_id: pydrake.geometry.FrameId) -> pydrake.math.RigidTransform_[AutoDiffXd]
Reports the position of the frame indicated by
frame_id
relative to the world frame.- Raises
RuntimeError if the frame frame_id is not valid. –
GetPoseInWorld(self: pydrake.geometry.QueryObject_[AutoDiffXd], geometry_id: pydrake.geometry.GeometryId) -> pydrake.math.RigidTransform_[AutoDiffXd]
Reports the position of the frame of the rigid geometry indicated by
geometry_id
relative to the world frame (X_WG).Note
This query is meaningless for deformable geometries. Their current state cannot be represented by a single rigid transformation. Instead, one should use GetConfigurationsInWorld() to get the current vertex positions of the deformable geometry in the world frame. On the other hand, it is meaningful to query the fixed pose of the reference geometry in its parent frame (see SceneGraphInspector::GetPoseInFrame()).
- Raises
RuntimeError if the geometry geometry_id is not valid or if it –
is deformable. –
- HasCollisions(self: pydrake.geometry.QueryObject_[AutoDiffXd]) bool
Reports true if there are any collisions between unfiltered pairs in the world.
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- inspector(self: pydrake.geometry.QueryObject_[AutoDiffXd]) pydrake.geometry.SceneGraphInspector_[AutoDiffXd]
Provides an inspector for the topological structure of the underlying scene graph data (see SceneGraphInspector for details).
- RenderColorImage(self: pydrake.geometry.QueryObject_[AutoDiffXd], camera: pydrake.geometry.ColorRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)2>
Renders an RGB image for the given
camera
posed with respect to the indicated parent frame P.- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
color_image_out
: The rendered color image.
- Parameter
- RenderDepthImage(self: pydrake.geometry.QueryObject_[AutoDiffXd], camera: pydrake.geometry.DepthRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)6>
Renders a depth image for the given
camera
posed with respect to the indicated parent frame P.In contrast to the other rendering methods, rendering depth images doesn’t provide the option to display the window; generally, basic depth images are not readily communicative to humans.
- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
depth_image_out
: The rendered depth image.
- Parameter
- RenderLabelImage(self: pydrake.geometry.QueryObject_[AutoDiffXd], camera: pydrake.geometry.ColorRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)7>
Renders a label image for the given
camera
posed with respect to the indicated parent frame P.- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
label_image_out
: The rendered label image.
- Parameter
- class pydrake.geometry.QueryObject_[Expression]
The QueryObject serves as a mechanism to perform geometry queries on the world’s geometry. The SceneGraph has an abstract-valued port that contains a QueryObject (i.e., a QueryObject-valued output port).
To perform geometry queries on SceneGraph: - a LeafSystem must have a QueryObject-valued input port and connect it to the corresponding query output port on SceneGraph, - the querying LeafSystem can evaluate the input port, retrieving a
const QueryObject&
in return, and, finally, - invoke the appropriate method on the QueryObject.The const reference returned by the input port is considered “live” - it is linked to the context, system, and cache (making full use of all of those mechanisms). This const reference should never be persisted; doing so can lead to erroneous query results. It is simpler and more advisable to acquire it for evaluation in a limited scope (e.g., CalcTimeDerivatives()) and then discard it. If a QueryObject is needed for many separate functions in a LeafSystem, each should re-evaluate the input port. The underlying caching mechanism should make the cost of this negligible.
The QueryObject can be copied. The copied instance is no longer “live”; it is now “baked”. Essentially, it freezes the state of the live scene graph in its current configuration and disconnects it from the system and context. This means, even if the original context changes values, the copied/baked instance will always reproduce the same query results. This baking process is not cheap and should not be done without consideration.
A QueryObject cannot be converted to a different scalar type. A QueryObject of scalar type T can only be acquired from the output port of a SceneGraph of type T evaluated on a corresponding Context, also of type T.
QueryObject’s support for arbitrary scalar type is incomplete. Not all queries support all scalar types to the same degree. Furthermore, the queries are typically served by families of algorithms. The evaluation of a query between a particular pair of geometries will depend on the query, the pair of geometry types involved, and the scalar type. From query to query, the treatment of a geometry (or geometry pair) for a given scalar type can vary in many ways, including but not limited to: ignoring the geometry, throwing an exception, results with limited precision, or full, accurate support. The queries below provide tables to help inform your expectations when evaluating queries. The tables all use a common methodology and admit a common interpretation.
For each (query, geometry-pair, scalar) combination, we create a set of geometric configurations with known answers. We evaluate the precision of the query result (if supported at all) over the entire set and report the worst observed error. This is a purely empirical approach and doesn’t fully characterize the families of underlying algorithms, and the reported error may be misleading in that we’ve missed far worse latent error or that the error reported doesn’t well represent the average case.
The families of algorithms also differ in how their inherent errors scale with the scale of the problem (e.g., size of geometries, magnitude of distance/depth, etc.) Attempting to fully characterize that aspect is both arduous and problematic, so, we’ve chosen a more representative approach.
Because Drake is primarily intended for robot simulation, we’ve created geometric configurations on the scale of common robot manipulators (on the order of 20cm). We position them with a known penetration depth (or separating distance) of 2 mm. The error reported is the deviation from that expected result.
When interpreting the tables, keep the following in mind: - The table illustrates trends in broad strokes, only. It does not represent an exhaustive analysis. - If your problem involves larger geometries, greater penetration depths, or larger separating distances, the error will vary. Do not assume that observed error in this context is necessarily relative – there truly is that much variability in the families of algorithms. - These values are an attempt to capture the worst case outcome. The error shown is a single-significant-digit approximation of that observed error. - These values may not actually represent the true worst case; discovering the true worst case is generally challenging. These represent our best effort to date. If you find outcomes that are worse those reported here, please ` submit a bug <https://github.com/RobotLocomotion/drake/issues/new>`_. - These tables represent Drake’s transient state. The eventual goal is to report no more than 1e-14 error across all supportable geometry pairs and scalars. At that point, the table will simply disappear.
- __init__(self: pydrake.geometry.QueryObject_[Expression]) None
Constructs a default QueryObject (all pointers are null).
- ComputePointPairPenetration(self: pydrake.geometry.QueryObject_[Expression]) list[drake::geometry::PenetrationAsPointPair<drake::symbolic::Expression>]
Computes the penetrations across all pairs of geometries in the world with the penetrations characterized by pairs of points (see PenetrationAsPointPair), providing some measure of the penetration “depth” of the two objects, but not the overlapping volume.
Only reports results for penetrating geometries; if two geometries are separated, there will be no result for that pair. Geometries whose surfaces are just touching (osculating) are not considered in penetration. Surfaces whose penetration is within an epsilon of osculation, are likewise not considered penetrating. Pairs of anchored geometry are also not reported. This method is affected by collision filtering.
For two penetrating geometries g_A and g_B, it is guaranteed that they will map to
id_A
andid_B
in a fixed, repeatable manner.Characterizing the returned values
As discussed in the query_object_precision_methodology “class’s documentation”, these tables document the support given by this query for pairs of geometry types and scalar. See the description in the link for details on how to interpret the tables’ results. The query is symmetric with respect to shape ordering, the pair (ShapeA, ShapeB) will be the same as (ShapeB, ShapeA), so we only fill in half of each table.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | 2e-15 | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | 3e-5ᶜ | 2e-5ᶜ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | 2e-15ᶜ | 3e-5ᶜ | 2e-15ᶜ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | 1e-3ᶜ | 4e-5ᶜ | 1e-3ᶜ | 2e-3ᶜ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | 4e-4ᶜ | 2e-4ᶜ | 4e-4ᶜ | 2e-3ᶜ | 5e-4ᶜ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | 6e-15 | 4e-15 | 3e-15ᶜ | 4e-15 | 3e-15 | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | 3e-15 | 5e-15 | 3e-5ᶜ | 5e-15 | 2e-4ᶜ | 3e-15 | ᵇ | 5e-15 | *Table 1*: Worst observed error (in m) for 2mm penetration between geometries approximately 20cm in size for
T
=double
.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵈ | throwsᵈ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | 2e-15 | 3e-15 | throwsᵈ | 2e-15 | throwsᵈ | 2e-15 | ᵇ | 5e-15 | *Table 2*: Worst observed error (in m) for 2mm penetration between geometries approximately 20cm in size for
T
= drake::AutoDiffXd “AutoDiffXd”.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵉ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵉ | throwsᵉ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ᵇ | ░░░░░ | | Sphere | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | throwsᵉ | ᵇ | throwsᵉ | *Table 3*: Support for
T
= drake::symbolic::Expression.ᵃ Penetration depth between two HalfSpace instances has no meaning; either
they don’t intersect, or they have infinite penetration. - ᵇ Meshes are represented by the convex hull of the mesh, therefore the results for Mesh are assumed to be the same as for Convex. - ᶜ These results are computed using an iterative algorithm. For particular configurations, the solution may be correct to machine precision. The values reported here are confirmed, observed worst case answers. - ᵈ These results are simply not supported for
T
= drake::AutoDiffXd “AutoDiffXd” at this time. - ᵉ These results are simply not supported forT
= drake::symbolic::Expression at this time.- Returns
A vector populated with all detected penetrations characterized as point pairs. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- Raises
RuntimeError if a Shape-Shape pair is in collision and indicated –
as throws in the support table above. –
- ComputeSignedDistancePairClosestPoints(self: pydrake.geometry.QueryObject_[Expression], geometry_id_A: pydrake.geometry.GeometryId, geometry_id_B: pydrake.geometry.GeometryId) drake::geometry::SignedDistancePair<drake::symbolic::Expression>
A variant of ComputeSignedDistancePairwiseClosestPoints() which computes the signed distance (and witnesses) between a specific pair of geometries indicated by id. This function has the same restrictions on scalar report as ComputeSignedDistancePairwiseClosestPoints().
Note
This query is unique among the distance queries in that it doesn’t respect collision filters. As long as the geometry ids refer to geometries with proximity roles, signed distance can be computed (subject to supported scalar tables above).
Characterizing the returned values
This method merely exercises the same mechanisms as ComputeSignedDistancePairwiseClosestPoints() for evaluating signed distance. Refer to query_object_compute_pairwise_distance_table “the table for ComputeSignedDistancePairwiseClosestPoints()” for details.
- Raises
RuntimeError if either geometry id is invalid (e.g., doesn't refer –
to an existing geometry, lacking proximity role, etc.), the pair –
is unsupported as indicated by the scalar support table. –
Warning
For Mesh shapes, their convex hulls are used in this query. It is not computationally efficient or particularly accurate.
- ComputeSignedDistancePairwiseClosestPoints(self: pydrake.geometry.QueryObject_[Expression], max_distance: float = inf) list[drake::geometry::SignedDistancePair<drake::symbolic::Expression>]
Computes the signed distance together with the nearest points across all pairs of geometries in the world. Reports both the separating geometries and penetrating geometries.
This query provides φ(A, B), the signed distance between two objects A and B.
If the objects do not overlap (i.e., A ⋂ B = ∅), φ > 0 and represents the minimal distance between the two objects. More formally: φ = min(|Aₚ - Bₚ|) ∀ Aₚ ∈ A and Bₚ ∈ B.
Note
The pair (Aₚ, Bₚ) is a “witness” of the distance. The pair need not be unique (think of two parallel planes).
If the objects touch or overlap (i.e., A ⋂ B ≠ ∅), φ ≤ 0 and can be interpreted as the negative penetration depth. It is the smallest length of the vector v, such that by shifting one object along that vector relative to the other, the two objects will no longer be overlapping. More formally, φ(A, B) = -min |v|. s.t (Tᵥ · A) ⋂ B = ∅ where Tᵥ is a rigid transformation that displaces A by the vector v, namely Tᵥ · A = {u + v | ∀ u ∈ A}. By implication, there exist points Aₚ and Bₚ on the surfaces of objects A and B, respectively, such that Aₚ + v = Bₚ, Aₚ ∈ A ∩ B, Bₚ ∈ A ∩ B. These points are the witnesses to the penetration.
This method is affected by collision filtering; geometry pairs that have been filtered will not produce signed distance query results.
For a geometry pair (A, B), the returned results will always be reported in a fixed order (e.g., always (A, B) and never (B, A)). The basis for the ordering is arbitrary (and therefore undocumented), but guaranteed to be fixed and repeatable.
Notice that this is an O(N²) operation, where N is the number of geometries remaining in the world after applying collision filter. We report the distance between dynamic objects, and between dynamic and anchored objects. We DO NOT report the distance between two anchored objects.
Using maximum distance
While the algorithm generally has O(N²) complexity in time and space, that can be reduced by the judicious use of the
max_distance
parameter. Ifφ(A, B) > max_distance
, the pair (A, B) will not be included in the results (making it O(M²) in space where M < N). Furthermore, the broadphase culling algorithm can exploitmax_distance
to cheaply eliminate pairs of geometry that are “obviously” too far (likewise reducing the time complexity).Passing
max_distance = 0
is conceptually related to calling HasCollisions(). If contact is sparse (very few actually contacting geometry pairs), the two invocations will be quite similar in cost. However, the distinction between the two is that this method would have to include all pairs that satisfyφ(A, B) <= 0
, whereas HasCollisions() stops at the first. So, the more actually colliding geometry pairs there are, the bigger the difference in cost between the two approaches.Characterizing the returned values
As discussed in the query_object_precision_methodology “class’s documentation”, this table documents the support given by this query for pairs of geometry types and scalar. See the description in the link for details on how to interpret the table results. The query is symmetric with respect to shape ordering, the pair (ShapeA, ShapeB) will be the same as (ShapeB, ShapeA), so we only fill in half the table.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | 4e-15 | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | 3e-6 | 2e-5 | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | 3e-15 | 2e-5 | 3e-15 | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | 6e-6 | 1e-5 | 6e-6 | 2e-5 | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | 9e-6 | 5e-6 | 9e-6 | 5e-5 | 2e-5 | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | 3e-15 | 6e-15 | 3e-6 | 5e-15 | 4e-5 | 3e-15 | ᶜ | 6e-15 | *Table 4*: Worst observed error (in m) for 2mm penetration/separation between geometries approximately 20cm in size for
T
=double
.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵇ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵇ | throwsᵇ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | 2e-15 | throwsᵇ | throwsᵇ | throwsᵇ | throwsᵇ | 2e-15 | ᶜ | 5e-15 | *Table 5*: Worst observed error (in m) for 2mm penetration/separation between geometries approximately 20cm in size for
T
= drake::AutoDiffXd “AutoDiffXd”.| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | throwsᵈ | throwsᵈ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | throwsᵃ | ░░░░░ | ░░░░░ | | Mesh | ᶜ | ᶜ | ᶜ | ᶜ | ᶜ | throwsᵃ | ᶜ | ░░░░░ | | Sphere | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | throwsᵈ | ᶜ | throwsᵈ | *Table 6*: Support for
T
= drake::symbolic::Expression.ᵃ We don’t currently support queries between HalfSpace and any other shape
(except for Sphere). - ᵇ These results are simply not supported for
T
= drake::AutoDiffXd “AutoDiffXd” at this time. - ᶜ Meshes are represented by the convex hull of the mesh, therefore the results for Mesh are the same as for Convex. - ᵈ These results are simply not supported forT
= drake::symbolic::Expression at this time.Characterizing the returned gradients
In most cases, the returned gradient vectors are the normalized displacement vectors between two witness points. However, when two geometries touch at zero distance, their witness points have a zero displacement vector that we cannot normalize.
When two geometries touch at zero distance, we have special implementation to choose reasonable gradients for some cases shown as “Ok” in the table below. Otherwise, they are “NaN” in the table. In general, we try to choose the gradient, when two geometries touch, in the most consistent way, but the problem sometimes doesn’t have a unique solution. For example, any direction is qualified to be the gradient for two concentric spheres. Or two boxes touching at their vertices can pick a gradient from a continuous family of directions.
| Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace | Mesh |Sphere | | ——–: | :–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | Box | Ok | ░░░░░░ | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Capsule | NaN | NaN | ░░░░░ | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Convex | NaN | NaN | NaN | ░░░░░░░ | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Cylinder | NaN | NaN | NaN | NaN | ░░░░░░ | ░░░░░░ | ░░░░░ | ░░░░░ | | Ellipsoid | NaN | NaN | NaN | NaN | NaN | ░░░░░░ | ░░░░░ | ░░░░░ | | HalfSpace | NaN | NaN | NaN | NaN | NaN | NaN | ░░░░░ | ░░░░░ | | Mesh | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ░░░░░ | | Sphere | Ok | Ok | Okᵃ | Ok | Okᵃ | Ok | Okᵃ | Ok | *Table 7*: Support for signed-distance gradients when two geometries touch at zero distance.
ᵃ Return the gradient as a Vector3d of NaN if the sphere has zero radius.
- Parameter
max_distance
: The maximum distance at which distance data is reported.
- Returns
The signed distance (and supporting data) for all unfiltered geometry pairs whose distance is less than or equal to
max_distance
. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.- Raises
RuntimeError as indicated in the table above. –
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- ComputeSignedDistanceToPoint(self: pydrake.geometry.QueryObject_[Expression], p_WQ: numpy.ndarray[object[3, 1]], threshold: float = inf) list[drake::geometry::SignedDistanceToPoint<drake::symbolic::Expression>]
Computes the signed distances and gradients to a query point from each geometry in the scene.
This query provides φᵢ(p), φᵢ:ℝ³→ℝ, the signed distance to the position p of a query point from geometry Gᵢ in the scene. It returns an array of the signed distances from all geometries.
Optionally you can specify a threshold distance that will filter out any object beyond the threshold. By default, we report distances from the query point to every object.
This query also provides the gradient vector ∇φᵢ(p) of the signed distance function from geometry Gᵢ. Note that, in general, if p is outside Gᵢ, then ∇φᵢ(p) equals the unit vector in the direction from the nearest point Nᵢ on Gᵢ’s surface to p. If p is inside Gᵢ, then ∇φᵢ(p) is in the direction from p to Nᵢ. This observation is written formally as:
∇φᵢ(p) = (p - Nᵢ)/|p - Nᵢ| if p is outside Gᵢ
∇φᵢ(p) = -(p - Nᵢ)/|p - Nᵢ| if p is inside Gᵢ
Note that ∇φᵢ(p) is also defined on Gᵢ’s surface, but we cannot use the above formula.
Characterizing the returned values
This table is a variant of that described in this query_object_precision_methodology “class’s documentation”. The query evaluates signed distance between one shape and a point (in contrast to other queries which involve two shapes). Therefore, we don’t need a matrix of shape pairs, but a list of shapes. Otherwise, the methodology is the same as described, with the point being represented as a zero-radius sphere.
Scalar | Box | Capsule | Convex | Cylinder | Ellipsoid | HalfSpace |Mesh | Sphere | | :——–: | :—–: | :——: | :—–: | :——-: | :——–: | :——–: | :—–: | :—–: | | double | 2e-15 | 4e-15 | ᵃ | 3e-15 | 3e-5ᵇ | 5e-15 | ᵃ | 4e-15 | | AutoDiffXd | 1e-15 | 4e-15 | ᵃ | ᵃ | ᵃ | 5e-15 | ᵃ | 3e-15 | | Expression | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | ᵃ | *Table 8*: Worst observed error (in m) for 2mm penetration/separation between geometry approximately 20cm in size and a point.
ᵃ Unsupported geometry/scalar combinations are simply ignored; no results
are reported for that geometry. - ᵇ This uses an iterative algorithm which introduces a relatively large and variable error. For example, as the eccentricity of the ellipsoid increases, this error may get worse. It also depends on the location of the projection of the query point on the ellipsoid; the closer that point is to the high curvature area, the bigger the effect. It is not immediately clear how much worse the answer will get.
Note
For a sphere G, the signed distance function φᵢ(p) has an undefined gradient vector at the center of the sphere–every point on the sphere’s surface has the same distance to the center. In this case, we will assign ∇φᵢ(p) the unit vector Gx (x-directional vector of G’s frame) expressed in World frame.
Note
For a box, at a point p on an edge or a corner of the box, the signed distance function φᵢ(p) has an undefined gradient vector. In this case, we will assign a unit vector in the direction of the average of the outward face unit normals of the incident faces of the edge or the corner. A point p is considered being on a face, or an edge, or a corner of the box if it lies within a certain tolerance from them.
Note
For a box B, if a point p is inside the box, and it is equidistant to multiple nearest faces, the signed distance function φᵢ(p) at p will have an undefined gradient vector. There is a nearest point candidate associated with each nearest face. In this case, we arbitrarily pick the point Nᵢ associated with one of the nearest faces. Please note that, due to the possible round off error arising from applying a pose X_WG to B, there is no guarantee which of the nearest faces will be used.
Note
The signed distance function is a continuous function with respect to the position of the query point, but its gradient vector field may not be continuous. Specifically at a position equidistant to multiple nearest points, its gradient vector field is not continuous.
Note
For a convex object, outside the object at positive distance from the boundary, the signed distance function is smooth (having continuous first-order partial derivatives).
- Parameter
p_WQ
: Position of a query point Q in world frame W.
- Parameter
threshold
: We ignore any object beyond this distance. By default, it is infinity, so we report distances from the query point to every object.
- Returns
signed_distances
: A vector populated with per-object signed distance values (and supporting data) for every supported geometry as shown in the table. See SignedDistanceToPoint. The ordering of the results is guaranteed to be consistent – for fixed geometry poses, the results will remain the same.
- FindCollisionCandidates(self: pydrake.geometry.QueryObject_[Expression]) list[drake::SortedPair<drake::geometry::GeometryId>]
Applies a conservative culling mechanism to create a subset of all possible geometry pairs based on non-zero intersections. A geometry pair that is absent from the results is either a) culled by collision filters or b) known to be separated. The caller is responsible for confirming that the remaining, unculled geometry pairs are actually in collision.
- Returns
A vector populated with collision pair candidates (the order will remain constant for a fixed population but can change as geometry ids are added/removed).
- GetPoseInParent(self: pydrake.geometry.QueryObject_[Expression], frame_id: pydrake.geometry.FrameId) pydrake.math.RigidTransform_[Expression]
Reports the position of the frame indicated by
frame_id
relative to its parent frame. If the frame was registered with the world frame as its parent frame, this value will be identical to that returned by GetPoseInWorld().- Raises
RuntimeError if the frame frame_id is not valid. –
- GetPoseInWorld(*args, **kwargs)
Overloaded function.
GetPoseInWorld(self: pydrake.geometry.QueryObject_[Expression], frame_id: pydrake.geometry.FrameId) -> pydrake.math.RigidTransform_[Expression]
Reports the position of the frame indicated by
frame_id
relative to the world frame.- Raises
RuntimeError if the frame frame_id is not valid. –
GetPoseInWorld(self: pydrake.geometry.QueryObject_[Expression], geometry_id: pydrake.geometry.GeometryId) -> pydrake.math.RigidTransform_[Expression]
Reports the position of the frame of the rigid geometry indicated by
geometry_id
relative to the world frame (X_WG).Note
This query is meaningless for deformable geometries. Their current state cannot be represented by a single rigid transformation. Instead, one should use GetConfigurationsInWorld() to get the current vertex positions of the deformable geometry in the world frame. On the other hand, it is meaningful to query the fixed pose of the reference geometry in its parent frame (see SceneGraphInspector::GetPoseInFrame()).
- Raises
RuntimeError if the geometry geometry_id is not valid or if it –
is deformable. –
- HasCollisions(self: pydrake.geometry.QueryObject_[Expression]) bool
Reports true if there are any collisions between unfiltered pairs in the world.
Warning
For Mesh shapes, their convex hulls are used in this query. It is not* computationally efficient or particularly accurate.
- inspector(self: pydrake.geometry.QueryObject_[Expression]) pydrake.geometry.SceneGraphInspector_[Expression]
Provides an inspector for the topological structure of the underlying scene graph data (see SceneGraphInspector for details).
- RenderColorImage(self: pydrake.geometry.QueryObject_[Expression], camera: pydrake.geometry.ColorRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)2>
Renders an RGB image for the given
camera
posed with respect to the indicated parent frame P.- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
color_image_out
: The rendered color image.
- Parameter
- RenderDepthImage(self: pydrake.geometry.QueryObject_[Expression], camera: pydrake.geometry.DepthRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)6>
Renders a depth image for the given
camera
posed with respect to the indicated parent frame P.In contrast to the other rendering methods, rendering depth images doesn’t provide the option to display the window; generally, basic depth images are not readily communicative to humans.
- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
depth_image_out
: The rendered depth image.
- Parameter
- RenderLabelImage(self: pydrake.geometry.QueryObject_[Expression], camera: pydrake.geometry.ColorRenderCamera, parent_frame: pydrake.geometry.FrameId, X_PC: pydrake.math.RigidTransform) drake::systems::sensors::Image<(drake::systems::sensors::PixelType)7>
Renders a label image for the given
camera
posed with respect to the indicated parent frame P.- Parameter
camera
: The camera to render from.
- Parameter
parent_frame
: The id for the camera’s parent frame.
- Parameter
X_PC
: The pose of the camera body in the parent frame.
- Parameter
label_image_out
: The rendered label image.
- Parameter
- pydrake.geometry.ReadObjToTriangleSurfaceMesh(filename: str, scale: float = 1.0) pydrake.geometry.TriangleSurfaceMesh
Constructs a surface mesh from a Wavefront .obj file and optionally scales coordinates by the given scale factor. Polygons will be triangulated if they are not triangles already. All objects in the .obj file will be merged into the surface mesh. See https://en.wikipedia.org/wiki/Wavefront_.obj_file for the file format.
- Parameter
filename
: A valid file name with absolute path or relative path.
- Parameter
scale
: An optional scale to coordinates.
- Parameter
on_warning
: An optional callback that will receive warning message(s) encountered while reading the mesh. When not provided, drake::log() will be used.
- Raises
RuntimeError if filename doesn't have a valid file path, or –
the file has no faces. –
- Returns
surface mesh
- Parameter
- class pydrake.geometry.RenderCameraCore
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.RenderCameraCore, other: pydrake.geometry.RenderCameraCore) -> None
Copy constructor
__init__(self: pydrake.geometry.RenderCameraCore, renderer_name: str, intrinsics: drake::systems::sensors::CameraInfo, clipping: pydrake.geometry.ClippingRange, X_BS: pydrake.math.RigidTransform) -> None
Fully-specified constructor. See the documentation on the member getter methods for documentation of parameters.
- clipping(self: pydrake.geometry.RenderCameraCore) pydrake.geometry.ClippingRange
The near and far clipping planes for this camera. This property is ignored by RenderEngine implementations that don’t use a clipping frustum.
- intrinsics(self: pydrake.geometry.RenderCameraCore) drake::systems::sensors::CameraInfo
The camera’s intrinsic properties (e.g., focal length, sensor size, etc.) See systems::sensors::CameraInfo for details.
- renderer_name(self: pydrake.geometry.RenderCameraCore) str
The name of the render engine this camera should be used with.
- sensor_pose_in_camera_body(self: pydrake.geometry.RenderCameraCore) pydrake.math.RigidTransform
The pose of the sensor frame (S) in the camera’s body frame (B). This is the “imager” referred to in systems::sensors::CameraInfo’s documentation.
- class pydrake.geometry.RenderEngine
- __init__(self: pydrake.geometry.RenderEngine) None
Constructs a RenderEngine with the given default render label. The default render label is applied to geometries that have not otherwise specified a (label, id) property. The value must be either RenderLabel::kUnspecified or RenderLabel::kDontCare. (See render_engine_default_label “this section” for more details.)
- Raises
RuntimeError if the default render label is not one of the two –
allowed labels. –
- Clone(self: pydrake.geometry.RenderEngine) pydrake.geometry.RenderEngine
Clones the render engine – making the RenderEngine compatible with copyable_unique_ptr.
- default_render_label(self: pydrake.geometry.RenderEngine) drake::geometry::render::RenderLabel
Reports the render label value this render engine has been configured to use.
- GetRenderLabelOrThrow(self: pydrake.geometry.RenderEngine, properties: pydrake.geometry.PerceptionProperties) drake::geometry::render::RenderLabel
Extracts the
(label, id)
RenderLabel property from the givenproperties
and validates it (or the configured default if no such property is defined).- Raises
RuntimeError If the tested render label value is deemed invalid. –
- has_geometry(self: pydrake.geometry.RenderEngine, id: pydrake.geometry.GeometryId) bool
Reports true if a geometry with the given
id
has been registered withthis
engine.
- RegisterVisual(self: pydrake.geometry.RenderEngine, id: pydrake.geometry.GeometryId, shape: pydrake.geometry.Shape, properties: pydrake.geometry.PerceptionProperties, X_WG: pydrake.math.RigidTransform, needs_updates: bool = True) bool
Requests registration of the given shape as a rigid geometry with this render engine.
- Parameter
id
: The geometry id of the shape to register.
- Parameter
shape
: The shape specification to add to the render engine.
- Parameter
properties
: The perception properties provided for this geometry.
- Parameter
X_WG
: The pose of the geometry relative to the world frame W.
- Parameter
needs_updates
: If true, the geometry’s pose will be updated via UpdatePoses().
- Returns
True if the RenderEngine implementation accepted the shape for registration.
- Raises
RuntimeError if the shape is an unsupported type, the shape's –
RenderLabel value is RenderLabel::kUnspecified or –
RenderLabel::kEmpty, or a geometry has already been registered –
with the given id. –
- Parameter
- RemoveGeometry(self: pydrake.geometry.RenderEngine, id: pydrake.geometry.GeometryId) bool
Removes the geometry indicated by the given
id
from the engine.- Parameter
id
: The id of the geometry to remove.
- Returns
True if the geometry was removed (false implies that this id wasn’t registered with this engine).
- Parameter
- RenderColorImage(self: pydrake.geometry.RenderEngine, camera: pydrake.geometry.ColorRenderCamera, color_image_out: drake::systems::sensors::Image<(drake::systems::sensors::PixelType)2>) None
Renders the registered geometry into the given color (rgb) image based on a fully specified camera.
- Parameter
camera
: The render engine camera properties.
- Parameter
color_image_out
: The rendered color image.
- Raises
RuntimeError if color_image_out is nullptr or the size of –
the given input image doesn't match the size declared in –
camera` –
- Parameter
- RenderDepthImage(self: pydrake.geometry.RenderEngine, camera: pydrake.geometry.DepthRenderCamera, depth_image_out: drake::systems::sensors::Image<(drake::systems::sensors::PixelType)6>) None
Renders the registered geometry into the given depth image based on a fully specified camera. In contrast to the other rendering operations, depth images don’t have an option to display the window; generally, basic depth images are not readily communicative to humans.
- Parameter
camera
: The render engine camera properties.
- Parameter
depth_image_out
: The rendered depth image.
- Raises
RuntimeError if depth_image_out is nullptr or the size of –
the given input image doesn't match the size declared in –
camera` –
- Parameter
- RenderLabelImage(self: pydrake.geometry.RenderEngine, camera: pydrake.geometry.ColorRenderCamera, label_image_out: drake::systems::sensors::Image<(drake::systems::sensors::PixelType)7>) None
Renders the registered geometry into the given label image based on a fully specified camera.
Note
This uses the ColorRenderCamera as label images are typically rendered to be exactly registered with a corresponding color image.
- Parameter
camera
: The render engine camera properties.
- Parameter
label_image_out
: The rendered label image.
- Raises
RuntimeError if label_image_out is nullptr or the size of –
the given input image doesn't match the size declared in –
camera` –
- Parameter
- SetDefaultLightPosition(self: pydrake.geometry.RenderEngine, X_DL: numpy.ndarray[numpy.float64[3, 1]]) None
Provides access to the light for manual configuration since it’s currently bound to the camera position. This is a temporary measure to facilitate benchmarking and create visible shadows, and should not be used publicly.
- Parameter
X_DL
: The pose of the light in a frame D that is attached to the camera position. In this frame D, the camera is located at (0, 0, 1), looking towards (0, 0, 0) at a distance of 1, with up being (0, 1, 0).
- Parameter
- static ThrowIfInvalid(*args, **kwargs)
Overloaded function.
ThrowIfInvalid(intrinsics: drake::systems::sensors::CameraInfo, image: drake::systems::sensors::Image<(drake::systems::sensors::PixelType)2>, image_type: str) -> None
ThrowIfInvalid(intrinsics: drake::systems::sensors::CameraInfo, image: drake::systems::sensors::Image<(drake::systems::sensors::PixelType)6>, image_type: str) -> None
ThrowIfInvalid(intrinsics: drake::systems::sensors::CameraInfo, image: drake::systems::sensors::Image<(drake::systems::sensors::PixelType)7>, image_type: str) -> None
- UpdateViewpoint(self: pydrake.geometry.RenderEngine, X_WR: pydrake.math.RigidTransform) None
Updates the renderer’s viewpoint with given pose X_WR.
- Parameter
X_WR
: The pose of renderer’s viewpoint in the world coordinate system.
- Parameter
- class pydrake.geometry.RenderEngineGlParams
Construction parameters for RenderEngineGl.
- __init__(self: pydrake.geometry.RenderEngineGlParams, **kwargs) None
- property default_clear_color
The default background color for color images.
- property default_diffuse
Default diffuse color to apply to a geometry when none is otherwise specified in the (phong, diffuse) property.
- property lights
Lights in the scene. More than five lights is an error. If no lights are defined, a single directional light, fixed to the camera frame, is used.
- class pydrake.geometry.RenderEngineGltfClientParams
Construction parameters for the MakeRenderEngineGltfClient() to create a client as part of the render_engine_gltf_client_server_api.
- __init__(self: pydrake.geometry.RenderEngineGltfClientParams, **kwargs) None
- property base_url
The base url of the server communicate with. See GetUrl() for details.
- property cleanup
Whether or not the client should cleanup files generated / retrieved from the server. By default (
cleanup=true
), after a server image response has been loaded into the client’s memory, the glTF scene file and images will be deleted. To keep the generated scene files or server response images for inspection purposes, setcleanup=false
instead. During the construction process a number of copies and clones are created, whencleanup=false
there will be more than one empty temporary directory created that will not be deleted. The path to the temporary directory can be observed by setting RenderEngineGltfClientParams::verbose toTrue
, or inspecting the parent directory described by drake::temp_directory().
- property render_endpoint
(Advanced) The server endpoint to retrieve renderings from. See GetUrl() for details.
- property verbose
Whether or not the client should log information about which files are being generated, as well as any information about HTTP communications between the client and server such as HTTP header information, url and port, etc. Information is logged at the debug level, so your application will need to logging::set_log_level() to
"debug"
.See also
drake/common/text_logging.h
- class pydrake.geometry.RenderEngineVtkParams
Construction parameters for the RenderEngineVtk.
- __init__(self: pydrake.geometry.RenderEngineVtkParams, **kwargs) None
- property cast_shadows
If
True
, all lights that are able to cast shadows will do so.Several important notes when designing your lighting:
Point lights do not cast shadows.
Directional lights will create a shadow map that spans the whole scene.
If your scene includes a geometry that is significantly larger than the locale you’re rendering, this will significantly reduce the efficacy of the directional light’s shadows. Consider truncating that larger geometry. A common case would be to use a HalfSpace to define a ground. A half space has infinite extent, so any reasonable approximation would be quite large. Better to use a box targeted to where you need it. - Transparent objects cast no shadows at all, but they do receive them.
Currently, there is no way to enable/disable shadows on a per-light basis.
- property default_clear_color
The rgb color to which the color buffer is cleared (each channel in the range [0, 1]). The default value (in byte values) would be [204, 229, 255].
- property default_diffuse
The (optional) rgba color to apply to the (phong, diffuse) property when none is otherwise specified. Note: currently the alpha channel is unused by RenderEngineVtk.
- property environment_map
An optional environment map. When providing the environment map, the render engine will be configured for physically-based rendering (PBR); all materials will be promoted to be a PBR material. This may change the appearance of any geometries introduced as primitives or .obj meshes.
Furthermore, if an environment map is specified, it replaces the default lighting (the map itself illuminates the scene). The usual camera head lamp will not be present. Lights can be explicitly added to combine with the environment map.
- property exposure
Exposure is an aspect of “tone mapping” (as described in VTK’s description of its PBR capabilities). Drake uses the GenericFilmic tone mapper and this value maps to its
exposure
property.By default, exposure is undefined and no tone mapping is applied to the image. Providing any value at all will enable tone mapping and can be done so whether your scene uses default Phong illumination model or physically-based rendering (e.g., such as when an environment map is present or a glTF model has been added).
This property is analogous to the concept of “exposure” in traditional photography. Exposure controls how much the film material is exposed to the light in the scene. Too little exposure and the scene is dark and muddy. Too much exposure, and the image becomes over saturated. As the amount of radiant energy in the scene increases, reducing the exposure may be necessary. In essence, exposure serves as a scale factor on the radiant energy. When thinking about it as a scale factor, it may seem that setting exposure to one would leave the image unchanged (with respect to the images that RenderEngineVtk has historically produced). This is not the case. As noted above, setting any value, including one, enables tone mapping. Without tone mapping enabled, there is a direct correlation between radiant energy on the surface and the final pixel colors. Tone mapping defines a non-linear relationship between illumination levels and pixel color.
The most common use for the
exposure
parameter is to combine an environment map with shadow-casting lights. If the environment map contains a great deal of light energy, it may overpower the strength of your lights. By reducing the exposure (below one), the shadows caused by the lights will become more distinct.If you plan on working with shadows and environment maps, best practice will be to set exposure to one and enable tone mapping. You can increase the value if your image seems too dark, or reduce the value if it seems “washed out”.
- property gltf_extensions
Map from the name of a glTF extension (e.g., “KHR_materials_sheen”) to render engine settings related to that extension.
- property lights
Lights in the scene. If no lights are defined, a single directional light, fixed to the camera frame, is used.
Note: RenderEngineVtk does not have a hard-coded limit on the number of lights; but more lights increases rendering cost. Note: the attenuation values have no effect on VTK directional lights.
- property shadow_map_size
this is a global setting. All shadow casting lights will use a map of the same size. Larger map sizes increase GPU memory usage and rendering times but improve shadow fidelity (less obvious pixelation).
See the note on
cast_shadows
for the warning on directional lights and shadow maps.- Type
The size of texture map (in pixels) to use for shadow maps. Note
- class pydrake.geometry.RenderLabel
Class representing object “labels” for rendering.
In a “label image” (see RenderEngine::RenderLabelImage() for details) each pixel value indicates the classification of the object that rendered into that pixel. The RenderLabel class provides that value and one label is associated with each rendered geometry.
The labels could be unique for each geometry, or multiple geometries could all share the same label (becoming indistinguishable in the label image). Ultimately, it is the user’s responsibility to assign labels in a manner that is meaningful for their application.
Reserved labels
There are several RenderLabels that are reserved. They have specific meaning in the context of the rendering ecosystem and are globally available to all applications. They are:
empty
: a pixel with theempty
RenderLabel value indicates that no
geometry rendered to that pixel. Implemented as RenderLabel::kEmpty. -
do not render
: any geometry assigned thedo not render
tag will not be rendered into a label image. This is a clear declaration that a geometry should be omitted. Useful for marking, e.g., glass windows so that the visible geometry behind the glass is what is included in the label image. Implemented as RenderLabel::kDoNotRender. -don't care
: thedon't care
label is intended as a convenient dumping ground. This would be for geometry that should render into the label image, but whose class is irrelevant (e.g., the walls of a room a robot is working in or the background terrain in driving simulation). Implemented as RenderLabel::kDontCare. -unspecified
: a default-constructed RenderLabel has anunspecified
value. Implemented as RenderLabel::kUnspecified.Generally, there is no good reason to assign
empty
orunspecified
labels to a geometry. A RenderEngine implementation is entitled to throw an exception if you attempt to do so.An application can simply instantiate RenderLabel with an arbitrary value. This allows the application to define a particular mapping from render label class to a preferred RenderLabel value. For a label image to be meaningful, every pixel value should admit an unambiguous interpretation. The application bears full responsibility in making sure that a single value is not inadvertently associated with multiple render classes. Finally, a RenderLabel cannot be explicitly constructed with a reserved value – those can only be accessed through the static methods provided.
Note
The RenderLabel class is based on a 16-bit integer. This makes the label image more compact but means there are only, approximately, 32,000 unique RenderLabel values.
- __init__(self: pydrake.geometry.RenderLabel, value: int) None
Constructs a label with the given
value
.- Raises
RuntimeError if a) is negative, or b) the value is one of the –
reserved values. –
- is_reserved(self: pydrake.geometry.RenderLabel) bool
- kDoNotRender = RenderLabel.kDoNotRender
- kDontCare = RenderLabel.kDontCare
- kEmpty = RenderLabel.kEmpty
- kMaxUnreserved = 32763
- kUnspecified = RenderLabel.kUnspecified
- class pydrake.geometry.Rgba
Defines RGBA (red, green, blue, alpha) values on the range [0, 1].
- __init__(*args, **kwargs)
Overloaded function.
__init__(self: pydrake.geometry.Rgba) -> None
Default constructor produces fully opaque white.
__init__(self: pydrake.geometry.Rgba, r: float, g: float, b: float, a: float = 1.0) -> None
Constructs with given (r, g, b, a) values.
- Precondition:
All values are within the range of [0, 1].
- a(self: pydrake.geometry.Rgba) float
Alpha.
- b(self: pydrake.geometry.Rgba) float
Blue.
- g(self: pydrake.geometry.Rgba) float
Green.
- r(self: pydrake.geometry.Rgba) float
Red.
- property rgba
The RGBA value as a property (as np.ndarray).
- scale_rgb(self: pydrake.geometry.Rgba, scale: float) pydrake.geometry.Rgba
Computes a new Rgba color by multiplying the color channels (rgb) by the given scalar
scalar
. All resultant channel values saturate at one. The result hasthis
Rgba’s alpha values.- Precondition:
scale >= 0.
- set(*args, **kwargs)
Overloaded function.
set(self: pydrake.geometry.Rgba, r: float, g: float, b: float, a: float = 1.0) -> None
Sets (r, g, b, a) values.
- Raises
RuntimeError if any values are outside of the range [0, 1] –
set(self: pydrake.geometry.Rgba, rgba: numpy.ndarray[numpy.float64[m, 1]]) -> None
Sets an (r, g, b, a) from a vector.
- Raises
RuntimeError if the vector is not size 3 or 4. –
RuntimeError if any values are outside of the range [0, 1] –
- update(self: pydrake.geometry.Rgba, r: Optional[float] = None, g: Optional[float] = None, b: Optional[float] = None, a: Optional[float] = None) None
Updates individual (r, g, b, a) values; any values not provided will remain unchanged.
- Raises
RuntimeError if any values are outside of the range [0, 1] –
- class pydrake.geometry.Role
General enumeration for indicating geometry role.
Members:
kUnassigned :
kProximity :
kIllustration :
kPerception :
- __init__(self: pydrake.geometry.Role, value: int) None
- kIllustration = <Role.kIllustration: 2>