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, and properties is not nullptr.

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, and properties is not nullptr.

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 of properties; 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 of properties; 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 < ∞ and properties 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, and height, 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 and length.

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: pydrake.geometry.GeometrySet, set_B: pydrake.geometry.GeometrySet) → pydrake.geometry.CollisionFilterDeclaration

Allows geometry pairs in proximity evaluation by updating the candidate pair set C ← C ⋃ P*, where P = {(a, b)}, ∀ a ∈ A, b ∈ B, a ≠ b and A = {a₀, a₁, ..., aₘ} and B = {b₀, b₁, ..., bₙ} are the input sets of geometries set_A and set_B, respectively. Where P* = 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: pydrake.geometry.GeometrySet) → pydrake.geometry.CollisionFilterDeclaration: Allows geometry pairs in proximity evaluation by updating the candidate pair set C ← C ⋃ P*, where P = {(gᵢ, gⱼ)}, ∀ gᵢ, gⱼ ∈ G, i ≠ j and G = {g₀, g₁, ..., gₘ} is the input geometry_set of geometries. Where P* = 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: pydrake.geometry.GeometrySet, set_B: pydrake.geometry.GeometrySet) → pydrake.geometry.CollisionFilterDeclaration: Excludes geometry pairs from proximity evaluation by updating the candidate pair set C ← C - P, where P = {(a, b)}, ∀ a ∈ A, b ∈ B and A = {a₀, a₁, ..., aₘ} and B = {b₀, b₁, ..., bₙ} are the input sets of geometries set_A and set_B, respectively.

ExcludeWithin(self: pydrake.geometry.CollisionFilterDeclaration, geometry_set: pydrake.geometry.GeometrySet) → pydrake.geometry.CollisionFilterDeclaration: Excludes geometry pairs from proximity evaluation by updating the candidate pair set C ← C - P, where P = {(gᵢ, gⱼ)}, ∀ gᵢ, gⱼ ∈ G and G = {g₀, g₁, ..., gₘ} is the input geometry_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 definition D ⋂ A = ∅). Gₚ ⊂ G is the subset of geometries that have a proximity role (with an analogous interpretation of Dₚ and Aₚ). Many proximity queries operate on pairs of geometries (e.g., (gᵢ, gⱼ)). The set of proximity candidate pairs for such queries is initially defined as C = (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 that gᵢ, gⱼ ∈ Dₚ and frame(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ₚ, or Iₚ 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ₙ} (for n 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 by this 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) → pydrake.geometry.FilterId: 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: pydrake.geometry.FilterId) → 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: pydrake.geometry.FilterId) → 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 iff is_active(filter_id) returns True before calling this method (i.e., filter_id refers to an existent filter that has successfully been removed).

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: pydrake.geometry.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) → pydrake.geometry.RenderCameraCore: This camera’s core render properties.

show_window(self: pydrake.geometry.ColorRenderCamera) → bool: If true, requests that the RenderEngine display the rendered image. Whether or not the image is able to be displayed depends on the specific render engine and its configuration.

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.

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 if this contains values for ∇eₘ.

HasGradE_N(self: pydrake.geometry.ContactSurface) → bool

Returns: True if this 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() returns False.

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() returns False.

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() returns True.

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() returns True.

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.

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 if this contains values for ∇eₘ.

HasGradE_N(self: pydrake.geometry.ContactSurface_[AutoDiffXd]) → bool

Returns: True if this 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() returns False.

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() returns False.

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() returns True.

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() returns True.

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__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.geometry.Convex, filename: os.PathLike, 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. –

__init__(self: pydrake.geometry.Convex, mesh_data: pydrake.geometry.InMemoryMesh, scale: float = 1.0) -> None

Constructs a convex shape specification from the contents of a Drake-supported mesh file type.

The mesh is defined by the contents of a supported_file_types “mesh file format supported by Drake”. Those contents are passed in as mesh_data. For Convex, the only supporting files required are those necessary to define vertex positions (e.g., a glTF’s .bin file); material and texture files, if provided, are ignored and are therefore unnecessary.

Parameter mesh_data:: The in-memory file contents that define the vertex data for this shape.
Parameter scale:: An optional scale to coordinates.

__init__(self: pydrake.geometry.Convex, source: pydrake.geometry.MeshSource, scale: float = 1.0) -> None

Constructs a convex shape specification from the given source.

Parameter source:: The source for the mesh data.
Parameter scale:: An optional scale to coordinates.

extension(self: pydrake.geometry.Convex) → str

Returns the extension of the underlying input mesh – all lower case and including the dot. If this is constructed from a file path, the extension is extracted from the path. I.e., /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().

If this is constructed using in-memory file contents, it is the extension of the MemoryFile passed to the constructor.

filename(self: pydrake.geometry.Convex) → str

Returns the filename passed to the constructor.

Raises

RuntimeError if this Convex was constructed using in-memory –
file contents. –

See also

source().is_path(). */ (Deprecated.)

Deprecated:: Convex shapes can be defined from a file path or in memory data. Use Convex::source() to determine if a filename is available. This will be removed from Drake on or after 2025-04-01.

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

source(self: pydrake.geometry.Convex) → pydrake.geometry.MeshSource: Returns the source for this specification’s mesh data. When working with Convex, this API should only be used for introspection. The contract for Convex is that the convex hull is always used in place of whatever underlying mesh declaration is provided. For all functional geometric usage, exclusively use the convex hull returned by GetConvexHull().

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 and length.

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 margin

(Advanced) Specifies a thin layer of thickness “margin” (in meters) around each geometry. Two bodies with margins δ₁ and δ₂ are considered for contact resolution whenever their distance is within δ₁ + δ₂. That is, (speculative) contact constraints are added for objects at a distance smaller than δ₁+δ₂.

Refer to hydro_margin for further details, including theory, examples, recommended margin values and limitations.

There will only be contact if the two zero level sets intersect. Unless the zero level sets of both geometries overlap, there is no contact and no contact force. However, (speculative) contact constraints will be added allowing our discrete contact solvers to predict if a contact “will” occur at the next time step. This leads to additional time coherence and stability. Analytical studies of stability show that a value of 0.1 mm to 1.0 mm is more than enough for most robotics applications. This is not an “action-at-a-distance” trick, there is no contact when the thin margin layers of two objects overlap. The margin is simply a “cheap” mechanism to avoid significantly more complex and costly strategies such as Continuous Collision Detection.

Note

Inflating the geometries does not appreciably change the domain of contact. In the original mesh, the contact pressure is zero on the mesh’s boundary surface. When inflating the meshes, we redefine the pressure field so that its zero level set field is a good approximation to the surface of the original geometry. When visualizing hydroelastic proximity geometry, the rendered geometry will include the inflation.

Note

Currently margin only applies to compliant hydroelastic contact and it does not affect point contact.

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: pydrake.geometry.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) → pydrake.geometry.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 | Property

Description | | :——–: | :——: | :———–: | :————-: | :——————- | | 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 a double- 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. –

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 | Property

Description | | :——–: | :——: | :———–: | :————-: | :——————- | | 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 a double- 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. –

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 to True 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 by poses is in an unspecified state. The implementation of Calc must always ensure that poses contains the correct value upon return, no matter what value it started with. The easy ways to do this are to call either poses->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 given id.

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 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 by poses is in an unspecified state. The implementation of Calc must always ensure that poses contains the correct value upon return, no matter what value it started with. The easy ways to do this are to call either poses->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 given id.

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. –

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 by poses is in an unspecified state. The implementation of Calc must always ensure that poses contains the correct value upon return, no matter what value it started with. The easy ways to do this are to call either poses->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 given id.

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. –

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.

frame_group(self: pydrake.geometry.GeometryFrame) → int

id(self: pydrake.geometry.GeometryFrame) → pydrake.geometry.FrameId: 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: pydrake.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. –

id(self: pydrake.geometry.GeometryInstance) → pydrake.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) → pydrake.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) → pydrake.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) → pydrake.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) → pydrake.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) → pydrake.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) → pydrake.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: pydrake.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: pydrake.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: pydrake.geometry.ProximityProperties) → None: Sets the proximity properties for the given instance.

shape(self: pydrake.geometry.GeometryInstance) → pydrake.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 property some_property is in some_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 given value. 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).

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.

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 given default_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 desired ValueType 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` –

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.

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 given value. If the property doesn’t already exist, it is equivalent to calling AddProperty. If the property does exist, its value (which must have the same type as value) 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).

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 the FrameId 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 ids F = {f₀, f₁, ..., fₙ} and geometry ids G = {g₀, g₁, ..., gₘ}, Gₛ = G ⋃ geometry(f₀) ⋃ … ⋃ geometry(fₙ) (where geometry(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: pydrake.geometry.GeometryId) -> None

See main constructor

__init__(self: pydrake.geometry.GeometrySet, frame_id: pydrake.geometry.FrameId) -> None

See main constructor

__init__(self: pydrake.geometry.GeometrySet, geometry_ids: list[pydrake.geometry.GeometryId]) -> None

See main constructor

__init__(self: pydrake.geometry.GeometrySet, frame_ids: list[pydrake.geometry.FrameId]) -> None

See main constructor

__init__(self: pydrake.geometry.GeometrySet, geometry_ids: list[pydrake.geometry.GeometryId], frame_ids: list[pydrake.geometry.FrameId]) -> None

See main constructor

Add(*args, **kwargs)

Overloaded function.

Add(self: pydrake.geometry.GeometrySet, geometry_id: pydrake.geometry.GeometryId) -> None
Add(self: pydrake.geometry.GeometrySet, frame_id: pydrake.geometry.FrameId) -> None
Add(self: pydrake.geometry.GeometrySet, geometry_ids: list[pydrake.geometry.GeometryId]) -> None

See main constructor

Add(self: pydrake.geometry.GeometrySet, frame_ids: list[pydrake.geometry.FrameId]) -> None

See main constructor

Add(self: pydrake.geometry.GeometrySet, geometry_ids: list[pydrake.geometry.GeometryId], frame_ids: list[pydrake.geometry.FrameId]) -> 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: pydrake.geometry.Role) → bool: Returns true if this GeometryVersion has the same role version as the other 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‖₂ < ε) –

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.GeometryProperties) -> None

Creates a copy of the properties

class pydrake.geometry.InMemoryMesh

Representation of a mesh file stored in memory. At a minimum it includes the contents of a mesh file. If that mesh file makes reference to additional files (e.g., a .obj file can reference a .mtl which in turn references a .png file), then those files can be included in this InMemoryMesh’s supporting files. Each supporting file is represented by a key-value pair. The key is the file-referencing string as it appears in the referencing file and the value is a FileSource. All supporting files can be located on disk; only the main mesh file is strictly required to be in memory. Failure to provide the supporting files may or may not lead to errors; it depends on the context in which the mesh data is used.

__init__(self: pydrake.geometry.InMemoryMesh, **kwargs) → None

property mesh_file: The main mesh file’s contents (e.g., a .obj or .gltf file, but not a .mtl or .bin).

property supporting_files: The optional collection of supporting files.

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.

Note

On Ubuntu, render::ColorRenderCamera::show_window only shows a window when RenderEngineVtkParams::backend is set to “GLX”; the default backend value of “EGL” cannot show a window.

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 | Property

Description | | :——–: | :———–: | :——: | :————-: | :——————- | | 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 | Property

Description | | :——–: | :———–: | :———–: | :————-: | :——————- | | 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__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.geometry.Mesh, filename: os.PathLike, 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. –

__init__(self: pydrake.geometry.Mesh, mesh_data: pydrake.geometry.InMemoryMesh, scale: float = 1.0) -> None

Constructs a mesh shape specification from the contents of a Drake-supported mesh file type.

The mesh is defined by the contents of a supported_file_types “mesh file format supported by Drake”. Those contents are passed in as mesh_data. The mesh data should include the main mesh file’s contents as well as any supporting file contents as needed. See InMemoryMesh.

Parameter mesh_data:: The in-memory file contents that define the mesh data for this shape.
Parameter scale:: An optional scale to coordinates.

__init__(self: pydrake.geometry.Mesh, source: pydrake.geometry.MeshSource, scale: float = 1.0) -> None

Constructs a mesh shape specification from the given source.

Parameter source:: The source for the mesh data.
Parameter scale:: An optional scale to coordinates.

extension(self: pydrake.geometry.Mesh) → str

Returns the extension of the mesh type – all lower case and including the dot. If this is constructed from a file path, the extension is extracted from the path. I.e., /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().

If this is constructed using in-memory file contents, it is the extension of the MemoryFile passed to the constructor.

filename(self: pydrake.geometry.Mesh) → str

Returns the filename passed to the constructor.

Raises

RuntimeError if this Mesh was constructed using in-memory file –
contents. –

See also

source().is_path(). */ (Deprecated.)

Deprecated:: Meshes can be defined from a file path or in memory data. Use Mesh::source() to determine if a filename is available. This will be removed from Drake on or after 2025-04-01.

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

source(self: pydrake.geometry.Mesh) → pydrake.geometry.MeshSource: Returns the source for this specification’s mesh data.

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 in http://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 optional keycode 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 also click 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 optional decrement_keycode or increment_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 by step (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, strict: bool = True) → bool

Removes the button name from the GUI.

Returns

true iff the button was removed.

Raises

RuntimeError if strict is true and 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, strict: bool = True) → bool

Removes the slider name from the GUI.

Returns

true iff the slider was removed.

Raises

RuntimeError if strict is true and 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) → pydrake.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 to this. 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) → pydrake.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 was last broadcast by this instance (typically, the value displayed in the meshcat visualizer stats chart). See SetRealtimeRate().

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 slider name.

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:

http://localhost:7000

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.

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: pydrake.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: pydrake.geometry.Meshcat.PerspectiveCamera, path: str = ‘/Cameras/default/rotated’) -> None

Sets the Meshcat object on path to a perspective camera. We provide a default value of path corresponding to the default camera object in Meshcat.

SetCamera(self: pydrake.geometry.Meshcat, camera: pydrake.geometry.Meshcat.OrthographicCamera, path: str = ‘/Cameras/default/rotated’) -> None

Sets the Meshcat object on path to an orthographic camera. We provide a default value of path 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 toward target_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).

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).

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 the vertices.

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.

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() –

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 that path`="/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 be point_cloud. Note that path`="/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

Immediately broadcasts the given realtime rate to all connected clients.

Parameter rate:: the realtime rate value to broadcast, will be converted to a percentage (multiplied by 100)

SetSimulationTime(self: pydrake.geometry.Meshcat, sim_time: float) → None

Updates Meshcat’s knowledge of simulation time. Changes to simulation time may trigger a realtime rate message to the meshcat visualizer client based on the configured value in MeshcatParams::realtime_rate_period value.

Invoking this method may dispatch a message to clients. The following rules apply to invocations and messages:

The first invocation is necessary to initialize the calculation; it

defines the the starting point from which all calculations are performed (for both wall clock time as well as simulation time). As no interval can be measured from a single invocation, no rate can be computed. Therefore, the first invocation will never broadcast the message. - Wall clock time must advance at least MeshcatParams::realtime_rate_period seconds for a message to be sent. - Meshcat promises to broadcast one message per elapsed period – starting from initialization – regardless of the frequency at which SetSimulationTime() actually gets invoked. If the elapsed time between invocations exceeds MeshcatParams::realtime_rate_period, multiple messages will be broadcast; one for each complete period. - This implies that each column of pixels in the realtime rate chart in the client visualizer represents a fixed amount of wall clock time.

When the realtime rate is broadcast, that value will be reported by GetRealtimeRate().

The realtime rate calculation can be “reset” by passing a simulation time value that is strictly less than the value of the previous invocation. This has the effect of re-initializing the calculation with the passed time and the wall clock time of the invocation. So, if the simulation’s context gets reset to time = 0, calls to this method passing the context time will implicitly reset realtime rate calculations accordingly. Resetting the calculator will reset the value reported by GetRealtimeRate() to zero.

This function is safe to be called redundantly with the same simulation time. Redundant calls are a no-op.

Parameter sim_time:: The absolute sim time being visualized.

See also

drake::systems::Simulator::set_target_realtime_rate()

SetSliderValue(self: pydrake.geometry.Meshcat, name: str, value: float) → None

Sets the current value of the slider name. value will be truncated to the slider range and rounded to the nearest increment specified by the slider step. 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.

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.

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).

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.

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) → pydrake.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: pydrake.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 specified frame 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 specified frame 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 specified frame 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 given path 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. –

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 and b are the lengths of the principal semi-axes of the horizontal section at z=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 realtime_rate_period

The minimum period of wall clock time (in seconds) between updates to the broadcast realtime rate. If the period is too short, the reported realtime rate can become visually noisy. Too long, and acute changes in performance may be masked. It must be strictly positive.

Meshcat promises to broadcast messages to clients at this fixed period. See Meshcat::SetSimulationTime() for details.

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’s host field, or else with “localhost” in case the host 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 port X_ParentCloud sets the MeshcatTransform at the path representing the cloud. If it is not connected, then we set X_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.

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 port X_ParentCloud sets the MeshcatTransform at the path representing the cloud. If it is not connected, then we set X_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.

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. –

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.

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. –

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.

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 our prefix. If that property is absent then the geometry will be shown only if include_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 Meshcat prefix 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 to True 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.MeshSource

Provides a general abstraction to the definition of a mesh. A mesh definition can come from disk or memory. APIs that support both can take as specification an instance of MeshSource to communicate that ability.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pydrake.geometry.MeshSource, path: os.PathLike) -> None

Constructs from a file path. Note: the path will not be validated in any way (existence, availability, naming an actual mesh file, etc.). Validation occurs where the MeshSource’s path is used.

__init__(self: pydrake.geometry.MeshSource, mesh: pydrake.geometry.InMemoryMesh) -> None

Constructs from an in-memory mesh.

__init__(self: pydrake.geometry.MeshSource, other: pydrake.geometry.MeshSource) -> None

description(self: pydrake.geometry.MeshSource) → str: Provides a source-agnostic description of the mesh. If is_path() is true, it is the path. If is_in_memory() is true, it is the filename_hint for the in-memory mesh file. If the in-memory mesh file has an empty filename hint, the description will explicitly communicate that; the empty string will never be returned.

extension(self: pydrake.geometry.MeshSource) → str

Returns the extension of the mesh type – all lower case and including the dot. If is_path() is True, the extension is extracted from the path. I.e., /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().

If is_in_memory() is True, it is the extension reported by the MemoryFile.

in_memory(self: pydrake.geometry.MeshSource) → pydrake.geometry.InMemoryMesh

Returns the source’s in-memory mesh data.

Precondition:: is_in_memory() returns True.

is_in_memory(self: pydrake.geometry.MeshSource) → bool: Reports True if this source contains an in-memory mesh definition.

is_path(self: pydrake.geometry.MeshSource) → bool: Reports True if this source is a filesystem path.

path(self: pydrake.geometry.MeshSource) → os.PathLike

Returns the source’s file path.

Precondition:: is_path() returns True.

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 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.

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.

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.GeometryProperties) -> 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 in face_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 into vertices.

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.

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 in face_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 into vertices.

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.

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()).

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 type C. 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. –

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()).

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 type C. 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. –

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.GeometryProperties) -> 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[pydrake.geometry.ContactSurface]

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 and id_B in a fixed, repeatable manner, where id_A and id_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[pydrake.geometry.ContactSurface], list[pydrake.geometry.PenetrationAsPointPair]]

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 nor point_pairs is nullptr.

Raises

RuntimeError for the reasons described in ComputeContactSurfaces() –
and ComputePointPairPenetration() –

Note

The surfaces and point_pairs are output pointers in C++, but are return values in the Python bindings.

ComputePointPairPenetration(self: pydrake.geometry.QueryObject) → list[pydrake.geometry.PenetrationAsPointPair]

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 and id_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.

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.

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”.

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 for T = 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) → pydrake.geometry.SignedDistancePair

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[pydrake.geometry.SignedDistancePair]

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 exploit max_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.

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.

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”.

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 for T = 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.

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[pydrake.geometry.SignedDistanceToPoint]

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.

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.

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.

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.

template pydrake.geometry.QueryObject_: Instantiations: QueryObject_[float], QueryObject_[AutoDiffXd], QueryObject_[Expression]

class pydrake.geometry.QueryObject_[AutoDiffXd]