From a6dd5f086f1832b06a4d23366d31e1c38eec29b6 Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Mon, 10 Feb 2025 10:09:35 -0800 Subject: [PATCH] Document element name lookup in MjSpec. PiperOrigin-RevId: 725258206 Change-Id: I5c9a85d25787eb38e9e8c3854eda2581700e188e --- doc/python.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/doc/python.rst b/doc/python.rst index 925edfadc7..a77306b807 100644 --- a/doc/python.rst +++ b/doc/python.rst @@ -587,14 +587,19 @@ Convenience methods The Python bindings provide a number of convenience methods and attributes not directly available in the C API in order to make model editing easier: +Finding elements +^^^^^^^^^^^^^^^^ +The ``MjSpec`` object has methods like ``find_body(), find_joint(), find_site(), ...`` for every type of name-able +:ref:`mjtObj` type. These methods take a name string and return the element with that name or ``None`` if it does not +exist. + Element lists ^^^^^^^^^^^^^ Lists of all elements in a spec can be accessed using named properties, using the plural form. For example, -``spec.meshes`` returns a list of all meshes in the spec. - -The following properties are implemented: ``sites``, ``geoms``, ``joints``, ``lights``, ``cameras``, ``bodies``, -``frames``, ``materials``, ``meshes``, ``pairs``, ``equalities``, ``tendons``, ``actuators``, ``skins``, ``textures``, -``texts``, ``tuples``, ``flexes``, ``hfields``, ``keys``, ``numerics``, ``excludes``, ``sensors``, ``plugins``. +``spec.meshes`` returns a list of all meshes in the spec. The following properties are implemented: ``sites``, +``geoms``, ``joints``, ``lights``, ``cameras``, ``bodies``, ``frames``, ``materials``, ``meshes``, ``pairs``, +``equalities``, ``tendons``, ``actuators``, ``skins``, ``textures``, ``texts``, ``tuples``, ``flexes``, ``hfields``, +``keys``, ``numerics``, ``excludes``, ``sensors``, ``plugins``. Tree traversal ^^^^^^^^^^^^^^ @@ -611,8 +616,9 @@ Recursive search: ``body.find_all(mujoco.mjtObj.mjOBJ_SITE)`` or ``body.find_all('site')`` will return a list of all sites under the body. -Additionally, the parent body of a given element - including bodies and frames - can be accessed via the ``parent`` -property. For example, the parent of a site can be accessed via ``site.parent``. +Parent: + The parent body of a given element -- including bodies and frames -- can be accessed via the ``parent`` property. + For example, the parent of a site can be accessed via ``site.parent``. Relationship to ``PyMJCF`` --------------------------