From 784c7a419b489b699b31528dffc9d9c1fb1e3af3 Mon Sep 17 00:00:00 2001
From: Yuval Tassa <tassa@google.com>
Date: Tue, 5 Aug 2025 10:24:45 -0700
Subject: [PATCH] Improve builtin hemisphere docs

PiperOrigin-RevId: 791271829
Change-Id: I391215b5388f4e9e2a17198dbcdbd0c605fda4b4
---
 doc/XMLreference.rst        | 9 +++++----
 python/mujoco/specs.cc      | 6 +++---
 python/mujoco/specs_test.py | 2 +-
 src/user/user_api.cc        | 4 ++--
 src/user/user_mesh.cc       | 2 +-
 5 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst
index 6c988d0d..0c30586d 100644
--- a/doc/XMLreference.rst
+++ b/doc/XMLreference.rst
@@ -1347,11 +1347,12 @@ The full list of processing steps applied by the compiler to each mesh is as fol
       :align: right
       :target: https://github.com/google-deepmind/mujoco/blob/main/test/user/testdata/makemesh.xml
 
-   :at-val:`hemisphere` (subdivision)
-      Repeated subdivisions of a square-based pyramid. For :math:`s` subdivisions, this mesh
-      has :math:`V = 2 + 2(s+1)(s+2)` vertices and :math:`F = 4(s+1)(s+2)` faces.
+   :at-val:`hemisphere` (resolution)
+      Quad-projected hemisphere. For resolution :math:`r`, this mesh has :math:`4r` edges and
+      vertices on the equator and a total of :math:`V = 2 + 2(r+1)(r+2)` vertices and
+      :math:`F = 4(r+1)(r+2)` faces.
 
-      **subdivision**: integer in [0-10]: The number of subdivisions to apply to the pyramid.
+      **resolution**: integer in [0-10]: Equator discretization of one hemisphere quadrant.
 
    .. image:: images/XMLreference/c.png
       :width: 23%
diff --git a/python/mujoco/specs.cc b/python/mujoco/specs.cc
index 3094a28b..ce507ac4 100644
--- a/python/mujoco/specs.cc
+++ b/python/mujoco/specs.cc
@@ -1025,13 +1025,13 @@ PYBIND11_MODULE(_specs, m) {
       py::arg("subdivision"));
   mjsMesh.def(
       "make_hemisphere",
-      [](raw::MjsMesh* self, int subdivision) {
-        double params[1] = {static_cast<double>(subdivision)};
+      [](raw::MjsMesh* self, int resolution) {
+        double params[1] = {static_cast<double>(resolution)};
         if (mjs_makeMesh(self, mjMESH_BUILTIN_HEMISPHERE, params, 1)) {
           throw pybind11::value_error(mjs_getError(mjs_getSpec(self->element)));
         }
       },
-      py::arg("subdivision"));
+      py::arg("resolution"));
   mjsMesh.def(
       "make_cone",
       [](raw::MjsMesh* self, int nedge, double radius) {
diff --git a/python/mujoco/specs_test.py b/python/mujoco/specs_test.py
index 602778f2..5d34f6f1 100644
--- a/python/mujoco/specs_test.py
+++ b/python/mujoco/specs_test.py
@@ -497,7 +497,7 @@ class SpecsTest(absltest.TestCase):
     mesh.make_cone(nedge=6, radius=0)
 
     mesh = spec.add_mesh(name='hemisphere')
-    mesh.make_hemisphere(subdivision=4)
+    mesh.make_hemisphere(resolution=4)
 
     mesh = spec.add_mesh(name='sphere')
     mesh.make_sphere(subdivision=2)
diff --git a/src/user/user_api.cc b/src/user/user_api.cc
index 5b25d542..73db82d8 100644
--- a/src/user/user_api.cc
+++ b/src/user/user_api.cc
@@ -513,11 +513,11 @@ int mjs_makeMesh(mjsMesh* mesh, mjtMeshBuiltin builtin, double* params, int npar
       }
       int subdiv = static_cast<int>(params[0]);
       if (subdiv < 0) {
-        m->SetError(mjCError(0, "Hemisphere subdivision cannot be negative"));
+        m->SetError(mjCError(0, "Hemisphere resolution cannot be negative"));
         return -1;
       }
       if (subdiv > 10) {
-        m->SetError(mjCError(0, "Hemisphere subdivision cannot be greater than 10"));
+        m->SetError(mjCError(0, "Hemisphere resolution cannot be greater than 10"));
         return -1;
       }
       meshC->MakeHemisphere(subdiv, /*make_faces*/ true, /*make_cap*/ true);
diff --git a/src/user/user_mesh.cc b/src/user/user_mesh.cc
index 28141de7..fba730a6 100644
--- a/src/user/user_mesh.cc
+++ b/src/user/user_mesh.cc
@@ -2066,7 +2066,7 @@ void mjCMesh::CopyGraph() {
 
 
 
-// make a mesh of a hemisphere
+// make a mesh of a hemisphere (quad projected)
 void mjCMesh::MakeHemisphere(int res, bool make_faces, bool make_cap) {
   constexpr double kNorthPole[3] = {0, 0, 1};
   constexpr double kEquator[4][3] = {