Hi Bob,
a while back I attempted to document the CGO capabilities, but never finished
it. Attached is a bit of a write-up from that attempt.
Hope it helps somewhat.
Carsten
From: Robert Hanson [mailto:hans...@stolaf.edu]
Sent: Monday, December 22, 2014 12:27 PM
To: David Hall
Cc: pymol-users
Subject: Re: [PyMOL] CGOs
OK, that explains it. I think I made that one up. It was a while ago that I
worked on this. :)
I see the list at
https://github.com/speleo3/pymol/blob/master/modules/pymol/cgo.py
Thanks​, David.
Bob
# CGO documentation
This documentation will attempt to shed some light on the syntax and provide
usage examples for each of the individual CGO primitives and if possible the
drawing directives
The module PyMOL\modules\pymol\cgo.py defines the following symbols,
which seem to be the current supported primitives in PyMOL.
POINTS = 0.0
LINES = 1.0
LINE_LOOP = 2.0
LINE_STRIP = 3.0
TRIANGLES = 4.0
TRIANGLE_STRIP = 5.0
TRIANGLE_FAN = 6.0
#QUADS = 7.0
#QUAD_STRIP = 8.0
#POLYGON = 9.0
STOP = 0.0
NULL = 1.0
BEGIN = 2.0
END = 3.0
VERTEX = 4.0
NORMAL = 5.0
COLOR = 6.0
SPHERE = 7.0
TRIANGLE = 8.0
CYLINDER = 9.0
LINEWIDTH = 10.0
WIDTHSCALE = 11.0
ENABLE = 12.0
DISABLE = 13.0
SAUSAGE = 14.0
CUSTOM_CYLINDER = 15.0
DOTWIDTH = 16.0
ALPHA_TRIANGLE = 17.0
ELLIPSOID = 18.0
#SHAPE_VERTEX = 16.0
#SHAPE_COLOR = 17.0
#SHAPE_NORMAL = 18.0
FONT = 19.0
FONT_SCALE = 20.0
FONT_VERTEX = 21.0
FONT_AXES = 22.0
CHAR = 23.0
ALPHA = 25.0
QUADRIC = 26.0 # NOTE: Only works with ellipsoids and disks
CONE = 27.0
LIGHTING = float(0x0B50)
Header
======
The following header lines must be defined to import the required symbols
into the internal python interpreter:
from pymol.cgo import *
from pymol import cmd
Syntax
======
The syntax for most of the primitives seems to be of the form
PRIMITIVE ARG1 ARG2 ... ARGn
were ARG1-ARGn are the required arguments. In reality these primitives are
nothing but numbers, which represent drawing directives for the internal
OpenGL renderer and the interal raycaster. Usually they are assembled in a
list, also called a CGO object. This list can either be assembled by hand or
generated by code. In the case of "hand-assembly" into a python list the
primitives and individual arguments are comma separated. In the case of code
generated primitives the usual python list manipulation methods can be used
as well.
Example (cgo01.py from PyMOL\examples\devel)
============================================
############ cgo01.py ######################
from pymol.cgo import *
from pymol import cmd
# this is a trivial example of creating a cgo object consisting of a
# a single state
# first we create a list of floats containing a GL rendering stream
obj = [
BEGIN, LINES, # inline comments are allowed
COLOR, 1.0, 1.0, 1.0, # white color
VERTEX, 0.0, 0.0, 0.0, # origin at (0,0,0)
VERTEX, 1.0, 0.0, 0.0, # extend line one unit in x
VERTEX, 0.0, 0.0, 0.0, # origin at (0,0,0)
VERTEX, 0.0, 2.0, 0.0, # extend line two units in y
VERTEX, 0.0, 0.0, 0.0, # origin at (0,0,0)
VERTEX, 0.0, 0.0, 3.0, # extend line three units in z
END
]
# then we load it into PyMOL ads the object 'cgo01'
cmd.load_cgo(obj,'cgo01')
# move the read clipping plane back a bit to that that is it brighter
cmd.clip('far',-5)
############ END cgo01.py ######################
The whole object could have also been defined as:
obj =[2.0, 1.0, 6.0, 1.0, 1.0, 1.0, 4.0, 0.0, 0.0, 0.0, 4.0, 1.0, 0.0, 0.0,
4.0, 0.0, 0.0, 0.0, 4.0, 0.0, 2.0, 0.0, 4.0, 0.0, 0.0, 0.0, 4.0, 0.0, 0.0,
3.0, 3.0]
but much less readable.
Color
=====
The color of CGO objects is set by the COLOR command and it has the form
COLOR, r,g,b,
where r g and b are floating point numbers ranging from 0.0 to 1.0 for each
of the red, green and blue channels of a colour. You may be familiar with RGB
colourspace expressed in different ways for example as integers 0 to 255
(RGB-255) or percentages (RGB-100). So you may have to do a simple numeric
conversion to get your favourite colours.
Lines
=====
The LINES command draws a lines between a set of coordinates defined by the
VERTEX command. The colour of the lines can be changed at any time even
between vertices, so that the start and end line color can be different. The
color of the line will be interpolated between the start and end color. The
thickness of the line is set by LINEWIDTH. However there is a bug in the
implementation. The GL renderer accepts the LINEWIDTH statement only before a
BEGIN statement. The interal renderer honors the change of the linewidth
before every VERTEX pair. Note: Tapered lines are not supported by either
implementation. LINEWIDTH and COLOR are optional commands.
LINEWIDTH, w,
BEGIN, LINES,
COLOR, r, g, b,
VERTEX, x1,y1,z1,
VERTEX, x2,y2,z2,
END
Line Strips
============
The LINE_STRIP command draws a continuous line between sets of coordinates
defined by the VERTEX command. The main difference to the LINES command is
that the endpoint of the first line is automatically the start of the next
line, but the first and last point are NOT connected, see LINE_LOOP instead.
The colour of the lines can be changed at any time even between vertices, so
that the start and end line color can be different. The color of the line
will be interpolated between the start and end color.The thickness of the
line is set by LINEWIDTH. However there is a bug in the implementation. The
GL renderer accepts the LINEWIDTH statement only before a BEGIN statement.
The interal renderer honors the change of the linewidth before every VERTEX
pair. Note: Tapered lines are not supported by either implementation.
LINEWIDTH and COLOR are optional commands.
LINEWIDTH, w,
BEGIN, LINE_STRIP,
COLOR, r, g, b,
VERTEX, x1,y1,z1,
VERTEX, x2,y2,z2, ...
VERTEX, xn,yn,zn
END
###Example
################### Start cgo_linestrip_1.py ###############################
from pymol.cgo import *
from pymol import cmd
# Draw a zig-zag of yellow lines with increased brightness
# on a white background. Change the LINE_STRIP statement to LINES
# to illustrate the difference between LINES and LINE_STRIP
cmd.reinitialize()
cmd.bg_color("white")
obj = [
#LINEWIDTH, 16.0, # Global line width for all lines in GL
BEGIN, LINE_STRIP, # inline comments are allowed
COLOR, 0.0, 0.0, 0.0, # red start color
LINEWIDTH, 1.0, # works with the raycaster
]
for x in range(0,9):
y = 1.0
if x % 2 == 0:
y = -1.0
obj.extend([VERTEX, x, y, 0.0])
obj.extend([LINEWIDTH, x+1])
obj.extend([COLOR,(x+1)/9.0,(x+1)/9.0,0])
obj.append(END)
# then we load it into PyMOL
cmd.load_cgo(obj,'LineStrip')
# move the read clipping plane back a bit to that that is it brighter
cmd.clip('far',-8)
################### End cgo_linestrip_1.py ###############################
Line Loops
============
The LINE_LOOP command draws a closed set of lines between sets of coordinates
defined by the VERTEX command. The main difference to the LINES command is
that the endpoint of the first line is automatically the start of the next
line. The colour of the lines can be changed at any time even between
vertices, so that the start and end line color can be different. The color of
the line will be interpolated between the start and end color.The thickness
of the line is set by LINEWIDTH. The definition of line width for the end
point in a line overrides the line width of the start point. However there is
a bug in the implementation. The GL renderer accepts the LINEWIDTH statement
only before a BEGIN statement. The interal renderer honors the change of the
linewidth. Note: Tapered lines are not supported by
either implementation. LINEWIDTH and COLOR are optional commands.
################### Sart cgo_line_loop.py ###############################
from pymol.cgo import *
from pymol import cmd
# Draw a closed square with varying colors and line widths
# LINE_LOOP automatically connects the first point (x1,y1,z1)
# to the last point (xn,yn,zn)
cmd.reinitialize()
cmd.bg_color("white")
obj = [
LINEWIDTH, 10.0, # Global line width for all lines in GL
BEGIN, LINE_LOOP, # inline comments are allowed
COLOR, 1.0, 0.0, 0.0, # red start color
LINEWIDTH, 1.0, # works with the raycaster
VERTEX, 0.0,2.0,0.0,
COLOR, 0.0, 1.0, 0.0,
VERTEX, 2.0,0.0,0.0,
LINEWIDTH, 3.0,
COLOR, 0.0, 0.0, 1.0,
VERTEX, 0.0,-2.0,0.0,
COLOR, 0.0, 0.0, 1.0,
LINEWIDTH, 6.0,
VERTEX, -2.0,0.0,0.0
]
obj.append(END)
# then we load it into PyMOL
cmd.load_cgo(obj,'LineLoop')
w = 0.06 # cylinder width
l = 0.75 # cylinder length
h = 0.25 # cone hight
d = w * 1.618 # cone base diameter
axes = [CYLINDER, 0.0, 0.0, 0.0, l, 0.0, 0.0, w, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0,
CYLINDER, 0.0, 0.0, 0.0, 0.0, l, 0.0, w, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0,
CYLINDER, 0.0, 0.0, 0.0, 0.0, 0.0, l, w, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0,
CONE, l, 0.0, 0.0, h+l, 0.0, 0.0, d, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0,
0.0, 1.0, 1.0,
CONE, 0.0, l, 0.0, 0.0, h+l, 0.0, d, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0,
0.0, 1.0, 1.0,
CONE, 0.0, 0.0, l, 0.0, 0.0, h+l, d, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0,
1.0, 1.0, 1.0]
cmd.load_cgo(axes, 'axes')
# move the read clipping plane back a bit to that that is it brighter
cmd.clip('far',-8)
################### End cgo_line_loop.py ###############################
Spheres
=======
CGO spheres are generated by the SPHERE command.
SPHERE, x,y,z,d
where x,y,z are the coordinates of the sphere centre and d is the diameter of
the sphere. Note how a COLOR command is used to set the colour of a sphere.
As with LINES you only need a COLOR command when the colour of the next
sphere to be drawn changes.
Points
======
The POINTS command draws a point on a a coordinates defined by the VERTEX
command. The colour of the point can be changed at any time even between
vertices. The thickness of the dot is set by DOTWIDTH and can be scaled with
WIDTHSCALE. W/o setting DOTWIDTH the size of the dots is fixed, independent
of the zoom. WIDTHSCALE enables the points to be "zoomed" in the internal
renderer. However there is a bug in the implementation. The GL renderer
accepts the DOTWIDTH statement only before a BEGIN statement, the WIDTHSCALE
command seems to be entirely ignored by the GL renderer. The interal renderer
honors the change of the dot width before every VERTEX pair. Note: Points are
represented as squares in the GL window and as spheres in the internal
renderer. A width of 1.5 seems to work well as a default. The WIDTHSCALE scaling
behavior is bit unintuitive. Start with 0.1 and work your way up.
DOTWIDTH, w,
WIDTHSCALE, s,
BEGIN, POINTS,
COLOR, r, g, b,
VERTEX, x1,y1,z1,
END
Cylinder
========
------------------------------------------------------------------------------
Dive into the World of Parallel Programming! The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net
_______________________________________________
PyMOL-users mailing list (PyMOL-users@lists.sourceforge.net)
Info Page: https://lists.sourceforge.net/lists/listinfo/pymol-users
Archives: http://www.mail-archive.com/pymol-users@lists.sourceforge.net
