proteusPy.turtle3D

  1"""
  2Implementation of a 3D 'Turtle' in Python.
  3
  4Part of the program proteusPy, https://github.com/suchanek/proteusPy, 
  5a Python packages for the manipulation and analysis of macromolecules. 
  6Based on the C implementation originally authored by Eric G. Suchanek PhD, 1990.
  7
  8"""
  9
 10# Last modification 3/9/24 -egs-
 11
 12__pdoc__ = {"__all__": True}
 13
 14import math
 15
 16import numpy
 17
 18numpy.set_printoptions(suppress=True)
 19
 20# from Bio.PDB.vectors import Vector, calc_angle, calc_dihedral
 21from proteusPy.vector3D import Vector3D as Vector
 22from proteusPy.vector3D import calc_angle, calc_dihedral
 23
 24_DOWN_ = -1
 25_UP_ = 1
 26_ORIENTATION_INIT = -1
 27
 28ORIENT_BACKBONE = 2
 29ORIENT_SIDECHAIN = 1
 30
 31
 32# Class Definition begins
 33class Turtle3D:
 34    """3D Turtle."""
 35
 36    def __init__(self, name="3D_Turtle"):
 37        # internal rep is arrays
 38        self._position = numpy.array((0.0, 0.0, 0.0), "d")
 39        self._heading = numpy.array((1.0, 0.0, 0.0), "d")
 40        self._left = numpy.array((0.0, 1.0, 0.0), "d")
 41        self._up = numpy.array((0.0, 0.0, 1.0), "d")
 42
 43        # expose these as Vectors
 44        self.pos = Vector(0.0, 0.0, 0.0)
 45        self.h = Vector(1.0, 0.0, 0.0)
 46        self.l = Vector(0.0, 1.0, 0.0)
 47        self.u = Vector(0.0, 0.0, 1.0)
 48
 49        self._name = name
 50        self._pen = _UP_
 51        self._orientation = _ORIENTATION_INIT  # will be set to 1 or 2 later when used for residue building
 52        self._recording = False
 53        self._tape = []
 54
 55    def new(
 56        self,
 57        name: str,
 58        pos: Vector,
 59        head: Vector = Vector(1.0, 0.0, 0.0),
 60        left: Vector = Vector(0.0, 1.0, 0.0),
 61        up: Vector = Vector(0.0, 0.0, 1.0),
 62        recording=False,
 63    ) -> None:
 64        """
 65        Initialize a Turtle with a name, position, optionally heading and left.
 66
 67        :param name: Turtle's Name
 68        :param pos: Turtle's Position
 69        :param head: Turtle's Heading vector, defaults to Vector(1,0,0)
 70        :param left: Turtle's Left vector, defaults to Vector(0,1,0)
 71        :param up: Turtle's Up vector, defaults to Vector(0,0,1)
 72        :param pen: Pen state, defaults to 'up'
 73        :param recording: _description_, defaults to False
 74        """
 75        self._name = name
 76        self.pos = pos
 77        self.h = head.normalized()
 78        self.l = left.normalized()
 79        self.u = up.normalized()
 80
 81        self._position = pos.get_array()
 82        self._left = left.normalized().get_array()
 83        self._heading = head.normalized().get_array()
 84        self._up = up.normalized().get_array()
 85
 86        self._recording = recording
 87
 88    def copy_coords(self, source) -> None:
 89        """
 90        Copy the Position, Heading, Left and Up coordinate system from
 91        the input source into self. Argument: source: Turtle3D
 92        Returns: None
 93        """
 94
 95        # copy the Arrays
 96        self._position = source._position.copy()
 97        self._heading = source._heading.copy()
 98        self._left = source._left.copy()
 99        self._up = source._up.copy()
100
101        # copy the Vectors - create new ones from the source arrays
102        self.pos = Vector(source._position)
103        self.h = Vector(source._heading)
104        self.l = Vector(source._left)
105        self.u = Vector(source._up)
106
107        self._orientation = source._orientation
108
109    def reset(self) -> None:
110        """
111        Reset the Turtle to be at the Origin, with correct Heading, Left and Up vectors.
112        Arguments: None
113        Returns: None
114        """
115        self.__init__()
116
117    @property
118    def Orientation(self) -> numpy.array:
119        return self._orientation
120
121    @Orientation.setter
122    def Orientation(self, orientation):
123        assert (
124            orientation == ORIENT_BACKBONE or orientation == ORIENT_SIDECHAIN
125        ), f"Orientation must be {ORIENT_BACKBONE} or {ORIENT_SIDECHAIN}"
126        self._orientation = orientation
127
128    @property
129    def Pen(self) -> str:
130        if self._pen == _UP_:
131            return "up"
132        else:
133            return "down"
134
135    @Pen.setter
136    def Pen(self, pen) -> None:
137        if pen == "up":
138            self._pen = _UP_
139        elif pen == "down":
140            self._pen = _DOWN_
141        else:
142            self._pen = _DOWN_
143
144    @property
145    def Recording(self) -> bool:
146        return self._recording
147
148    @Recording.setter
149    def Recording(self, recording: bool):
150        self._recording = recording
151
152    def ResetTape(self) -> None:
153        self.Recording(False)
154        self._tape = []
155
156    @property
157    def Position(self) -> Vector:
158        """
159        The Turtle's Position
160
161        :return: Position
162        :rtype: Vector
163        """
164        return self.pos
165
166    @Position.setter
167    def Position(self, x, y=None, z=None) -> None:
168        """
169        Set's the Turtle's Position
170
171        :param x: X coordinate
172        :type x: float
173        :param y: Y coordinate, defaults to None
174        :type y: float, optional
175        :param z: Z coordinate, defaults to None
176        :type z: float, optional
177        :raises ValueError: Type error
178        """
179
180        if y is None and z is None:
181            # Vector, Array, list, tuple...
182            if isinstance(x, Vector):
183                self.pos = x
184                self._position = x.get_array()
185
186            elif len(x) != 3:
187                raise ValueError(
188                    "Turtle3D: x is not a vector list/tuple/array of 3 numbers"
189                )
190            else:
191                self._position = numpy.array(x, "d")
192        else:
193            # Three numbers
194            self._position = numpy.array((x, y, z), "d")
195
196        self.pos = Vector(self._position)
197        return
198
199    @property
200    def Heading(self) -> Vector:
201        """
202        Get the Turtle's Heading
203
204        :return: Heading
205        :rtype: Vector
206        """
207        return self.h
208
209    @Heading.setter
210    def Heading(self, x, y=None, z=None) -> None:
211        """
212        Set the turtle's Heading direction vector
213
214        :param x: X coordinate
215        :type x: float
216        :param y: Y coordinate, defaults to None
217        :type y: float, optional
218        :param z: Z coordinate, defaults to None
219        :type z: float, optional
220        :raises ValueError: illegal value
221        """
222
223        if isinstance(x, Vector):
224            self.h = x
225            self._heading = x.get_array()
226
227        elif y is None and z is None:
228            # Array, list, tuple...
229            if len(x) != 3:
230                raise ValueError("Turtle3D: x is not a list/tuple/array of 3 numbers")
231            self._heading = numpy.array(x, "d")
232        else:
233            # Three numbers
234            self._heading = numpy.array((x, y, z), "d")
235        self.h = Vector(self._heading)
236        return
237
238    @property
239    def Left(self) -> Vector:
240        """
241        Get the Turtle's Left direction vector
242
243        :return: Left
244        :rtype: Vector
245        """
246
247        return self.l
248
249    @Left.setter
250    def Left(self, x, y=None, z=None):
251        """
252        Set the turtle's Left direction vector
253
254        :param x: X coordinate
255        :type x: float
256        :param y: Y coordinate, defaults to None
257        :type y: float, optional
258        :param z: Z coordinate, defaults to None
259        :type z: float, optional
260        :raises ValueError: illegal value
261        """
262        if isinstance(x, Vector):
263            self.l = x
264            self._left = x.get_array()
265
266        elif y is None and z is None:
267            # Array, list, tuple...
268            if len(x) != 3:
269                raise ValueError("Turtle3D: x is not a list/tuple/array of 3 numbers")
270            self._left = numpy.array(x, "d")
271        else:
272            # Three numbers
273            self._left = numpy.array((x, y, z), "d")
274        self.l = Vector(self._left)
275        return
276
277    @property
278    def Up(self) -> Vector:
279        """
280        The Turtle's Up direction vector
281
282        :return: Up
283        :rtype: Vector
284        """
285
286        return self.u
287
288    @Up.setter
289    def Up(self, x, y=None, z=None) -> None:
290        """
291        Set the turtle's Up direction vector
292
293        :param x: X coordinate
294        :type x: float
295        :param y: Y coordinate, defaults to None
296        :type y: float, optional
297        :param z: Z coordinate, defaults to None
298        :type z: float, optional
299        :raises ValueError: illegal value
300        """
301        if isinstance(x, Vector):
302            self.u = x
303            self._up = x.get_array()
304
305        elif y is None and z is None:
306            # Array, list, tuple...
307            if len(x) != 3:
308                raise ValueError("Turtle3D: x is not a list/tuple/array of 3 numbers")
309            self._up = numpy.array(x, "d")
310        else:
311            # Three numbers
312            self._up = numpy.array((x, y, z), "d")
313        self.u = Vector(self._up)
314        return
315
316    @property
317    def Name(self) -> str:
318        """
319        Return the Turtle's Name.
320        """
321        return self._name
322
323    @Name.setter
324    def Name(self, name) -> None:
325        """
326        Set the Turtle's name.
327
328        """
329        self._name = name
330
331    def move(self, distance: float) -> None:
332        """
333        Move the Turtle distance (Å), in direction of Heading
334
335        :param distance: Amount to move (Å)
336        :type distance: float
337        """
338        self._position = self._position + self._heading * distance
339        self.pos = Vector(self._position)
340
341    def roll(self, angle) -> None:
342        """
343        Roll the Turtle about the heading vector angle degrees
344
345        :param angle: roll angle, degrees -180 -> 180
346        :type angle: float
347        """
348
349        ang = angle * math.pi / 180.0
350        cosang = numpy.cos(ang)
351        sinang = numpy.sin(ang)
352
353        lold = self._left.copy()
354        uold = self._up.copy()
355
356        self._up[0] = cosang * uold[0] - sinang * lold[0]
357        self._up[1] = cosang * uold[1] - sinang * lold[1]
358        self._up[2] = cosang * uold[2] - sinang * lold[2]
359        self._up = self.unit(self._up)
360
361        self.u = Vector(self._up)
362
363        self._left[0] = cosang * lold[0] + sinang * uold[0]
364        self._left[1] = cosang * lold[1] + sinang * uold[1]
365        self._left[2] = cosang * lold[2] + sinang * uold[2]
366        self._left = self.unit(self._left)
367
368        self.l = Vector(self._left)
369
370    def yaw(self, angle) -> None:
371        """
372        Yaw the Turtle about the up vector (180 - angle) degrees.
373        This is used when building molecules
374
375        :param angle: Yaw angle, degrees -180 -> 180
376        :type angle: float
377        """
378
379        ang = ((180 - angle) * math.pi) / 180.0
380        cosang = numpy.cos(ang)
381        sinang = numpy.sin(ang)
382
383        lold = self._left.copy()
384        hold = self._heading.copy()
385
386        self._heading[0] = cosang * hold[0] + sinang * lold[0]
387        self._heading[1] = cosang * hold[1] + sinang * lold[1]
388        self._heading[2] = cosang * hold[2] + sinang * lold[2]
389        self._heading = self.unit(self._heading)
390        self.h = Vector(self._heading)
391
392        self._left[0] = cosang * lold[0] - sinang * hold[0]
393        self._left[1] = cosang * lold[1] - sinang * hold[1]
394        self._left[2] = cosang * lold[2] - sinang * hold[2]
395        self._left = self.unit(self._left)
396        self.l = Vector(self._left)
397
398    def turn(self, angle) -> None:
399        """
400        Turn the Turtle about the up vector angle degrees.
401
402        :param angle: Turn angle, degrees
403        :type angle: float
404        """
405
406        ang = (angle * math.pi) / 180.0
407
408        cosang = numpy.cos(ang)
409        sinang = numpy.sin(ang)
410
411        heading = self._heading.copy()
412        left = self._left.copy()
413
414        self._heading[0] = cosang * heading[0] + sinang * left[0]
415        self._heading[1] = cosang * heading[1] + sinang * left[1]
416        self._heading[2] = cosang * heading[2] + sinang * left[2]
417
418        self._heading = self.unit(self._heading)
419        self.h = Vector(self._heading)
420
421        self._left[0] = cosang * left[0] - sinang * heading[0]
422        self._left[1] = cosang * left[1] - sinang * heading[1]
423        self._left[2] = cosang * left[2] - sinang * heading[2]
424        self._left = self.unit(self._left)
425        self.l = Vector(self._left)
426
427    def pitch(self, angle) -> None:
428        """
429        pitch the Turtle about the left vector angle degrees
430
431        :param angle: Pitch angle, degrees -180 -> 180
432        :type angle: float
433        """
434
435        up = self._up.copy()
436        heading = self._heading.copy()
437
438        ang = angle * math.pi / 180.0
439        cosang = numpy.cos(ang)
440        sinang = numpy.sin(ang)
441
442        self._heading[0] = heading[0] * cosang - up[0] * sinang
443        self._heading[1] = heading[1] * cosang - up[1] * sinang
444        self._heading[2] = heading[2] * cosang - up[2] * sinang
445        self._heading = self.unit(self._heading)
446        self.h = Vector(self._heading)
447
448        self._up[0] = up[0] * cosang + heading[0] * sinang
449        self._up[1] = up[1] * cosang + heading[1] * sinang
450        self._up[2] = up[2] * cosang + heading[2] * sinang
451        self._up = self.unit(self._up)
452        self.u = Vector(self._up)
453
454    def unit(self, v) -> Vector:
455        """
456        Return a unit vector for the input vector.
457
458        :param v: Input Vector
459        :return: Unit Vector
460        """
461        norm = numpy.linalg.norm(v)
462        if norm == 0:
463            return v
464        return v / norm
465
466    def orient(
467        self, position: numpy.array, heading: numpy.array, left: numpy.array
468    ) -> None:
469        """
470        Orients the turtle with Position at p1, Heading at p2 and Left at p3
471
472        :param position: Position
473        :type position: numpy.array
474        :param heading: Heading direction vector
475        :type heading: numpy.array
476        :param left: Left direction vector
477        :type left: numpy.array
478        """
479
480        self._position = position
481
482        temp = heading - position
483        self._heading = self.unit(temp)
484        self.h = Vector(self._heading)
485
486        temp = left - position
487        self._left = self.unit(temp)
488
489        temp = numpy.cross(self._heading, self._left)
490        self._up = self.unit(temp)
491        self.u = Vector(self._up)
492
493        # fix left to be orthogonal
494        temp = numpy.cross(self._up, self._heading)
495        self._left = self.unit(temp)
496        self.l = Vector(self._left)
497        return
498
499    def orient_at_residue(self, chain, resnumb, orientation) -> None:
500        """
501        Orient the turtle at the specified residue from the input Chain in
502        either orientation 1 or 2.
503
504        :param chain: list of Residues in the model, eg: chain = model['A']
505        :type chain: str
506        :param resnumb: residue number
507        :type resnumb: int
508        :param orientation: 1 - at Ca heading towards Cb with N at the left or
509            2 - at Ca heading towards C with N at the left
510        :type orientation: int
511        """
512
513        assert (
514            self._orientation == 1 or self._orientation == 2
515        ), f"orient_at_residue() requires Turtle3D to be #1 or #2"
516
517        residue = chain[resnumb]
518        assert (
519            residue is not None
520        ), f"get_backbone_from_sidechain() requires valid residue number"
521
522        # by this point I'm pretty confident I have coordinates
523        # we pull the actual numpy.array from the coordinates since that's what the
524        # Turtle3D expects
525
526        n = residue["N"].get_vector().get_array()
527        ca = residue["CA"].get_vector().get_array()
528        cb = residue["CB"].get_vector().get_array()
529        c = residue["C"].get_vector().get_array()
530
531        if orientation == ORIENT_SIDECHAIN:
532            self.orient(ca, cb, n)
533            self.set_orientation(ORIENT_SIDECHAIN)
534        elif orientation == ORIENT_BACKBONE:
535            self.orient(ca, c, n)
536            self.set_orientation(ORIENT_BACKBONE)
537        return
538
539    def orient_from_backbone(
540        self,
541        n: numpy.array,
542        ca: numpy.array,
543        cb: numpy.array,
544        c: numpy.array,
545        orientation,
546    ) -> None:
547        """
548        Orient the turtle at the specified residue from the input Chain in
549        either orientation 1 or 2.
550
551        Arguments:
552            turtle: input Turtle3D object
553            n: position of n atom
554            ca: position of ca atom
555            c: position of c atom
556            orientation:
557            1 - at Ca heading towards Cb with N at the left
558            2 - at Ca heading towards C with N at the left
559        Returns: None. Turtle internal state is modified
560        """
561
562        assert (
563            orientation == 1 or orientation == 2
564        ), f"orient_at_residue() requires Turtle3D to be #1 or #2"
565
566        _n = n.copy()
567        _ca = ca.copy()
568        _cb = cb.copy()
569        _c = c.copy()
570
571        if orientation == ORIENT_SIDECHAIN:
572            self.orient(_ca, _cb, _n)
573            self.Orientation = ORIENT_SIDECHAIN
574        elif orientation == ORIENT_BACKBONE:
575            self.orient(_ca, _c, _n)
576            self.Orientation = ORIENT_BACKBONE
577        return
578
579    def to_local(self, global_vec) -> numpy.array:
580        """
581        Returns the Turtle-centered local coordinates for input Global vector (3d)
582        """
583
584        newpos = global_vec - self._position
585        dp1 = numpy.dot(self._heading, newpos)
586        dp2 = numpy.dot(self._left, newpos)
587        dp3 = numpy.dot(self._up, newpos)
588
589        result = numpy.array((dp1, dp2, dp3), "d")
590        return result
591
592    def to_localVec(self, global_vec) -> Vector:
593        """
594        Returns the Turtle-centered local coordinates for input Global vector (3d)
595        """
596
597        res = self.to_local(global_vec)
598        return Vector(res)
599
600    def to_global(self, local) -> numpy.array:
601        """
602        Returns the global coordinates for input local vector (3d)
603        """
604
605        p1 = (
606            self._position[0]
607            + self._heading[0] * local[0]
608            + self._left[0] * local[1]
609            + self._up[0] * local[2]
610        )
611        p2 = (
612            self._position[1]
613            + self._heading[1] * local[0]
614            + self._left[1] * local[1]
615            + self._up[1] * local[2]
616        )
617        p3 = (
618            self._position[2]
619            + self._heading[2] * local[0]
620            + self._left[2] * local[1] * self._up[2] * local[2]
621        )
622
623        return numpy.array((p1, p2, p3), "d")
624
625    def to_globalVec(self, local) -> Vector:
626        """
627        Returns the global coordinates for input local vector (3d)
628        """
629        res = self.to_global(local)
630        return Vector(res)
631
632    def __repr__(self):
633        """Return Turtle 3D coordinates."""
634        return f"<Turtle: {self._name}\n Position: {self._position},\n Heading: {self._heading} \n Left: {self._left} \n Up: {self._up}\n Orientation: {self._orientation}\n Pen: {self._pen} \n Recording: {self._recording}>"
635
636    def bbone_to_schain(self) -> None:
637        """
638        Function requires turtle to be in orientation #2 (at alpha carbon,
639        headed towards carbonyl, with nitrogen on left) and converts to orientation #1
640        (at alpha c, headed to beta carbon, with nitrogen on left.
641
642        Arguments:
643            turtle: Turtle3D object in orientation #2
644
645        Returns: modified Turtle3D
646        """
647
648        # assert self._orientation == 2, f'bbone_to_schain() requires Turtle3D to be in orientation #2'
649
650        self.roll(240.0)
651        self.pitch(180.0)
652        self.yaw(110.0)
653        self.roll(240.0)
654        self.Orientation = 1  # sets the orientation flag
655
656    def schain_to_bbone(self) -> None:
657        """
658        Function requires turtle to be in orientation #1 (at alpha c, headed to beta carbon, with nitrogen on left)
659        and converts to orientation #2 (at alpha carbon, headed towards carbonyl, with nitrogen on left).
660
661        Arguments:
662            None
663        Returns: modified Turtle3D
664        """
665
666        # assert self._orientation == 1, f'schain_to_bbone() requires Turtle3D to be in orientation #1'
667
668        self.pitch(180.0)
669        self.roll(240.0)
670        self.yaw(110.0)
671        self.roll(120.0)
672        self.Orientation = 2  # sets the orientation flag
673        return
674
675
676# class definition ends
677
678if __name__ == "__main__":
679    import doctest
680
681    doctest.testmod()
682
683# End of file