Add mesh_detail attribute to select gripper mesh resolution

The gripper's Geometries() mesh doubles as the motion-planning collision
geometry, so it was decimated to keep planning responsive. Add a
mesh_detail attribute ("high" / "low", default "low") to both gripper
models so a full-resolution gripper and a decimated one can run on the
same machine for a planning/visual side-by-side.

- meshes/gripper/ now holds high/ and low/ variants of each PLY;
  gen_gripper_meshes.py emits both detail levels.
- meshes.go embeds meshes/gripper as an embed.FS; buildGripperMeshes
  reads the PLY for the requested detail level.
- mesh_detail added to SO101GripperConfig and SO101SimulatedGripperConfig
  (validated; defaults to "low" so existing configs are unchanged).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: btshrewsbury-viam

Makefile

@@ -9,7 +9,7 @@ ifeq ($(VIAM_TARGET_OS), windows)
 	MODULE_BINARY = bin/arm.exe
 endif
 
-$(MODULE_BINARY): Makefile go.mod *.go cmd/module/*.go so101.json meshes/so101/*.glb meshes/gripper/*.ply
+$(MODULE_BINARY): Makefile go.mod *.go cmd/module/*.go so101.json meshes/so101/*.glb meshes/gripper/*/*.ply
 	GOOS=$(VIAM_BUILD_OS) GOARCH=$(VIAM_BUILD_ARCH) $(GO_BUILD_ENV) go build $(GO_BUILD_FLAGS) -o $(MODULE_BINARY) cmd/module/main.go
 
 lint:

README.md

@@ -293,6 +293,7 @@ Follow the [arm setup steps](#first-time-arm-setup) to learn how to set up the a
 | `servo_id`         | int      | Optional  | The servo ID for the gripper. Default is `6`.                 |
 | `timeout`          | duration | Optional  | Communication timeout. Default is system default.             |
 | `gripper_type`     | string   | Optional  | Which gripper meshes `Geometries()` serves for the 3D viewer: `follower` (moving jaw, default) or `leader` (thumb-loop handle + trigger). The moving part articulates with the live gripper opening. |
+| `mesh_detail`      | string   | Optional  | Gripper mesh resolution: `low` (decimated, the default) or `high` (full resolution). `Geometries()` is also the motion-planning collision geometry, so `low` keeps planning fast; `high` is mainly for visual comparison. |
 
 ### Communication
 
@@ -382,6 +383,7 @@ All attributes are optional, so the simulated gripper works with an empty config
 | Name           | Type   | Inclusion | Description                                                                                                |
 | -------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------- |
 | `gripper_type` | string | Optional  | Which gripper meshes to serve: `follower` (moving jaw, the default) or `leader` (thumb-loop handle + trigger). |
+| `mesh_detail`  | string | Optional  | Gripper mesh resolution: `low` (decimated, the default) or `high` (full resolution). The mesh is also the motion-planning collision geometry, so `low` keeps planning fast; set `high` on a second gripper for a visual side-by-side. |
 
 ### DoCommand
 

gripper.go

@@ -28,6 +28,14 @@ const (
 	followerGripper = "follower"
 )
 
+// Mesh detail levels selectable via the mesh_detail config attribute. The gripper
+// mesh is also the motion-planning collision geometry, so "low" (heavily decimated)
+// is the responsive default; "high" is full resolution, for visual comparison.
+const (
+	highDetail = "high"
+	lowDetail  = "low"
+)
+
 type SO101GripperConfig struct {
 	Port     string `json:"port,omitempty"`
 	Baudrate int    `json:"baudrate,omitempty"`
@@ -43,6 +51,11 @@ type SO101GripperConfig struct {
 	// GripperType selects which meshes Geometries() serves: "follower" (moving
 	// jaw, the default) or "leader" (thumb-loop handle + trigger).
 	GripperType string `json:"gripper_type,omitempty"`
+
+	// MeshDetail selects the gripper mesh resolution Geometries() serves:
+	// "low" (decimated, the default -- keeps motion planning fast) or "high"
+	// (full resolution).
+	MeshDetail string `json:"mesh_detail,omitempty"`
 }
 
 // Validate ensures all parts of the config are valid
@@ -68,6 +81,11 @@ func (cfg *SO101GripperConfig) Validate(path string) ([]string, []string, error)
 			leaderGripper, followerGripper, cfg.GripperType)
 	}
 
+	if cfg.MeshDetail != "" && cfg.MeshDetail != highDetail && cfg.MeshDetail != lowDetail {
+		return nil, nil, fmt.Errorf("mesh_detail must be %q or %q, got %q",
+			highDetail, lowDetail, cfg.MeshDetail)
+	}
+
 	return nil, nil, nil
 }
 
@@ -78,6 +96,7 @@ type so101Gripper struct {
 	logger      logging.Logger
 	controller  *SafeSoArmController
 	gripperType string
+	meshDetail  string
 	servoID     int
 
 	mu       sync.Mutex
@@ -144,11 +163,17 @@ func newSO101Gripper(ctx context.Context, deps resource.Dependencies, conf resou
 		gripperType = followerGripper
 	}
 
+	meshDetail := cfg.MeshDetail
+	if meshDetail == "" {
+		meshDetail = lowDetail
+	}
+
 	g := &so101Gripper{
 		name:           conf.ResourceName(),
 		logger:         logger,
 		controller:     controller,
 		gripperType:    gripperType,
+		meshDetail:     meshDetail,
 		servoID:        cfg.ServoID,
 		speed:          30,
 		acceleration:   50,
@@ -263,22 +288,26 @@ const (
 
 // buildGripperMeshes returns the gripper's static body mesh plus the moving part
 // (jaw for the follower, trigger for the leader) posed at jawAngle radians about
-// the gripper joint. It is split out from Geometries so it can be tested without
-// a hardware controller.
-func buildGripperMeshes(gripperType string, jawAngle float64) ([]spatialmath.Geometry, error) {
-	// Static meshes (all posed at the gripper body pose) plus the moving-part mesh.
-	// The follower's body is one piece; the leader's is the wrist-roll part (which
-	// connects to the arm) plus the handle attached to it.
-	staticPLYs := [][]byte{so101FollowerBodyPLY}
-	movingPLY := so101FollowerJawPLY
+// the gripper joint, at the requested mesh detail level ("high" or "low"). It is
+// split out from Geometries so it can be tested without a hardware controller.
+func buildGripperMeshes(gripperType, meshDetail string, jawAngle float64) ([]spatialmath.Geometry, error) {
+	// Mesh names for this gripper variant: the static body part(s) plus the moving
+	// part. The follower's body is one piece; the leader's is the wrist-roll part
+	// (which connects to the arm) plus the handle attached to it.
+	staticNames := []string{"follower_body"}
+	movingName := "follower_jaw"
 	if gripperType == leaderGripper {
-		staticPLYs = [][]byte{so101LeaderWristRollPLY, so101LeaderBodyPLY}
-		movingPLY = so101LeaderTriggerPLY
+		staticNames = []string{"leader_wrist_roll", "leader_body"}
+		movingName = "leader_trigger"
 	}
 
 	bodyPose := spatialmath.Compose(toolFromGripperLink, gripperBodyPose)
-	geoms := make([]spatialmath.Geometry, 0, len(staticPLYs)+1)
-	for i, ply := range staticPLYs {
+	geoms := make([]spatialmath.Geometry, 0, len(staticNames)+1)
+	for i, name := range staticNames {
+		ply, err := gripperMeshPLY(meshDetail, name)
+		if err != nil {
+			return nil, err
+		}
 		m, err := spatialmath.NewMeshFromProto(bodyPose,
 			&commonpb.Mesh{ContentType: "ply", Mesh: ply}, fmt.Sprintf("gripper_body_%d", i))
 		if err != nil {
@@ -294,6 +323,10 @@ func buildGripperMeshes(gripperType string, jawAngle float64) ([]spatialmath.Geo
 			spatialmath.NewPose(r3.Vector{}, &spatialmath.EulerAngles{Yaw: jawAngle})),
 		gripperMovingVisualPose,
 	))
+	movingPLY, err := gripperMeshPLY(meshDetail, movingName)
+	if err != nil {
+		return nil, err
+	}
 	moving, err := spatialmath.NewMeshFromProto(movingPose,
 		&commonpb.Mesh{ContentType: "ply", Mesh: movingPLY}, "gripper_moving")
 	if err != nil {
@@ -317,7 +350,7 @@ func (g *so101Gripper) jawAngle(ctx context.Context) float64 {
 // Geometries serves the gripper as meshes: a static body and a moving part posed by
 // the live gripper opening, so the jaw/trigger articulates in the 3D viewer.
 func (g *so101Gripper) Geometries(ctx context.Context, extra map[string]interface{}) ([]spatialmath.Geometry, error) {
-	return buildGripperMeshes(g.gripperType, g.jawAngle(ctx))
+	return buildGripperMeshes(g.gripperType, g.meshDetail, g.jawAngle(ctx))
 }
 
 func (g *so101Gripper) DoCommand(ctx context.Context, cmd map[string]interface{}) (map[string]interface{}, error) {

gripper_test.go

@@ -9,35 +9,48 @@ import (
 )
 
 func TestSO101GripperConfigValidate(t *testing.T) {
-	// An unset gripper_type is accepted (defaults to follower).
+	// An unset gripper_type / mesh_detail is accepted (defaults applied).
 	_, _, err := (&SO101GripperConfig{Port: "/dev/ttyUSB0"}).Validate("")
 	require.NoError(t, err)
 
 	for _, gt := range []string{leaderGripper, followerGripper} {
 		_, _, err := (&SO101GripperConfig{Port: "/dev/ttyUSB0", GripperType: gt}).Validate("")
 		require.NoError(t, err, "gripper_type %q should be valid", gt)
 	}
+	for _, md := range []string{highDetail, lowDetail} {
+		_, _, err := (&SO101GripperConfig{Port: "/dev/ttyUSB0", MeshDetail: md}).Validate("")
+		require.NoError(t, err, "mesh_detail %q should be valid", md)
+	}
 
 	_, _, err = (&SO101GripperConfig{Port: "/dev/ttyUSB0", GripperType: "bogus"}).Validate("")
 	require.Error(t, err)
+	_, _, err = (&SO101GripperConfig{Port: "/dev/ttyUSB0", MeshDetail: "bogus"}).Validate("")
+	require.Error(t, err)
 }
 
 func TestBuildGripperMeshes(t *testing.T) {
-	// Exercises the pose math and confirms each embedded PLY parses into a mesh.
+	// Exercises the pose math, confirms each embedded PLY parses into a mesh at
+	// both detail levels, and that "high" really is denser than "low".
 	for _, tc := range []struct {
 		gripperType string
 		meshes      int
 	}{
 		{followerGripper, 2}, // body + jaw
 		{leaderGripper, 3},   // wrist-roll + handle + trigger
 	} {
-		geoms, err := buildGripperMeshes(tc.gripperType, 0.5)
-		require.NoError(t, err, "gripper_type %q", tc.gripperType)
-		require.Len(t, geoms, tc.meshes)
-		for _, geom := range geoms {
-			mesh, ok := geom.(*spatialmath.Mesh)
-			require.True(t, ok, "gripper geometry should be a mesh")
-			assert.NotEmpty(t, mesh.Triangles(), "mesh should have triangles")
+		triCount := map[string]int{}
+		for _, detail := range []string{highDetail, lowDetail} {
+			geoms, err := buildGripperMeshes(tc.gripperType, detail, 0.5)
+			require.NoError(t, err, "gripper_type %q detail %q", tc.gripperType, detail)
+			require.Len(t, geoms, tc.meshes)
+			for _, geom := range geoms {
+				mesh, ok := geom.(*spatialmath.Mesh)
+				require.True(t, ok, "gripper geometry should be a mesh")
+				assert.NotEmpty(t, mesh.Triangles(), "mesh should have triangles")
+				triCount[detail] += len(mesh.Triangles())
+			}
 		}
+		assert.Greater(t, triCount[highDetail], triCount[lowDetail],
+			"high detail should be denser than low for %q", tc.gripperType)
 	}
 }

meshes.go

@@ -1,7 +1,7 @@
 package so_arm
 
 import (
-	_ "embed"
+	"embed"
 
 	commonpb "go.viam.com/api/common/v1"
 )
@@ -34,22 +34,18 @@ var so101EEFrameGLB []byte
 
 // SO-101 gripper meshes (ASCII PLY, see meshes/gen_gripper_meshes.py). The gripper
 // component serves these via Geometries() as spatialmath.Mesh geometries: a static
-// body and a moving part (jaw for the follower, trigger for the leader).
-
-//go:embed meshes/gripper/follower_body.ply
-var so101FollowerBodyPLY []byte
-
-//go:embed meshes/gripper/follower_jaw.ply
-var so101FollowerJawPLY []byte
-
-//go:embed meshes/gripper/leader_wrist_roll.ply
-var so101LeaderWristRollPLY []byte
-
-//go:embed meshes/gripper/leader_body.ply
-var so101LeaderBodyPLY []byte
+// body and a moving part (jaw for the follower, trigger for the leader). Each mesh
+// is embedded at two detail levels -- meshes/gripper/{high,low}/ -- chosen by the
+// gripper's mesh_detail attribute.
+//
+//go:embed meshes/gripper
+var gripperMeshFS embed.FS
 
-//go:embed meshes/gripper/leader_trigger.ply
-var so101LeaderTriggerPLY []byte
+// gripperMeshPLY returns the embedded PLY bytes for a gripper mesh ("follower_body",
+// "leader_trigger", ...) at the given detail level ("high" or "low").
+func gripperMeshPLY(detail, name string) ([]byte, error) {
+	return gripperMeshFS.ReadFile("meshes/gripper/" + detail + "/" + name + ".ply")
+}
 
 const gltfBinary = "model/gltf-binary"
 

meshes/gen_gripper_meshes.py

@@ -7,6 +7,11 @@
 written as ASCII PLY -- rdk's spatialmath.NewMeshFromProto accepts ASCII PLY only,
 and the gripper component serves these via Geometries() as spatialmath.Mesh.
 
+Each mesh is written at two detail levels -- meshes/gripper/high/ and
+meshes/gripper/low/ -- chosen at runtime by the gripper's mesh_detail attribute.
+The gripper mesh doubles as the motion-planning collision geometry, so "low" is
+the responsive default and "high" is for visual comparison.
+
 PLY vertices are kept in METERS (rdk's PLY reader scales x1000 to millimeters).
 
 Run from the repo root:  python3 meshes/gen_gripper_meshes.py
@@ -19,17 +24,20 @@
 
 BASE = "https://raw.githubusercontent.com/TheRobotStudio/SO-ARM100/main"
 
-# name -> (source URL, grid cell size in meters, source-unit-to-meters scale).
-# The follower simulation assets are authored in meters; the leader printable
-# STLs are in millimeters, so they need a 0.001 scale.
+# name -> (source URL, source-unit-to-meters scale). The follower simulation
+# assets are authored in meters; the leader printable STLs are in millimeters.
 MESHES = {
-    "follower_body": (f"{BASE}/Simulation/SO101/assets/wrist_roll_follower_so101_v1.stl", 0.01, 1.0),
-    "follower_jaw": (f"{BASE}/Simulation/SO101/assets/moving_jaw_so101_v1.stl", 0.01, 1.0),
-    "leader_wrist_roll": (f"{BASE}/STL/SO101/Individual/Wrist_Roll_SO101.stl", 0.01, 0.001),
-    "leader_body": (f"{BASE}/STL/SO101/Individual/Handle_SO101.stl", 0.01, 0.001),
-    "leader_trigger": (f"{BASE}/STL/SO101/Individual/Trigger_SO101.stl", 0.01, 0.001),
+    "follower_body": (f"{BASE}/Simulation/SO101/assets/wrist_roll_follower_so101_v1.stl", 1.0),
+    "follower_jaw": (f"{BASE}/Simulation/SO101/assets/moving_jaw_so101_v1.stl", 1.0),
+    "leader_wrist_roll": (f"{BASE}/STL/SO101/Individual/Wrist_Roll_SO101.stl", 0.001),
+    "leader_body": (f"{BASE}/STL/SO101/Individual/Handle_SO101.stl", 0.001),
+    "leader_trigger": (f"{BASE}/STL/SO101/Individual/Trigger_SO101.stl", 0.001),
 }
 
+# detail level -> weld grid cell size in meters. A coarser grid welds more
+# vertices together, yielding far fewer faces (and far cheaper collision checks).
+GRIDS = {"high": 0.0015, "low": 0.01}
+
 
 def load_binary_stl(data):
     """Return an (n, 3, 3) array of triangle vertices from binary STL bytes."""
@@ -75,20 +83,19 @@ def write_ascii_ply(path, verts, faces):
 
 
 def main():
-    out_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "gripper")
-    os.makedirs(out_dir, exist_ok=True)
-    for name, (url, grid, scale) in MESHES.items():
+    base_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "gripper")
+    for name, (url, scale) in MESHES.items():
         with urllib.request.urlopen(url) as resp:
             stl = resp.read()
         verts = load_binary_stl(stl) * scale
-        reps, faces = weld(verts, grid)
-        path = os.path.join(out_dir, f"{name}.ply")
-        write_ascii_ply(path, reps, faces)
-        bb = verts.reshape(-1, 3)
-        dims = bb.max(0) - bb.min(0)
-        print(f"{name:16s} {len(verts):6d} tris -> {len(faces):6d} faces, "
-              f"{len(reps):6d} verts, {os.path.getsize(path) / 1024:7.1f} KB  "
-              f"bbox(m) {dims[0]:.3f} x {dims[1]:.3f} x {dims[2]:.3f}")
+        for detail, grid in GRIDS.items():
+            out_dir = os.path.join(base_dir, detail)
+            os.makedirs(out_dir, exist_ok=True)
+            reps, faces = weld(verts, grid)
+            path = os.path.join(out_dir, f"{name}.ply")
+            write_ascii_ply(path, reps, faces)
+            print(f"{detail:4s} {name:18s} {len(faces):6d} faces, "
+                  f"{os.path.getsize(path) / 1024:7.1f} KB")
 
 
 if __name__ == "__main__":