Add CGO functionality to documentation

doc/apidoc.rst

@@ -7,4 +7,5 @@ API Reference
   startup
   model
   convert
+  shapes
   display

doc/examples/scripts/displacement.py

@@ -0,0 +1,77 @@
+"""
+Displacement between HCN4 C-linker in apo and holo conformation
+===============================================================
+
+This example shows the extension of the C-linker '*disc*' of the HCN4
+ion channel upon binding of the ligand cAMP.
+The displacement between the apo and holo structure is clarified using
+arrows.
+"""
+
+# Code source: Patrick Kunzmann
+# License: CC0
+
+import numpy as np
+import biotite.structure as struc
+import biotite.structure.io.mmtf as mmtf
+import biotite.database.rcsb as rcsb
+import ammolite
+
+
+PNG_SIZE = (800, 800)
+CLINKER_RANGE = (522, 564+1)
+EXTENSION_FACTOR = 7
+
+########################################################################
+
+apo_structure, holo_structure = (
+    mmtf.get_structure(
+        mmtf.MMTFFile.read(rcsb.fetch(pdb_id, "mmtf")),
+        model=1, include_bonds=True
+    )
+    for pdb_id in ("7NP3", "7NP4")
+)
+
+# Holo structure is slightly longer at both ends than apo structure
+# -> select common atoms
+holo_structure = holo_structure[
+    np.isin(holo_structure.res_id, apo_structure.res_id)
+]
+
+holo_structure, _ = struc.superimpose(apo_structure, holo_structure)
+
+# Display entire ion channel
+pymol_apo = ammolite.PyMOLObject.from_structure(apo_structure)
+pymol_holo = ammolite.PyMOLObject.from_structure(holo_structure)
+pymol_apo.color("skyblue")
+pymol_holo.color("firebrick")
+pymol_apo.orient()
+ammolite.cmd.turn("z", -90)
+
+ammolite.show(PNG_SIZE)
+
+########################################################################
+
+# Show only C_linker
+clinker_mask = np.isin(apo_structure.res_id, np.arange(*CLINKER_RANGE))
+pymol_apo.hide("cartoon", ~clinker_mask)
+pymol_holo.hide("cartoon", ~clinker_mask)
+
+displacement = holo_structure.coord - apo_structure.coord
+# Make the arrows longer than the actual displacement
+# to clarify the disc extension
+displacement *= EXTENSION_FACTOR
+start_coord = apo_structure.coord
+end_coord = apo_structure.coord + displacement
+ca_mask = apo_structure.atom_name == "CA"
+ammolite.draw_arrows(
+    start_coord[clinker_mask & ca_mask],
+    end_coord[clinker_mask & ca_mask],
+    head_radius=0.5,
+    head_length=0.8
+)
+pymol_apo.orient(clinker_mask)
+pymol_apo.zoom(clinker_mask, buffer=10)
+
+ammolite.show(PNG_SIZE)
+# sphinx_gallery_thumbnail_number = 2

doc/shapes.rst

@@ -0,0 +1,16 @@
+Compiled graphics object API
+----------------------------
+
+.. currentmodule:: ammolite
+
+.. autofunction:: draw_cgo
+
+.. autofunction:: get_cylinder_cgo
+
+.. autofunction:: get_cone_cgo
+
+.. autofunction:: get_sphere_cgo
+
+|
+
+.. autofunction:: draw_arrows

doc/usage.rst

@@ -199,6 +199,47 @@ The following commands are supported as instance methods:
 - :meth:`PyMOLObject.zoom()`
 
 
+Drawing custom shapes
+---------------------
+
+In addition to visualization of molecules *PyMOL* is capable of drawing
+arbitrary geometric shapes using *compiled graphics objects* (CGOs).
+A CGO (for example a sphere) is represented by a list of floating point values.
+*Ammolite* supports a range of CGOs, that can be created conveniently using
+the following functions.
+
+- :func:`get_cylinder_cgo()`
+- :func:`get_cone_cgo()`
+- :func:`get_sphere_cgo()`
+
+One or multiple of the CGOs obtained this way can be drawn with
+:func:`draw_cgo()`.
+For example, to draw two spheres connected by a line (a cylinder) and
+a color gradient from red to blue, you can call
+
+.. code-block:: python
+
+  RED = (1, 0, 0)
+  BLUE = (0, 0, 1)
+  
+  ammolite.draw_cgo([
+      ammolite.get_sphere_cgo(
+          pos=(0, 0, 0), radius=1.0, color=RED
+      ),
+      ammolite.get_cylinder_cgo(
+          start=(0, 0, 0), end=(5, 0, 0), radius=0.5,
+          start_color=RED, end_color=BLUE
+      ),
+      ammolite.get_sphere_cgo(
+          pos=(5, 0, 0), radius=1.0, color=BLUE
+      ),
+  ])
+
+For convenience, the following shapes can be drawn, that rely on a combination
+of CGOs:
+
+- :func:`draw_arrows()`
+
 Jupyter notebook support
 ------------------------