ELink properties

add doco and examples
reorder
add isprismatic, isrevolute

Author: petercorke

roboticstoolbox/robot/ELink.py

@@ -123,9 +123,9 @@ def _init_Ts(self):
 
     def __repr__(self):
         name = self.__class__.__name__
-        s = "ets=" + str(self.ets())
+        s = f"{self.name}, ets={self.ets()}"
         if self.parent is not None:
-            s += ", parent=" + str(self.parent.name)
+            s += f", parent={self.parent.name}"
         args = [s] + super()._params()
         return name + "(" + ", ".join(args) + ")"
 
@@ -145,32 +145,113 @@ def __str__(self):
 
     @property
     def v(self):
+        """
+        Variable part of link ETS
+
+        :return: joint variable transform
+        :rtype: ETS instance
+
+        The ETS for each ELink comprises a constant part (possible the identity)
+        followed by an optional joint variable transform.  This property returns
+        the latter.
+
+        .. runblock:: pycon
+
+            >>> from roboticstoolbox import ELink, ETS
+            >>> link = ELink( ETS.tz(0.333) * ETS.rx(90, 'deg') * ETS.rz() )
+            >>> print(link.v)
+        """
         return self._v
 
     @property
     def Ts(self):
-        return self._Ts
+        """
+        Constant part of link ETS
 
-    @property
-    def collision(self):
-        return self._collision
+        :return: constant part of link transform
+        :rtype: SE3 instance
+
+        The ETS for each ELink comprises a constant part (possible the identity)
+        followed by an optional joint variable transform.  This property returns
+        the constant part.  If no constant part is given, this returns an
+        identity matrix.
+
+        .. runblock:: pycon
+
+            >>> from roboticstoolbox import ELink, ETS
+            >>> link = ELink( ETS.tz(0.333) * ETS.rx(90, 'deg') * ETS.rz() )
+            >>> link.Ts
+            >>> link = ELink( ETS.rz() )
+            >>> link.Ts
+        """
+        return self._Ts
 
-    @property
-    def geometry(self):
-        return self._geometry
 
     @property
     def isjoint(self):
+        """
+        Test if link has joint
+
+        :return: test if link has a joint
+        :rtype: bool
+
+        The ETS for each ELink comprises a constant part (possible the identity)
+        followed by an optional joint variable transform.  This property returns the
+        whether the
+
+        .. runblock:: pycon
+
+            >>> from roboticstoolbox import models
+            >>> robot = models.URDF.Panda()
+            >>> robot[1].isjoint  # link with joint
+            >>> robot[8].isjoint  # static link
+        """
         return self._v is not None
 
     @property
     def jindex(self):
+        """
+        Get/set joint index
+
+        - ``link.jindex`` is the joint index
+            :return: joint index
+            :rtype: int
+        - ``link.jindex = ...`` checks and sets the joint index
+
+        For a serial-link manipulator the joints are numbered starting at zero
+        and increasing sequentially toward the end-effector.  For branched
+        mechanisms this is not so straightforward.
+
+        The link's ``jindex`` property specifies the index of its joint
+        variable within a vector of joint coordinates.
+
+        .. note:: ``jindex`` values must be a sequence of integers starting
+            at zero.
+        """
         return self._jindex
 
     @jindex.setter
     def jindex(self, j):
         self._jindex = j
 
+    def isrevolute(self):
+        """
+        Checks if the joint is of revolute type
+
+        :return: Ture if is revolute
+        :rtype: bool
+        """
+        return self.v.isrevolute
+
+    def isprismatic(self):
+        """
+        Checks if the joint is of prismatic type
+
+        :return: Ture if is prismatic
+        :rtype: bool
+        """
+        return self.v.isprismatic
+
     # @property
     # def ets(self):
     #     return self._ets
@@ -185,6 +266,21 @@ def jindex(self, j):
 
     @property
     def parent(self):
+        """
+        Parent link
+
+        :return: Link's parent
+        :rtype: ELink instance
+
+        This is a reference to 
+
+        .. runblock:: pycon
+
+            >>> from roboticstoolbox import models
+            >>> robot = models.URDF.Panda()
+            >>> robot[0].parent  # base link has no parent
+            >>> robot[1].parent  # second link's parent
+        """
         return self._parent
 
     @property
@@ -195,39 +291,14 @@ def child(self):
     def M(self):
         return self._M
 
-    @collision.setter
-    def collision(self, coll):
-        new_coll = []
-
-        if isinstance(coll, list):
-            for gi in coll:
-                if isinstance(gi, rp.Shape):
-                    new_coll.append(gi)
-                else:
-                    raise TypeError('Collision must be of Shape class')
-        elif isinstance(coll, rp.Shape):
-            new_coll.append(coll)
-        else:
-            raise TypeError('Geometry must be of Shape class or list of Shape')
-
-        self._collision = new_coll
-
-    @geometry.setter
-    def geometry(self, geom):
-        new_geom = []
+    @property
+    def collision(self):
+        return self._collision
 
-        if isinstance(geom, list):
-            for gi in geom:
-                if isinstance(gi, rp.Shape):
-                    new_geom.append(gi)
-                else:
-                    raise TypeError('Geometry must be of Shape class')
-        elif isinstance(geom, rp.Shape):
-            new_geom.append(geom)
-        else:
-            raise TypeError('Geometry must be of Shape class or list of Shape')
+    @property
+    def geometry(self):
+        return self._geometry
 
-        self._geometry = new_geom
 
     # @r.setter
     # def r(self, T):
@@ -282,6 +353,40 @@ def ets(self):
         else:
             return self._ets * self.v
 
+    @collision.setter
+    def collision(self, coll):
+        new_coll = []
+
+        if isinstance(coll, list):
+            for gi in coll:
+                if isinstance(gi, rp.Shape):
+                    new_coll.append(gi)
+                else:
+                    raise TypeError('Collision must be of Shape class')
+        elif isinstance(coll, rp.Shape):
+            new_coll.append(coll)
+        else:
+            raise TypeError('Geometry must be of Shape class or list of Shape')
+
+        self._collision = new_coll
+
+    @geometry.setter
+    def geometry(self, geom):
+        new_geom = []
+
+        if isinstance(geom, list):
+            for gi in geom:
+                if isinstance(gi, rp.Shape):
+                    new_geom.append(gi)
+                else:
+                    raise TypeError('Geometry must be of Shape class')
+        elif isinstance(geom, rp.Shape):
+            new_geom.append(geom)
+        else:
+            raise TypeError('Geometry must be of Shape class or list of Shape')
+
+        self._geometry = new_geom
+
     def closest_point(self, shape, inf_dist=1.0):
         '''
         closest_point(shape, inf_dist) returns the minimum euclidean