RasCtrl API Reference
This page contains the reference for RasCtrl methods, events, and motif commands. For
more information about how to use RasCtrl API, refer to the C# sample
applications.
The following methods and events are illustrated
using C# syntax. Other programming languages, such as Visual Basic, can call
RasCtrl in the similar way.
|
|
| AlignMotif |
Align the orientation of a protein to the reference protein by aligning a motif in the protein to the corresponding motif in the reference.
|
| ExecuteCommand |
Execute the RasMol
commands and the motif commands. |
| GetMotifCaNums |
Get the atom serial numbers of the alpha carbons contained in a motif. |
| GetMotifCaPos |
Get the 3D coordinates of the alpha carbons contained in a motif. |
| Rotate |
Rotate the world coordinate of the RasCtrl component. |
|
|
| RotateEve |
The RotateEve event is invoked by a RasCtrl component when the proteins in the RasCtrl window are rotated by mouse actions. |
| StringFeedbackEve |
The StringFeedbackEve is invoked by a RasCtrl component when there is a user action, or a change of RasCtrl internal state, or an error caused by executing invalid commands. |
Motif Commands
|
| motif add |
Add a new motif structure to a RasCtrl component.
|
| motif color |
Set the color of a motif.
|
| motif label |
Set the label of a motif.
|
| motif labelcolor |
Set the label color of a motif.
|
| motif labelsize |
Set the label size of motifs.
|
| motif linewidth |
Set the line width of a motif.
|
| motif picking |
Enable/Disable picking motifs.
|
| motif remove |
Remove motifs from a RasCtrl component.
|
| motif shading |
Set whether rendering a motif
using shading effect.
|
| motif style |
Set the drawing style of a motif to be the sphere, the stick, or the triangle representation.
|
| motif transparency |
Set the transparency of a motif.
|
RasCtrl Methods
Top
AlignMotif
Align the orientation of a protein to the
reference protein by aligning a motif in the protein to the corresponding motif
in the reference. The alpha carbon positions of the amino acids that constitute the motif
are used to do alignment.
bool rasCtrl.AlignMotif(int
MolID, int ChainID, int[] MotifIdx, double[] RefPos)
Parameters
rasCtrl: A RasCtrl object.
MolID: The ID of the protein needed to be
aligned. MolID is determined by the order of loading the protein in to
the RasCtrl object. The MolID of the first loaded protein is 1.
ChainID: The ID of the chain which
contains the motif.
MotifIdx: A list of amino acid residue numbers.
These amino acids constitute the motif. Each amino acid has a alpha
carbon.
RefPos: The alpha carbon positions of the amino acids
that constitute the reference motif. Supposing MotifIdx has N
residue numbers, there will be N alpha carbons and the length of RefPos
will be 3*N. The 3D coordinate of the nth alpha carbon, n =
0...N-1, will be stored in RefPos with the index 3*n, 3*n+1,
3*n+2.
Return Value
If the alignment is successful, the return value is true. Otherwise, it is
false.
Remarks
A motif is represented by the protein ID, the chain ID, and a list of amino acid residue
numbers. This method align the motif to the reference motif. RefPos
stores the alpha carbon positions of the reference motif. The value of RefPos
can be obtained by calling GetMotifCaPos.
After alignment, the aligned motifs in a same window are overlapped. The
aligned motifs in different windows have same orientation. Refer to the MotMan
sample for more details.
Top
ExecuteCommand
Execute the RasMol
commands and the motif commands.
bool rasCtrl.ExecuteCommand(int
displayMode, string command)
Parameters
rasCtrl: A RasCtrl object.
displayMode: A binary value to indicate
whether to update the screen after executing the commands. displayMode=1
is to update; displayMode=0 is not to update.
command: A string containing commands. command
can contain multiple RasMol and motif commands. In this situation, command
is a multi-line string, in which each command starts as a new
line.
Return Value
If command is executed successfully, the return value is true.
Otherwise, it is false.
Remarks
This method are heavily used to load proteins, add motifs and set their
appearances. If an error occurs in executing command, a StringFeedbackEve
event will be invoked to return the error message to the client. Refer to the MotVis
sample to more details.
Top
GetMotifCaNums
Get the atom serial numbers of the alpha carbons
contained in a motif. A motif is composed by a group of amino acids, each of
which has an alpha carbon.
int[] rasCtrl.GetMotifCaNums(int
MolID, int ChainID, int[] MotifIdx)
Parameters
rasCtrl: A RasCtrl object.
MolID: The ID of the protein which
contains the motif. MolID is determined by the order of loading the
protein in to rasCtrl. The MolID of the first loaded protein is 1.
ChainID: The ID of the chain which
contains the motif.
MotifIdx: A list of amino acid residue numbers.
These amino acids constitute the motif.
Return Value
A list of atom serial numbers of the alpha carbons contained in a motif.
Remarks
An atom in a protein has a unique atom serial number.
The returned numbers can be used to index the alpha carbons of the
motif.
Top
GetMotifCaPos
Get the 3D coordinates of the alpha carbons
contained in a motif. A motif is composed by a group of amino acids, each of
which has an alpha carbon.
double[] rasCtrl.GetMotifCaPos(int
MolID, int ChainID, int[] MotifIdx)
Parameters
rasCtrl: A RasCtrl object.
MolID: The ID of the protein which
contains the motif. MolID is determined by the order of loading the
protein in to rasCtrl. The MolID of the first loaded protein is 1.
ChainID: The ID of the chain which
contains the motif.
MotifIdx: A list of amino acid residue numbers.
These amino acids constitute the motif.
Return Value
A list containing the 3D coordinates of the alpha carbons in a motif. Supposing
MotifIdx has N residue numbers, there will be N
alpha carbons and the length of the returned list will be 3*N. The 3D
coordinate of the nth alpha carbon, n = 0...N-1, will be
stored in the returned list with the index 3*n, 3*n+1, 3*n+2.
Remarks
This method is used together with AlignMotif
to align motifs. The alpha carbon positions of the reference motif are obtained
by calling this method. Refer to the MotMan sample for
more details.
Top
Rotate
Rotate the world coordinate of the RasCtrl
component. All proteins contained in the RasCtrl component will be
rotated.
bool rasCtrl.Rotate(double
rX, double rY, double rZ)
Parameters
rasCtrl: A RasCtrl object.
rX, rY, rZ: The rotation angles along x,
y, z axis.
Return Value
If the rotation operation is successful, the return value is true. Otherwise,
it is false.
Remarks
This method works with the RotateEve
event to synchronize the rotation of the proteins shown in different RasCtrl
windows. When a user uses the mouse to rotate proteins in a RasCtrl window,
RotateEve messages about the new angles of the world coordinate will be sent out
to the client. The client will call the Rotate method to update the world
coordinates of other RasCtrl compoents. Refer to the MolVis
sample and the MotMan sample for more
details.
RasCtrl Events
Top
RotateEve
The RotateEve event is invoked by a RasCtrl
component when the proteins in the RasCtrl window are rotated by mouse
actions.
void RotateEve(double rX, double
rY, double rZ)
Parameters
rX, rY, rZ: The rotation angles along x, y, z axis.
Remarks
This event works with Rotate
method to synchronize the rotation of the proteins shown in different RasCtrl
windows. The angles in the RotateEve messages are used as parameters of the
Rotate method. Refer to the MolVis sample and the MotMan
sample for more details.
Top
StringFeedbackEve
The StringFeedbackEve event is invoked by a
RasCtrl component when there is a user action, or a change of RasCtrl internal state,
or an error caused by executing invalid commands.
void StringFeedbackEve(string
str)
Parameters
str: the string message.
Remarks
The event can be invoked by a variety of reasons.
The client handles this event by parsing the return string. Refer to the MotVis
sample for more details.
Motif Commands
In RasCtrl, a motif is defined as a substructure of protein containing a number of atoms. This definition is more general than the definition in the
Motif Space project, which defines a motif as a substructure containing a number of amino acid residues. This generalization enables motifs be visualized in more flexible ways.
A motif defined in a RasCtrl has a unique motifID, which is a
non-negative integer.
Motifs are rendered by OpenGL, which enables
rich rendering effects. Motifs can be shown as sphere, stick, or triangle
representation. The color, transparency, and shading of a representation can be
set arbitrarily. A motif can be labeled using text.
The following commands are defined to support adding
motifs, removing motifs, and setting the appearance of motifs. Similar to the RasMol
commands, these commands are executed by calling the ExecuteCommand
method.
Similar to the RasMol commands, each motif command starts a separate line.
All motif commands start with 'motif' keyword. Keywords are case insensitive.
Spaces are used to separate key words and their arguments. Refer to the MotVis
sample about how to use the motif commands.
Top
motif add
Add a new motif structure to a RasCtrl component.
Syntax
motif add motifID molID chainID nResidue residueNumList
Add a motif containing alpha carbon atoms of the amino acids.
The ID of the added motif is motifID, a non-negative integer. The amino
acids are in the protein with the ID molID and are on the chain with ID chainID.
The number of the amino acids is nResidue. The residue numbers of the
amino acids are listed in residueNumList. Refer to the MotVis
sample.
motif add motifID molID nAomSerialNum atomSerialNumList
Add a motif containing atoms with atom serial numbers listed
in atomSerialNumList. The ID of the added motif is motifID, a
non-negative integer. The atoms are in the protein with the ID molID. The
number of the amino acids is nResidue. Refer to the third 'add'
command in the MotVis
sample.
Top
motif color
Set the color of a motif.
Syntax
motif color motifID R G B
Set the color of the motif with ID motifID. R, G, and B
are RGB color
with range [0..1]. Refer to the MotVis
sample.
Top
motif label
Set the label of a motif.
Syntax
motif label motifID string
Set the label of the motif with ID motifID to
be string. Refer to the MotVis
sample.
Top
motif labelcolor
Set the label color of a motif.
Syntax
motif labelcolor motifID R G B
Set the label color of the motif with ID motifID. R, G, and B
are RGB
color with range [0..1]. Refer to the MotVis
sample.
Top
motif labelsize
Set the label size of motifs.
Syntax
motif labelsize s
All motif labels in a RasCtrl component are in a same size. s is a positive
integer. The default label size is 14. Refer to the MotVis
sample.
Top
motif linewidth
Set the line width of a motif.
Syntax
motif linewidth motifID w
Set the line width of the motif with ID motifID. Line width determines
the thickness of the lines used in the stick representation. w is a
positive real number. The default line width is 3.0. Refer to the MotVis
sample.
Top
motif picking
Enable/Disable picking motifs.
Syntax
motif picking on/off
When picking mode is on, RasCtrl responses to motif selection and invokes StringFeedbackEve
events. Otherwise, RasCtrl ignores user actions. Refer to the MotVis
sample.
Top
motif remove
Remove motifs from a RasCtrl component.
Syntax
motif remove motifID
Remove the motif with ID motifID.
motif remove all
Remove all motifs defined in a RasCtrl component. When proteins in a RasCtrl
are removed, all motifs associated with the proteins must be removed by calling
this command. Refer to the MotVis
sample.
Top
motif shading
Set whether rendering a motif using shading
effect.
Syntax
motif shading motifID on/off
Set whether using shading effect to render the motif with ID motifID.
Refer
to the MotVis
sample.
Top
motif style
Set the drawing style of a motif to be the
sphere, the stick, or the triangle representation.
Syntax
motif style motifID sphere [radiusScale]
Set the drawing style of the motif with ID motifID to be the sphere
representation. The center of the sphere is the coordinates mean of the atoms
contained in the motif. The default radius is the minimum radius with which the
sphere can include all the atoms. radiusScale is used to scale the
default radius. radiusScale can be omitted. The default value of radiusScale
is 1.0. Refer to the first added motif in the MotVis
sample.
motif style motifID triangle N PointList
Set the drawing style of the motif with ID motifID to be the triangle
representation. PointList has N elements, each of which is the
index of a atom in the motif. There will be N/3 triangles. The vertices
of the ith triangle, i=0...N/3-1, are the (3*i)th,
(3*i+1)th, and (3*i+2)th element of PointList. Refer to the
second added motif in the MotVis
sample.
motif style motifID stick N PointList
Set the drawing style of the motif with ID motifID to be the stick
representation. PointList has N elements, each of which is the
index of a atom in the motif. There will be N/2 lines. The end points of
the ith line, i=0...N/2-1, are the (2*i)th and (2*i+1)th
element of PointList. Refer to the third added motif in the MotVis
sample.
motif style motifID none
Set the motif with ID motifID to be invisible. This can be used
to hide a motif.
Top
motif transparency
Set the transparency of a motif.
Syntax
motif transparency motifID ratio
Set the transparency of the motif with ID motifID. ratio is in the
range [0..1]. ratio = 0.0 means that the motif is totally
transparent. ratio = 1.0 means that the motif is totally opaque.
Refer to the MotVis
sample.