fix: support scalar/2-elem dim shorthand in tranimate/Animate

tranimate() popped "dims" from kwargs but forwarded it to Animate() as
dim=, and every other function in this codebase (plotvol2, plotvol3)
uses the singular "dim" as the actual keyword name. Calling
tranimate(T, dim=1.5) -- correct per that convention -- left dim=1.5
sitting in **kwargs, colliding with the explicit dim=dim already being
passed to Animate() and raising "got multiple values for keyword
argument 'dim'". Now accepts dim, with dims kept as a back-compat
alias for the previous docstring examples.

Animate.__init__ also had its own hand-rolled dim-length check that
only accepted 2 or 6 elements, so even a correctly-named dim=1.5 would
have failed validation afterward. Replaced it with expand_dims(), the
same helper plotvol3 already uses, so the scalar-shorthand convention
(A -> [-A,A] on every axis) works consistently everywhere.

Author: petercorke

spatialmath/base/animate.py

@@ -60,10 +60,11 @@ def __init__(
 
         :param ax: the axes to plot into, defaults to current axes
         :type ax: Axes3D reference
-        :param dim: dimension of plot volume as [xmin, xmax, ymin, ymax,
-            zmin, zmax]. If dims is [min, max] those limits are applied
-            to the x-, y- and z-axes.
-        :type dim: array_like(6) or array_like(2)
+        :param dim: dimension of plot volume, using the same shorthand as
+            ``plotvol3``: a scalar ``A`` gives ``[-A,A]`` on every axis, a
+            2-vector ``[A,B]`` gives ``[A,B]`` on every axis, and a 6-vector
+            gives ``[xmin, xmax, ymin, ymax, zmin, zmax]`` explicitly.
+        :type dim: scalar, array_like(2) or array_like(6)
         :param projection: 3D projection: ortho [default] or persp
         :type projection: str
         :param labels: labels for the axes, defaults to X, Y and Z
@@ -105,13 +106,9 @@ def __init__(
             #     # ax.set_aspect('equal')
             ax = smb.plotvol3(ax=ax, dim=dim)
         if dim is not None:
-            dim = list(np.ndarray.flatten(np.array(dim)))
-            if len(dim) == 2:
-                dim = dim * 3
-            elif len(dim) != 6:
-                raise ValueError(
-                    f"dim must have 2 or 6 elements, got {dim}. See docstring for details."
-                )
+            # same shorthand as plotvol3: scalar A -> [-A,A]*3, [A,B] -> [A,B]*3,
+            # or a full [xmin,xmax,ymin,ymax,zmin,zmax]
+            dim = smb.expand_dims(dim, nd=3)
             ax.set_xlim(dim[0:2])
             ax.set_ylim(dim[2:4])
             ax.set_zlim(dim[4:])

spatialmath/base/transforms3d.py

@@ -3402,8 +3402,8 @@ def tranimate(T: Union[SO3Array, SE3Array], **kwargs) -> str:
 
         Examples:
 
-                >>> tranimate(transl(1,2,3)@trotx(1), frame='A', arrow=False, dims=[0, 5])
-                >>> tranimate(transl(1,2,3)@trotx(1), frame='A', arrow=False, dims=[0, 5], movie='spin.mp4')
+                >>> tranimate(transl(1,2,3)@trotx(1), frame='A', arrow=False, dim=[0, 5])
+                >>> tranimate(transl(1,2,3)@trotx(1), frame='A', arrow=False, dim=[0, 5], movie='spin.mp4')
 
         .. note:: For Jupyter this works with the ``notebook`` and ``TkAgg``
             backends.
@@ -3419,7 +3419,9 @@ def tranimate(T: Union[SO3Array, SE3Array], **kwargs) -> str:
 
         :seealso: `trplot`, `plotvol3`
         """
-        dim = kwargs.pop("dims", None)
+        # accept dim (matches Animate/plotvol2/plotvol3), keep dims as an
+        # alias for backward compatibility with the previous docstring/API
+        dim = kwargs.pop("dim", kwargs.pop("dims", None))
         ax = kwargs.pop("ax", None)
         anim = Animate(dim=dim, ax=ax, **kwargs)
         anim.trplot(T, **kwargs)